Ref

(click to open)

Quick Page Table of Contents

Scanning…

ezwindow System i GUI Reference

Note: If you have trouble reading this screen, try the print tab for bigger font and width.

Sample Window Definition

The following GUI window definition can be stored in a library/file(mbr), IFS file, program string array, etc. See the RPG Reference Guide for interface.

# :tags must start at begin line
# to be correctly read by ezwindow    
# -------- Window definition -------
:start my_window title=GetBio exit_buttons=no \
typechk_rc=0 fg=Black bg=LightSteelBlue hide=yes
:ltr frame=yes
:text_entry_group input_fg=SlateBlue input_bg=LightGrey \
enter=exit(0)
Name:\length=40
Age: \length=2
:eltr
:ltr
:hot_button name=" Ok      "  rc=0 fg=ivory bg=DarkSlateBlue
:hot_button name=" Cancel  "  rc=4 fg=ivory bg=DarkSlateBlue
:eltr
:text id=msg fg=IndianRed lines=3
:stop

The Window Definition Language

An EZWindow window is made up of objects. These objects are defined by window definition statements made up of special tags and related data. Additional tags are used for a variety of control purposes. Here is a summary of the primary window definition tags:

     Display object tags:
        title            - A single centered line of text.
        text               - Multiple lines of text.
        scrolled_text   - Scrolled text, optionally editable.
        image                - A (bitmap) graphic image
        sep                 - A separator line.
        space               - A blank separator area.
     Input object tags:
        entry              - One or more data entry fields
        radio_buttons    - Toggle button selection list
        options            - Select value using a pull-down list
        slider            - Select numeric value using a sliding scale
        list              - Scrolled selection list
        hot_button        - Button causing exit with specified rc
        hot_key             - Key causing exit with specified rc
        hot_text          - (Hyper) text causing exit with specified rc
        menu_bar             - Pulldown menus
       file_select    -  Standard file selection box

    Other tags:
        start
        stop
        help
        include

A window definition is composed of a series of tags which generally have the following syntax:

     tag options

All options may have three formats:

  Table 1. Option Formats
  Form                    Use
  option=value            value contains no blanks.
  option="value"          value contains blanks. (Use '\"' for imbedded '"', '\\' for '\'.)
  option=$VAR             value contained in corresponding environment variable.

Here are some examples of tag options:

  :radio_buttons columns=1 default="Not sure"
  :list lines=$LINES policy=s

Any window definition line that starts with the character ! or # is treated as a comment, and lines may be continued using the character \.

Option names and keywords used for some option values are case sensitive. Many keywords have unusual case, e.g. “default=aLL”. When you see something like this it is not a documentation error; you must use the case as documented.

Note: Passing large amounts of data using an environment variable may result in an error.

 title=text    Specifies the frame title. 
               The title text is not double-quoted, and
               the character '_' should be used for a blank.
  Example:

    :ttb frame=yes,type=out,title=My_Frame,border=5

Passing Information Using Environment Variables

Shell environment variables may also be used to include dynamically generated lists and text in a window definition. Items in an option, radio button, menu_bar, or scrolled selection list must by default be delineated by a “,”. Here is are some examples:

  BUTTONS="Yes,No,Not sure"
  DEFAULT="Not sure"
  MONTHS="January,February,March,..."
   export BUTTONS DEFAULT MONTHS
  ezwindow ...
  ...
  :start ...
  ...
   :radio_buttons columns=1 default=$DEFAULT
  $BUTTONS
   :list lines=6 type=s
  $MONTHS

In a more general sense, an environment variable may be used (by itself) on any line of a menu definition; e.g.

  :text
  $TEXT1
Notes:
 1. If the variable contains a window definition tag the windowdef=yes option 
    must be specified; e.g.
        $DEF_LINE windowdef=yes
 2. Initializing a window with "large" amounts of data using environment 
    variables may result in an error.

Once a window has been opened, the EZWindow “window manager” is running as a background task, and thus does not have access to changes in environment variable values. Therefore, environment variables may only be used in the initialization of a window.

Widgets

Generic Options

The following options may be used with any tag, except where noted:

                                    Established a name to be use when updating an object
                                    or retrieving data from
      id=name[,save]
                                    an object.
      fg=color                      Specifies the foreground color of the object.
      bg=color                      Specifies the background color of the object.
      font=fontname                 Specifies the font for the object.
      dim=yes|no                    Initializes the object in a dimmed (insensitive) state.
      group=name1,[name2, ...]      Places an object in one or more "update groups".
      down=n                        Creates n (vertical) pixels of blank space above the object.
      right=n                       Creates n (horizontal) pixels of blank space to the 
                                    left of the object.
      border=yes                    Adds a single line border to the object. 
                                    Valid for: :title, :text, :entry., and
                                    :radio_buttons.
      frame=yes[,options]           Adds a shadowed frame around objects inside a 
                                    :ttb/:ettb or :ltr/:eltr tag pair by
                                    using the option on the :ttb or :ltr tag. 
                                    Supported options are:
                                    type=style      Specifies the shadow style for the frame. 
                                                    Valid values are in,
                                                    (default), out, etched_in, and etched_out.
                                    border=n        Specifies the number of pixels of blank border
                                                    inside frame (default=10)

:delims

The delims tag is used for cases where the EZWindow default delimiters conflict with particular window data.

Syntax:
  :delims d1 d2
  where:
      d1 =    the results delimiter character (default = ";"), 
              used only by the shell interface.
      d2 =    the character used as a delimiter in lists associated with 
              :radio_buttons, :options, :menu_bar, and :list
              objects. Redefining this delimiter changes both the 
              delimiter used in the returned data and the
              delimiter (possibly) used to specify list items to 
              initially define or to update the window. By default,
              the delimiter is a ','.
  Example:
    :delims < >

Notes:
 1. This tag controls all following statements until the end of the 
    window definition or until another delim tag in encountered.
 2. Alternatively, a delimiter character may be specified as a 
    hex number using the form "xhh"; e.g.
         :delims x0b x0c

:entry

The entry tag signifies that one or more data entry field definitions follow.

  Syntax:
     :entry. [enter=exit(rc)]
     prompt [\options]
     prompt [\options]
     ...
           prompt             The prompt for the input data. May be blank.
         options:
           init=text          Specifies an initial value.
           comment=text       Text will appear to the right of the input area
           length=n           Length of input area in number of characters, default = 20.
           max=n              Maximum number of characters that can be entered. 
                              This also sets default length to n.
           hide=yes|no        yes suppresses display of characters entered.
           lines=n            Provides a multi-line input area. The character "\" 
                              may be used as an EOL indicator
                              when using the init option. All lines are returned 
                              in one string, with each line delimited
                              by a Newline (012) character. 
                              Incompatible with the max, hide, and enter=exit()
                              options. (See :scrolled_text editable=yes 
                              for a similar facility.)
           editable=no        Makes field read-only.
           min=n              Minimum number of characters to be entered. 
                              (Note: this option is generally redundant
                              with the following type option.)
           spacing=           Controls the vertical spacing (in pixels) 
                              between fields (default = 0).
           type=value         Specifies data type-checking. See details below.
           input_fg=color     Specifies the foreground color of the entry area.
           input_bg=color     Specifies the background color of the entry area.
     Example:
       :entry.
       Picture ID:
       Scaling:\init=150 comment=(1-300)
       Copies:\init=$COPIES length=2

If :entry. enter=exit(rc) is specified, pressing the Enter key causes an immediate exit with an exit code of “n”, otherwise the Enter key will be ignored.

The default input mode is insert. To change the mode to replace (for all entry fields) use the editmode=overstrike option on the :start tag.

Entry Field Automatic Type Checking

The type option is used to perform type-checking on entry fields. For example, the following check assures that a whole number is entered:

    :entry.
    Width:\type=WHOLE

Supported checks are:

        Keyword                      Checks for
        NONBLANK                     Anything
        WHOLE                        A whole number
        NUMBER                       Any number; decimal or floating point format.
        HEX                          A hex number
        BINARY                       A binary number
        RANGE(n1-n2)                 Value is in the specified numeric range.
        RANGE_WHOLE(n1-n2)           Value is a whole number in the specified range.
        CHARS(n)                     Exactly n characters long.
        CHARSET(string)              All characters found in "string" 
                                     (case sensitive)
        ONE_OF(list)                 Entry is one of the items (case sensitive) 
                                     in the comma-delineated "list"; e.g.
                                     type=ONE_OF(red,green,blue).
        DATE                         Check for format: mm/dd/yy
        DATE2000                     Check for format: mm/dd/yyyyy

Checking keywords may be followed by an “OPTIONAL” qualifier to specify that the checking should only be done if something is entered in the field. Here is an example:

    :entry.
    Size:\type=RANGE(25-100),OPTIONAL

By default, checking is performed when the user takes any exit action, with the exception of a rc=4 caused by the default Cancel button or a hot_button. When an error is found the “bell” will ring, an appropriate error message will be displayed, and the cursor will be positioned at the field in error.

The space for the error messages must be reserved in the window using a special text field.

The exit conditions when error checking will be done may be explicitly specified by using the typechk_rc option on the :start tag to specify the (only) exit return code where checking should be done. For example, the following start tag specifies that checking will only be done when the window exits with rc=25.

     :start typechk_rc=25 ...

:exit_buttons

The exit_buttons tag is used to override the default names that appear on the standard OK and Cancel buttons that are displayed at the bottom of the window. Specifying a button name of “NONE” will suppress the display of that button.

Syntax:
   :exit_buttons [ok=name] [cancel=name] [help_cmd="aix-command"]

Use of the help_cmd=aix-command option will cause the specified AIX command to be executed when the help button is pressed. (Note: the command cannot write to stdout/err.) (Use of the exit_buttons=no option on the :start tag will suppress both the OK and Cancel buttons.)

:file_select

The file_select tag is used display a standard Motif file selection window to allow the selection of a file.

 Syntax:
   :file_select [help={none}] [filter=value]
   where:
        help={none}             specifies that no help button is displayed. 
                                Otherwise, a help button is displayed,
                                which when clicked will display the :help 
                                text in popup window.
        filter=value            optionally specifies a filter to be used for 
                                the file selection process. The default filter
                                is "./*".
     Example:

      :start ...

      :file_select help={none}

      :stop

When the window is exited the selected filename will be returned. Checking for a valid filename must be done by the application.

Notes:
  1. A file_select object may not be combined with other objects 
     in a window; i.e. it must be the sole object, as in
     the preceding example.
  2. Unlike other EZWindow windows, a window containing a file_select 
     object is resizable.
  3. The filter may be changed by using the update command:
                id filter=value

:font

The font tag is used to specify the font to be used for all following objects.

Syntax:
   :font=fontname

If a font option is used on a particular object it will overide the font specified using this tag. Any font available on your system may be specified. To make font selection easier, the following special names may be used to specify a reasonably compatible set of fonts:

      Tiny, Small, Standard, Italic, Large, Larger, Jumbo

:font_defs

The font_defs tag is used to specify up to five custom fonts for use in a window. These default fonts may be overridden by entries in a .Xdefaults or app-defaults file.

 Syntax:
    :font_defs font_1=font-name ... font_5=font-name
    Example:

       :font_defs font_1=bld14 font_2=bld17

:help

Use of the optional help tag will cause a Help button to be displayed at the bottom of the window. When the button is clicked, the text that follows the tag will be display in a separate window.

Syntax:
    :help [title=title] [width=n] [reflow=off] [lines=n]

The tag record may optionally specify a title for the help window, otherwise a generic title will be used. The width of the help window (in number of characters) may also be specified (default width = 60). Automatic re-formatting for the help text follows the same rules as with the text tag, with reflow=off suppressing all re-formatting. If lines=n is specified, the help text will be displayed in a scrollable window n lines deep.

Example:
    :help title="Help for Ezwindow Demo" width=40
                      Help for EZWINDOW
    This program is so EZ to use that no help text is
   required. :-)

The help text may be alternatively be displayed using two other techniques:

  1. Using rc=help option of the :hot_button tag. 
     See the tag description for details.
  2. Specifying a :menu_bar pulldown value of "helP". 
     Here is an example:
        :menu_bar rc=25
        ...
        :pulldown Help
        Help\:helP
        :epulldown

An independent help facility may be provided by using the help_cmd=aix-command option of the :exit_buttons tag.

:hot_button

The hot_button tag is used to display a button, that when clicked by the user, will cause an immediate exit from the window with a specified return code.

Syntax:
  :hot_button name=name | :filename rc=n [text=text] [text_pos=Left] [width=n]
  where:
       name=              defines the name to be displayed inside the button. 
                          If the form name=:filename is used,
                          the bitmap contained in the specified file will 
                          be displayed inside the button.
       rc=                defines the exit code when the button is clicked. 
                          (0 < rc < 256)
       text=              defines optional text to be displayed (by default) 
                          to the right of the button.
       text_pos=Left      displays optional text to the left of the button.
       width=             centers the button name in a space "n" characters wide.
Example:
   :hot_button name=Refresh rc=100 text="Refresh queue status list"

There are four special hot_button names: uP, dowN, lefT, and righT.. Use of these names will displays buttons that are small graphical arrows pointing in the specified direction.

Notes:
 1. The character "\" may be used as an EOL indicator to 
    split either the button name or text onto multiple lines.
 2. If the special case rc=help is specified the standard Help 
    button will not be displayed at the bottom of the
     window and the hot-button will act like the standard 
     Help button; i.e. when clicked it will display the :help
     text.

:hot_button_row

The hot_button_row tag is used to evenly space a row of hot_buttons across the window.

Syntax:
  :hot_button_row [width=n]
  rc=n1name=name1 [options]
  rc=n2name=name2 [options]
  ...

The ratio of button width to inter-button space is defined by the width option, and defaults to 2. Decreasing the width to (the minimum of) 1 makes the buttons narrower, which may be desirable if you only have a few buttons.

Increasing the width makes them wider, which will be needed if you have many buttons or long button names. Experiment for the best effect.

The options that may be used on each of button definition lines are the general options that can be used with the :hot_button tag; namely: fg, bg, font, id, and dim.

  Example:
    :hot_button_row
      name=Continue rc=1 bg=yellow
      name=Cancel rc=4 bg=yellow
      name=Help rc=16 bg=yellow

:hot_key

The hot_key tag is used to define a key, that when pressed by the user, will cause an immediate exit from the window with a specified return code.

Syntax:
  :hot_key key=key-name rc=n
Supported key names are:
  a-z, 0-9
  F1-F12, Escape, Return
[@
Key name are case sensitive, and Shift/Alt/Ctrl combinations are not supported.
[@
Notes:
 1. :hot_key tags must precede any object-creating tags 
    in the window definition; i.e. they should follow 
    the :start tag.
 2. Using alpha-numeric hot_keys with windows that contain 
    :entry. fields is likely to be confusing to the user.
 3. If the special case rc=help is specified the standard 
    Help button will not be displayed at the bottom of the
    window and the key will act like the standard Help button; 
    i.e. when pressed it will display the :help text.

:hot_text

The hot_text tag is used to display text, which when clicked by the user, will cause an immediate exit from the window with a specified return code. When the mouse pointer points to this text the pointer shape is changed to a “pointing hand”, indicating that the text is sensitized. This feature can be used to support simple hypertext applications.

Syntax:
  :hot_text [text=text | text=:filename] [rc=n]
  where:
       text=      defines the text to be pointer-sensitized. 
                  The character "\" may be used as an EOL indicator 
                  to split text= the text onto multiple lines. 
                  If the form text=:filename is used, the bitmap 
                  contained in the specified file will be displayed 
                  and sensitized.
       rc=        defines the exit code when the text is clicked. (0 < rc < 256)
  Example
   :ltr
     :title EZWindow uses
     :hot_text text=tags rc=18 fg=red
     :title to define a window.
   :eltr

The preceding example will display the following sentence with the word “tags” sensitized. EZWindow uses tags to define a window. When the word tags is clicked the window will exit with rc=18.

:hsep

The hsep, when used inside a :ltr/:eltr pair, tag places a vertical separator line in the window.

Syntax:
 :hsep [size=n]
     n=    horizontal dimension of the separator area in pixels, (default = 15).
Example:
 :hsep

:hspace

The hspace, when used inside a :ltr/:eltr pair, tag places a horozontal separator space in the window.

Syntax:
 :hspace [size=n]
     n=   horizontal dimension of the separator 
          area in pixels, (default = 15).
Example:
 :hspace size=60

:if/else/endif

The if/else/endif tags are used to allow conditional processing of sections of a window definition.

:image

The image tag is used to display a graphics image in the window.

  Syntax:
     :image file=filename [on_error=IGNORE|WARNING|ABORT] [rc=n]

The specified file must be in the XBM (2-color bitmap) format. The on_error option indicates the action to take when the specified file is not found, with ABORT the default. If the rc option is used, the image will be given “hyperlink” characteristics; i.e. when the mouse pointer points to the image the pointer shape is changed to a “pointing hand”, indicating that the image is sensitized. If the image is clicked the window will exit with the specified return code.

:include

The include tag is used to dynamically include the contents of another file as part of a window definition.

  Syntax:
     :include file=filename [windowdef=yes] [start=string [end=string]]

The filename may be an environment variable. The following example assumes that a radio-button name list is stored in the file identified by the environment variable MYLIST:

  Example:
    :radio_buttons columns=1
    :include $MYLIST

Note that EZWindow will not do shell filename resolution; i.e. the following statements will fail:

      # These definitions will fail!
    :include $HOME/my_file
    :include  &#771;/my_file

The solution to this situation is to do the resolution in your application and pass the full name using an environment variable.

If the start option is specified the included file lines will start with the line beginning with the specified string and end with either the last line of the file of the line starting with the string specified with the end option.

If the windowdef=yes option is specified the included file will be interpreted as containing window definition records, otherwise the data will be treated literally as pertaining to the preceding tag.

Includes may be nested up to 10 levels deep. @]

:list

The list tag is used to allow the selection of items from a scrolled selection list. The tag is followed by a list of items to be selected from.

  Syntax:
     :list [lines=n] [policy=x] [position=value] 
           [default=value] [rc=n] [click=single]
           [results=position] [results_to=filename] 
           [width=n] [header="text" [header_fg=color]]
     list-item-1
     list-item-2
     ...
     where:
       lines=                     defines the number of items to be 
                                  visible at one time. If not specified 
                                  (or specified as "*") then all items will 
                                  be displayed, otherwise the specified 
                                  number of lines will be displayed and a 
                                  vertical scrollbar will be provided.
       policy=                    defines the selection rule:
                                        s      select "zero or one" items (default)
                                        s1     select "one and only one" item
                                        m      select "zero or many" items
                                        mc     select contiguous items using 'drag'. 
                                               See details below.
       position=                  defines initial display of list:
                                        tOP           display from top (default)
                                        bottOM        display from bottom
                                        item          positions specified item 
                                                      at top of window
                                        \n            positions item number n 
                                                      at top of window
       default=                   defines initial selection of items:
                                        noNE          none selected (default, 
                                                      except for policy=s1)
                                        aLL           all items selected
                                        item          specified item selected
                                        "list"        quoted list of items, 
                                                      comma delineated. 
                                                      Note: leading blanks are honored; 
                                                      e.g. default="a, c" pre-selects 
                                                      items "a", and " c".
                                        \n            select item number n.
       rc=n                       specifies that EZWindow will immediately exit with the 
                                  specified exit code when a list item is selected 
                                  by double-clicking. The code must be < 256.
       click=single               when used with the rc, specifies that EZWindow 
                                  will immediately exit with the specified exit code 
                                  when a list item is selected by single-clicking. 
                                  Only valid for policy=s|s1.
       results=position           returns position (origin 1) of selected items 
                                  (not value).
       results_to=:filename       writes selected items to specified file 
                                  (instead of returning the item list.)
       width=n                    defines the horizontal size of the window in 
                                  number of characters. If not specified
                                  (or specified as "*") then the window 
                                  width will be the length of the longest item,
                                  otherwise the width will be as specified and 
                                  a horizontal scrollbar will be provided.
                                  (Note: due to a Motif quirk, use of this option 
                                  will not force a horizontal scrollbar
                                  unless the lines option is also used to force 
                                  the vertical scrollbar.)
       header="text"              Displays a column header text line above 
                                  the scrolled list that scrolls horizontally as
                                  the list is scrolled horizontally. To use this 
                                  option the width option must also be
                                  specified.
       header_fg=color            Specifies the foreground color of the header 
                                  text displayed using the header option.
Example:
   :list lines=6 policy=s1
  January
  February
  March
  etc.

If multiple items are selected (using “policy=m”) they will be returned in a comma-delineated list; e.g.

   March,July,November

Using policy=mc

If you have specified policy=mc, your user’s will have a variety of techniques for selecting data. Holding down the left mouse button and dragging will select multiple contiguous items and deselect any other items previously selected. To select discontiguous groups of items, do the same while holding down the Ctrl key. To extend the selection from a previous selected item or group to a new item or group, hold down the Shift key while using the mouse button. Similar techniques can be used to deselect items.

:ltr

The ltr tag, when paired with a :eltr tag, is used to position objects in a left-to-right order in the window.

:menu_bar

The menu_bar tag is used to provide user input capability using pulldown menus from a “menu bar”.

     Syntax:
        :menu_bar rc=n [results=brief]
        :pulldown name
       choice1
       choice2
        ...
        :epulldown
        ...
  Example:
    :menu_bar rc=25
     :pulldown Background Color
    Red
    Green
    Blue
    :epulldown
     :pulldown Foreground Color
    Red
    Green
    Blue
    :epulldown

When a choice is selected, EzWindow will exit with the specified return code, returning all window data. The data returned from the menu_bar tag will have the form:

    pulldown-name,choice

If the results=brief option is specified, only the item chosen will be returned; i.e.

    choice

If the window is exited using some action other than a pulldown, a null value will be returned for the pulldown. Cascading pulldown menus are also supported.

Alternate (usually simpler) “aliases” to be returned when the program exits may be specified for both the pulldown names and choices using the syntax:

    choice\alias

If you want a choice to return an empty string, specify the alias as “{blank}”. Also, if a pulldown choice is specified as “-sep-“, a visual separator will appear in the pulldown list.

  Example:
    :menu_bar rc=25
    :pulldown Color\C
    Red\R
    Green\G
    Blue\B
    -sep-
    Quit\Q
    :epulldown

Specifying Non-default Mnemonics

By default, the first letter of both pulldown and choice names are underlined when displayed in the window. The underlined characters are “mnemonics” that allow keyboard use of the menus; “Alt-character” to pulldown a menu and then “character” to select a choice. If the defaults result in conflicts, mnemonic characters may be overridden using the extended syntax:

   :pulldown name\[alias][\mnem=c]
   choice1\[alias][\mnem=c]
   choice2\[alias][\mnem=c]
   ...
   :epulldown
Here is an example:
  :pulldown File\\mnem=i
  Exit\\mnem=x
  :epulldown

:options

The options tag is used to allow the selection of 1-of-n items via a pulldown list. The tag is followed by the option list.

  Syntax:
    :options [name=text] [default=choice] [rc=n]
    choice1
    choice2
    ...
    where:
         name=       defines optional list name to be displayed to the 
                     left of the currently selected option.
         default=    defines the option that will be initially selected. 
                     If no default is specified the first option in the
                     list will be the default.
         rc=         Causes an immediate exit with the specified 
                     return code when a new value is selected.

This object provides a function identical to radio_buttons policy=s1, but in a more compact form.

Option names may contain blanks, and you may specify an “alias” name to be returned if the option is selected by using the syntax name\alias; e.g. Red\R. (If you want a choice to return an empty string, specify the alias as “{blank}”.) As a special case, if an option name is specified as “-sep-“, a visual separator will appear in the pulldown list.

    Example:
        :options name="Background color:"
      Red\R
      Green\G
      Blue
      -sep-
      White\W

:radio_buttons

The radio_buttons tag is used to allow the selection of 1-of-n items via a display of “radio buttons”. The tag is followed by the button name list.

  Syntax:
     :radio_buttons [columns=x] [default=name] [policy=x] [text=text] [text_pos=Left]
                 [rc=n] [spacing=n]
     button-name1
     button-name2
     ...
     where:
       columns=          defines the number of button columns:
                         * Align the buttons horizontally (default)
                         1 Align the buttons vertically
                         n Align the buttons horizontally with a 
                         maximum of "n" columns.
       default=          defines the name of the button that will 
                         be initially selected. If no default is 
                         specified the first button in the list 
                         will be the default. "Alternate" button 
                         names (described below) may
                         be specified.
       policy=           defines the selection rule:
                         s1 select "one and only one" button (default)
                         m select "zero or many" buttons
       text=             defines optional text to be displayed (by default) 
                         to the right of the buttons. The character
                         "\" may be used as an newline indicator to 
                         split the text onto multiple lines.
       text_pos=Left     displays optional text to the left of the buttons.
       rc=               Causes an immediate exit with the specified return 
                         code when any button is toggled.
       spacing=          Controls the vertical spacing (in pixels) between 
                         buttons (default = 4).
       ONcolor=          Specifies the color of the selected button(s).

Specifying policy=m will cause the buttons to have a different shape from “one and only one” buttons. (Note that using Motif terminology, buttons with this behavior are referred to as “check buttons”, not “radio buttons”.)

If multiple buttons are selected by the user they will be returned in a comma-delineated list; e.g.

     Fortran,Cobol,PL/I;

Button names may contain blanks, and you may specify an alias button name to be returned if the button is selected by using the syntax name\alias-name; e.g. Red\R. (If you want a choice to return an empty string, specify the alias as “{blank}”.)

  Example:
     :radio_buttons columns=1 default=yes
    yes
    no
    not sure\?

If policy=m is used, multiple default buttons may be specified using a double-quoted comma-delineated list; e.g.

     :radio_buttons policy=m default="Fortran,Cobol"

and all buttons may be set on by specifying default=aLL.

Also, at the risk of confusing the user, when using policy=s1 you may specify default=noNE.

:sep

The sep tag places a horizontal separator line in the window.

Syntax:
 :sep [size=n]
     n=    vertical dimension of the separator area in pixels, 
           (default = 15).
Example:
 :sep

:scrolled_area

The scrolled_area/escrolled_area tags are used to create a scrolled area that may contain other EZWindow objects. The syntax for the scrolled_area tag is:

     :scrolled_area height=n width=n
          where n is in pixels.

The use of the tags is best shown by example. The following window will contain a scrollable set of radio buttons labeled 1 to 20.

    :start w1
     :title Choose one of the following:
     :scrolled_area height=100 width=200
   :radio_buttons columns=1
       1, 2, 3, 4, 5, 6, 7, 8, 9,10,11,12,13,14,15,16,17,18,19,20
   :escrolled_area

Any combinations of objects may be placed in a scrolled area, and there may be multiple scrolled areas in a window. The area width will be the specified width or the width of the window; whichever is larger. To force it to a specified width which is smaller than the window width, put the area inside a :ltr/:eltr pair.

:scrolled_text

The scrolled_text tag is used to display text in a scrolled window. Both vertical and horizontal scrolling is available. While this tag can be followed by lines of text, it would typically be follow by an :include tag specifying a file that contains the text to be displayed.

  Syntax:
     :scrolled_text [lines=n] [width=n] [position=bottOM] 
                    [editable=yes] [linewrap=yes]
                    [maxlines=n]
     where:
          lines=              defines the vertical size of the window 
                              (default is 10).
          width=              defines the horizontal size of the window 
                              in number of characters. If not specified (or
                              specified as '*') the window defaults to 
                              the width of the longest text line and no
                              horizontal scroll bar is displayed.
          position=bottOM     defines the initial position of the displayed
                              text. The default is tOP.
          editable=yes        specifies that the text is editable, and will 
                              be returned to the application when the
                              window is exited. The returned text will contain
                              newline (012) characters to delineate
                              multiple lines. The editing facility is quite 
                              primitive, so this option has limited use.
          linewrap=yes        specifies that no horizontal scroll bar will 
                              be displayed, and if a text line is longer than
                              that specified using the width option, the line
                              will be split onto multiple lines.
          maxlines=n          specifies the maximum (last) lines to be displayed. 
                              (Used with Update append command.)
     Example:
        :scrolled_text width=40 lines=20
        :include /tmp/text

This object also has a search facility.

Note: Initializing this object using an environment variable containing “large” amounts data may result in an error.

Using a Secondary Message Window

This object may also be used to support a secondary “message” window to display ongoing status messages. Messages are posted to the window using the Update command ‘append=“text”’. For long-running programs you may wish to use the maxlines option to limit the number of lines that are displayable in the window.

While using colors to distinguish different classes of messages is not supported, appended text may be underlined or displayed in reverse video by using the update command “highlight=reverse|underline|none”, which will control highlighting for following appended text.

To allow the use of the scrollbars on the message window while another window is active the following special option must be specified on the :start tag for the message window:

          :start my_msg_window ...inactive=yes

An “inactive” window will not support pushbuttons (or any other object that could cause a window exit), and thus can only be closed by a Close command from the application.

:slider

The slider tag is used to allow the user to specify a numeric value using a sliding scale.

Syntax:
   :slider min=n max=n [init=n] [decimal_points=n] 
                  [orientation=vertical|horizontal]
                  [ticks=n] [name="text"] [size=n]
   where:
        min/max=               defines the minimum and maximum values selectable.
        init=                  defines the initial setting of the scale. 
                               (Default = min)
        decimal_points=        defines the number of decimal points to display
                               in the window and to return to the
                               application. For example, min=1 max=2 
                               decimal_points=2 would result in a range of
                               1.00 to 2.00 being display and returned. 
                               (Default = 0)
        orientation=           defines the orientation of the slider. 
                               (Default = vertical)
        ticks=                 specifies that when a vertical orientation is 
                               used, n tick marks are to be displayed,
                               distributed equally along the slider. See the 
                               example below for labeling the tick marks.
        name=text              defines text used to label the slider. The 
                               character "\" may be used to force newlines in
                               the text.
        size=n                 constrains the horizontal size of the slider to 
                               (approximately) n characters when used
                               with orientation=horizontal.
   Example:
      :slider min=1 max=100 init=50 name="Copies"

Motif does not supply any convenience function for labeling tick marks; and neither does EZWindow. However, it can be done with only a little spacing experimentation. Here is an example for a scale with a vertical orientation:

     :ltr
    :ttb
    :space 5
    :title 200
    :space 210
    :title 100
    :ettb
      :slider min=100 max=200 ticks=10 name="Labeled\Tick Marks\Example"
    :eltr

If the scale has a horizontal orientation, a similar do-it-yourself technique must be used, including the placement of the tick marks.

:space

The space tag places a blank horizontal separator space in the window.

Syntax:
   :space [size=n]
       n=    vertical dimension of the separator area in pixels, 
             (default = 5).
  Example:
   :space size=15

:start

The start tag identifies the beginning of a EZWindow definition.

Syntax:
   :start window_id|* [options]
Example:
   :start window_1 title="My Program" bg=SeaGreen

The following options are available:

title=text                       Window title (in top border)
ititle=text                      Icon title
class=name                       Name for .Xdefault entries or app-defaults file.
fg=color                         Window foreground color
bg=color                         Window background color
font=fontname                    Window font
width=n                          Used to specify the minimum width 
                                 (in number of characters) for the window
                                 (default = 35).
reflow_width=n                   Specifies the width used for text reflow. 
                                 Used when the automatic calculation of
                                 width is observed to be incorrect.
editmode=overstrike              Editing of entry fields done in overstrike 
                                 mode (default = insert mode). Note:
                                 mode toggle via Insert key is not supported.
savefile=filename                Specifies "autosave" filename.
keyboard=active                  Allows window to be navigated using the keyboard 
                                 Enter and tab keys. Also
                                 highlights current "focus" position. Use 
                                 "spacebar" to activate item with focus.
focus=pointer                    Causes typically annoying but occasionally 
                                 useful behavior.
                                 Window geometry; e.g. geometry=+100+150
geometry=XYvalues
icon=bitmap_filename             Specifies a bitmap file to be used as the 
                                 window icon. The foreground and
                                 background colors of the icon may be specified 
                                 using the :start options
                                 icon_fg/bg=color.
iconic=yes                       Causes the window to be initialized in 
                                 the iconic state.
dim=yes                          Causes the window to be initialized in 
                                 the dimmed (insensitive) state.
warp=no                          Don't warp pointer to window when opened.
exit_buttons=no                  Suppress display of default exit buttons 
                                 at bottom of window.
indent=n                         Specifies column indent for improved 
                                 readability of window definitions.
typechk_rc=n                     Suppresses type checking of :entry. data 
                                 unless the exit code is as specified.
hide=yes|no                      yes initializes the window in a hidden 
                                 state for performance.

:table

The :table/:etable tag pair is used to arrange objects in a window in an nxm row-column format.

 Syntax:
    :table columns=n [height=n[,m]] [spacing=n]
    :row [height=n[,m]]
    tag
    tag
    ...
    :row
    tag
    tag
    ...
    :row
    ...
    :etable
    where:
         columns=n      specifies the number of columns.
         height=n       defines the row height. The default height 
                        for each row is the height of one character of the
                        current font plus 12 pixels, which provides good 
                        default spacing for pushbutton, radio_button,
                        and (single) entry objects. The default height 
                        may be changed using the height option on the
                        :table tag. Additionally, the height for a 
                        particular row may be specified by using the height
                        option on a :row tag. In both cases, the height 
                        is specified in the form "m[,n]", where m is in
                        "number of characters", and may be fractional; i.e, 
                        "height=2.6", and "n" is the additional
                        "number of pixels".
                        Note: Text from a :text object is automatically offset 
                        4 pixels down to give a reasonable
                        alignment with objects of other types in the same row.
         spacing=n      specifies the spacing (in pixels) between columns. 
                        (Default = 3)

The table is filled left_to-right, top-to-botton. There must be the specified number of objects in each row; use the :space tag to pad a row to the required number of objects if required.

The readability of the :table definition may be improved by using the “indent=n” option on the :start tag. Here is an example, using indent=3:

    :table columns=2

    :row

          :text text="Foreground Color"

         :radio_buttons

         red,orange,yellow,green,blue,violet

    :row

          :text text="Background Color"

         :radio_buttons

         red,orange,yellow,green,blue,violet

    :etable

Note: If a table is the widest object in a window, EZWindow will be unable to make the correct calculation of the window width in order to automatically reflow text displayed with the :text tag. In this case you will have to specify the window/reflow width by using the width option on the :start tag.

:stop

Window definitions are terminated by EOF, the start tag for another window, or by use of the stop tag.

Example:
 :stop

:text

The text tag, followed by lines of text, defines a text area in the window. The text will be reflowed to match the width of the window on a paragraph basis, with a blank line delineating paragraphs. Any line starting with a blank will not be reformatted, and completely blank lines will be preserved. If the text is specified using the text option or an environment variable, a ‘\’ may be used to force a newline, and ‘\\’ is used to display a backslash.

Syntax:
   :text [width=n] [reflow=off|on] [text="text"] [lines=n]
   text
where:
        reflow=off         Suppresses reflow of text.
        width=n            Used within a ltr/eltr pair to specify 
                           the width of the text area in characters.
        text="text"        Provides an alternate method for specifying 
                           a short text string.
        lines=n            Reserves n blank text lines; 
                           typically used for EZmsg.
Example:
  :text
   These two lines will be reflowed into a single paragraph.
   These two lines will be reflowed into a single paragraph.
      These two lines will not be reformatted.
      These two lines will not be reformatted.

:text_entry

The :text_entry tag is used to provide a single data entry field. (See the :text_entry_group tag for defining multiple aligned text entry fields.)

  Syntax:
     :text_entry [options]
      options:
           init=text             Specifies an initial value.
           length=n              Length of input area in number of characters, 
                                 default = 20.
           max=n                 Maximum number of characters that can be 
                                 entered. This also sets the default length
                                 to n.
           min=n                 Minimum number of characters that can be entered.
           hide=yes|no           yes suppresses display of characters entered.
           editable=no           Makes field read-only.
           type=value            Specifies data type-checking. See details below.
     Example:
        :text_entry init=$NAME length=16

The default editing mode is insert. See the editmode option on the :start tag for details on enabling the Insert key to toggle the editing mode between insert mode and overstrike mode.

Automatic Type Checking

The type option is used to perform type-checking on :text_entry_group and :text_entry fields. For example, the following check assures that a whole number is entered:

    :text_entry type=WHOLE

Supported checks are:

        Keyword                       Checks for
        NONBLANK                      Anything
        WHOLE                         A whole number
        NUMBER                        Any number; decimal or floating point format.
        HEX                           A hex number
        BINARY                        A binary number
        RANGE(n1-n2)                  Value is in the specified numeric range.
        RANGE_WHOLE(n1-n2)            Value is a whole number in the specified range.
        CHARS(n)                      Exactly n characters long.
        CHARSET(string)               All characters found in "string" 
                                      (case sensitive)
        ONE_OF(list)                  Entry is one of the items 
                                      (case sensitive) in the 
                                      comma-delineated "list"; e.g.
                                      type=ONE_OF(red,green,blue).
        DATE                          Check for format: mm/dd/yy
        DATE2000                      Check for format: mm/dd/yyyy

Checking keywords may be followed by an “OPTIONAL” qualifier to specify that the checking should only be done if something is entered in the field. Here is an example:

    :text_entry type=RANGE(25-100),OPTIONAL

When an error is found the “bell” will ring, an appropriate error message will be displayed, and the cursor will be positioned at the field in error. The space for the error messages must be reserved in the window using a special text field; see “Displaying Messages” in the User’s Guide for details.

:text_entry_area

The :text_entry_area tag is used to provide a multi-line scrolled text entry facility.

Syntax:
   :text_entry_area lines=n width=n [position={bottom}]
   where:
        lines=n                defines the vertical size of the input area.
        width=n                defines the horizontal size of the window
                               in number of characters.
        position={bottom}      if the area is initialized, defines the 
                               initial position of the displayed text. 
                               The default is {top}.
  Example:
      :text_entry_area width=40 lines=4

If the area is to be initialized the tag may be followed by lines of text, or more typically by an :include tag specifying a file containing the initialization text.

The default editing mode is insert. See the editmode option on the :start tag for details on enabling the Insert key to toggle the editing mode between insert mode and overstrike mode.

The text that will be returned will contain newline (“\n”) characters delineating multiple lines. The delimiter may be modified using the :delims tag.

:text_entry_group

The :text_entry_group tag allows you to display multiple aligned text_entry fields with preceding field names. It is a “convenience alternative” to using the :table, :text_entry, and :text tags to do the same task.

Syntax:
   :text_entry_group
   field-name [\options]
   field-name [\options]
   ...
  where:
         field-name           Text identifying the input field. May be blank.
       options:
         init=text             Specifies an initial value.
         length=n              Length of input area in number of characters, 
                               default = 20.
         max=n                 Maximum number of characters that can be entered. 
                               This also sets the default length to n.
         min=n                 Minimum number of characters that can be entered.
         hide=yes|no           yes suppresses display of characters entered.
         editable=no           Makes field read-only.
         spacing=n             Controls the vertical spacing (in pixels) between 
                               fields (default = 0).
         type=value            Specifies data type-checking. See the :text_entry 
                               tag for details.
         fldname_fg=color      Specifies the foreground color of the field name text.
         fldname_bg=color      Specifies the background color of the field name text.
   Example:
     :text_entry_group
     Picture ID:
     Scaling:\init=150
     Copies:\init=$COPIES length=2

The default editing mode is insert. See the editmode option on the :start tag for details on enabling the Insert key to toggle the editing mode between insert mode and overstrike mode.

:title

The title tag places a centered line of text in the window.

Syntax:
  :title text or,
  :title text="text"    (Use this form when other options are specified.)
Example:
  :title EZWindow Example

The character “\” may be used to force newlines in the title.

:ttb

The ttb tag, when paired with a :ettb tag and used within a :ltr/:eltr tag pair, is used to position objects in a top-to-bottom order in the window.

The Update Commands

The available Update commands are shown in the following table.

Note: The first set of commands listed are used with the pre-defined update-id Window, and are not specific to any window object. Here is an example of use:

       Window bell=yes
    Applicable Tags          Commands                              Comments
    Window                   get_immediate=geometry                Used with UpdateGet 
                                                                   Exits immediately,
                                                                   returning the X and Y locations
                                                                   of window.
                             get_immediate=data                    Used with UpdateGet Exits immediately,
                                                                   returning all window data.
                             timeout=n                             Next Get will exit after 
                                                                   n seconds with a rc=8
                                                                   if no user exit action occurs. 
                                                                   The value may
                                                                   be fractional (e.g. ".5").
                             bell=yes                              Rings "bell". 
                                                                   (Please use sparingly!)
                             dim=yes|no                            Changes the sensitivity of the
                                                                   window.
                             raise=yes                             Assures that the window is fully
                                                                   visible.
                             save=filename                         Save/Restore window data. 
                             restore=filename                      Save/Restore Feature.
                             warp=yes|no                           Controls pointer warping for all
                                                                   subsequent Gets.
                             hide=yes                              Makes the window invisible.
                             iconic=yes|no                         Iconizes/deiconizes the window.
    any                      bg=color                              Sets background color. 
                                                                   (Not supported for
                                                                   'Window'; see FAQs in UG.)
                             fg=color                              Sets foreground color. 
                                                                   (Not supported for
                                                                   'Window'; see FAQs in UG.)
                             dim=yes|no                            yes visually "dims" the object
                                                                   and ignores any keyboard or 
                                                                   mouse input for the object.
    file_select              filter="value"                        Sets new filter value for the 
                                                                   file selection box.
    entry input field        init="text"                           Sets new initialization value 
                                                                   for input field.
                                                                   (Use the character "\" as a 
                                                                   newline character if
                                                                   the field is multi-line.)
                             cursor=here                           Positions cursor on identified 
                                                                   input field.
                             editable=yes|no                       Make input field editable or
                                                                   non-editable.
    hot_button               name=name                             Gives button new name.
                             rc=n                                  Assigns a new exit code to a button.
    image                    image=filename                        Displays a new bitmap picture
                                                                   contained in the
                                                                   specified file.
    list                     items="item1,item2,..."               Display new list. (See note 
                                                                   #1 following table.)
                             items=:filename                       Display new list from file.
                             items_updt=                           Updates specific items, where 
                                                                   the "position" of "pos1,item1
                                                                   [,pos2,item2, ...]"
                                                                   the first item is 1. 
                                                                   (Use 0 to append item.)
                             default=item                          Sets new default item.
                             default=\n                            Sets new default to item number n.
                             position=item|\n                      Positions specified item 
                                                                   (or item number) at
                                                                   the top of the viewport.
                             positionBot=item|\n                   Positions specified item 
                                                                   (or item number) at
                                                                   the bottom of the viewport.
                             position=tOP|bottOM                   Positions list at top or bottom.
                             visible=item|\n                       Assures that specified item 
                                                                   (or item number) is
                                                                   visible in the viewport.
                             policy=x                              Sets new list policy.
                             header="text"                         Replaces header text displayed 
                                                                   using the header option.
    options                  default=value                         Sets new default. "Alias" names 
                                                                   may be optionally used.
    scrolled_text            append="text"                         Appends text to end and adjusts
                                                                   position to bottom.
                             append=:filename                      Same as above, but appends 
                                                                   contents of file.
                             text="text"                           Replaces current text with new text.
                                                                   (See note #1 following table.)
                             text=:filename                        Replaces current text with new 
                                                                   text from file.
                             position=tOP|bottOM                   Positions text at top/bottom.
                             find=text                             Searches for text.
                             highlight=reverse|underline|none      Controls highlighting for 
                                                                   following appended text.
    slider                   init=n                                Set new slider value.
    title, text              text="text"                           Changes text/titles. 
                                                                   (The character "\" will
                                                                   force a newline for text fields.)
                             text=:filename                        Changes text/titles using text 
                                                                   in specified file.
    radio_buttons            default=value                         Sets new defaults. "Alias" names 
                                                                   may be optionally used. 
                                                                   You may also specify "noNE"
                                                                   or "aLL".
                             on_color=color                        Changes button "on-color".
  Notes:
   1. Using the shell interface to update objects with 
      "large" amounts data may result in an error.