Guide

(click to open)

Quick Page Table of Contents

Scanning…

ezwindow System i User’s Guide

Using the Program

While the true name of the program described in this document is “ezwindow”, for readability the document will refer to the program using the name “EZWindow”.

EZWindow is a tool that allows you to easily add basic Motif user interface services to your AIX programs. Windows are defined using a gml-like window definition language, with no knowledge of Motif required. There are four basic types of calls an application can make to EZWindow; Open, Get, Update, and Close. Lets talk about the two simplest one’s first; Open, and Close. As you might guess, the Open call performs the initial display of the window. The call is passed the window definition to be used, and it returns a window id for the opened window. This id is used with all subsequent calls for that window. This allows your application to manage multiple windows simultaneously.

As you can also guess, a Close call removes the window from the display.

Next comes the Update call. This call allows the window to be modified by passing a string of update commands. The update call is discussed in detail in a later section of this document, and the supported commands are listed in the Reference Guide.

This leaves the Get call, which allows the user to interact with the window. The call waits until the user takes an exit action, typically clicking on a button, and then returns both a code indicating the type of exit action plus the value of all the window data that can be modified by the user.

Details on the Get Call

A Get call will return two types of information, the exit action code and the window data. The type of exit actionis indicated by an integer value. There are three reserved values:

Using Environment Variables
  Code      Meaning
  ----    -------
     0    User clicked on default OK button.
     4    User clicked on default Cancel button or closed the window via
          the Mwm pulldown.
     8    Timeout from Update command "Window timeout=n".

Note: If the user clicks on the “cancel” button the window is not automatically closed, and thus it is up to the application to close all windows before terminating.

Using the window definition language, other exit codes may be associated with a variety of user actions:

    Clicking on a button
    Pressing the Enter Key
    Making a selection using a pulldown menu, option list, or radio button.
    Single or Double-clicking on an item in a list.

The Get call also (always) returns all window data that is user modifiable. This includes:

    Radio button and option values
    Items selected from a list
    User-entered text.

Depending on the interface used, the data is returned either in a semi-colon delineated shell string, or a C array of character strings. The order that the data is placed in these data structures is in the order that the data appears in the window, top-to-bottom, left-to-right. It is up to the application to “understand” this order so that the data can be properly interpreted.

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, or scrolled selection list must be delineated by a “,”. Here is an example:

  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.

        $DEFLINE 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 (directly) in the initialization of a window.

Updating a Window

It is frequently desirable to update information in the window, typically after some user action. This is done by making a Update call to EZWindow, passing it an update string. An update string has the following syntax:

      update-id command

where the update-id identifies the window object to be updated and the command describes the update action to be taken. Multiple updates may be made using multiple Update calls or by including multiple update-id/command pairs in the update string, semi-colon delimited.

Here is an example of a update string that displays a message with a yellow background.

      errmsg bg=yellow; errmsg text="Please specify a printer queue"

The first step in performing window updates is to use the id option to assign a update-id to each window object you wish to update. For example, if you wanted to display a highlighted error message in a text area in the window you would first need a line like the following in your window definition to assign an id to a text area.

  :text id=errmsg

This would allow you to use a update string like the following to display the error message.

   errmsg text="You goofed!"

Here are some more examples of using the id option:

  :list lines=10 id=filelist
  :radio_buttons policy=m id=buttons1
  :entry
  size:\init=24 id=size

Note from the preceding example that the use of the id option with an entry object is an exception in that the option must be specified for individual input fields, not the entry tag itself. While certain update commands (e.g. bg=color) can be used to update any type of window object, most objects have specific update commands tailored to the function of that object. See the Reference Guide section “The Update Commands” for the complete list of general and specific commands.

Displaying Messages

A frequent use of the Update function is to display a informational message in the window; typically an errormessage. EZWindow provides some special services to make the job of displaying messages easier. This is done using :text tag with the following syntax:

  :text id=EZmsg [lines=n] [msg_fg=color] [msg_fg=color] [bell=no]

where “EZmsg” is a special (reserved) id.

Since the size of the window cannot be changed, the space for a message must be reserved in the initial window. This can be done by following the :text tag by one or more blank lines, or by using the lines option to reserve n blank text lines in the window. If the longest error message will not fit on a single line then multiple blank lines must be reserved. This requirement can best be determined empirically. (A possibility for reserving space on a single line for long messages is to use the width option on the :start tag.)

When this text field is updated with text, the “bell” will ring and the text will be displayed in the (optional) colors specified. The bell can be suppressed with the bell=no option on the tag. If the message indicates an error in some entry field you will probably also want to position the cursor in that field using the cursor=here Update command.

If the message is later updated with a blank message using the command EZmsg text=“” the original colors will be restored to the text area.

This special text area must be made available to display messages when using the type or min options on an :entry field. When a type-checking error message is displayed, EZWindow will automatically position the cursor to the field in error and clear the message when the error is corrected.

The message area may also be used to display other messages generated by your application; i.e. there will be no conflicts with the type-checking messages. If you wish to use the default bell=yes for typechecking, but disable the bell when using the area for other messages, you may temporarily disable the bell by using the Update command sequence EZmsg bell=no; EZmsg text=“message”.

Creating 2-Dimensional Window Layouts

By default, EZWindow window objects are placed in the window in a single-dimension, top-to-bottom order as their tags are encountered in the window description. If desired, more sophisticated window layouts are possible by using two additional tags:

   Table 1. Tags for Multi-Dimensional Window Layouts
   Tag                     Description
   :ltr                    Begin placing objects left-to-right until a (matching) :eltr tag is encountered.
   :ttb                    Begin placing objects top-to-bottom until a (matching) :ettb tag is encountered. This
                           tag pair must be nested inside a ltr/eltr tag pair.
Here's an example of using these tags:
:start w1
:title Title 1
:ltr
:title Title 2
:ttb
:title Title 3
:title Title 4
:ettb
:title Title 5
:eltr
:title Title 6
:stop
with the results being in the form:
                               Title 1
         Title 2               Title 3               Title 5
                               Title 4
                               Title 6

You may alternately nest ltr/ttb tag pairs as deep as you can keep track of. To do fine tuning on the layout the following tags can be used to add objects of blank space and Motif separator lines in both the vertical and horizontal direction:

Table 2. Tags for Multi-Dimensional Window Layouts
Tag                              Description                                                             Default
                                                                                                         size
:space [size=n]                  Reserve space in the vertical direction, where size=n specifies the     5
                                 vertical dimension of the blank area in pixels.
:sep [size=n]                    Reserve space in the vertical direction, including a horizontal Motif   15
                                 separator line. size=n specifies the vertical dimension of the
                                 separator area in pixels.
:hspace [size=n]                 Reserve space in the horizontal direction, where size=n specifies the   5
                                 horizontal dimension of the blank area in pixels.
:hsep [size=n]                   Reserve space in the horizontal direction, including a horizontal Motif
                                 separator line. size=n specifies the horizontal dimension of the
                                 separator area in pixels.

Dimming for Profit and Pleasure

A significant limitation of the UpdateWindow function is that the window size may not be changed from its original size. However, sections of the window may be essentially “removed” from and “added” to the window through use of “dimming”. For example, with a window definition of:

        :radio_buttons id=rb1 dim=yes
        apples,grape,pears

the radio buttons are initialized in a dimmed state, and are unavailable for use. At a later time they can be undimmed and made available using the update command:

        rb1 dim=no

With a minimal amount of creativity this feature can provide a surprisingly sophisticated interface.

It is also possible to dim/undim individual items associated with the following tags:

        :options
        :pulldown
        :radio_buttons
        :entry

This is done using the following extended syntax for the individual choices:

        choice\[alias][\options]
  where the options (which would always be used together) are:
       dim=yes      Initialize choice in "dim" (insensitive) mode.
       id=name      Name to be used to later "undim/dim" the choice with the update command "name dim=yes|no".
  Here is an example:
        :menu_bar rc=25
         :pulldown Color\\id=color dim=yes
        Red\R
        Green\G
        Blue\B
        :epulldown
        :pulldown Numbers
        One
        Two
        Three\\id=three dim=yes
        :epulldown
        :radio_buttons
        Yes\Y
        No\N\id=rb_two dim=yes
        Perhaps\P

Also, individual items in a :text_entry_group may be similarly dimmed by using the id and dim options for an item.

  Notes:
    1. Values for dimmed items will continue to be returned whenever the window is exited.
    2. Lists are not visually dimmed, due to a Motif quirk.

Using the “group” Option

If you have a large number of object that need to be dimmed/undimmed at the same time, you may use the group option to accomplish the action with a single Update command. Objects may also belong to multiple groups. For example, given:

       :radio_buttons

       one group=odd,grp1

       two group=even,grp1

       three group=odd,all

       four group=even,all

the following update commands will have the indicated action:

                          Buttons dimmed
    Update command
    odd dim=yes            one, three
    even dim=yes           two, four
    grp1 dim=yes           one, two

Dimming with Multiple Windows

Since when a window is opened it is assigned an unique id, it is possible for an application to have multiple windows open at the same time. An example of this can be seen in ezwindow.demo. However, while multiple windows may be displayed, only the window the current Get call has been made to is “active”; i.e. responsive to user input. To indicate to the user that other windows are temporarily inactive those windows should be updated with the command:

    Window dim=yes

This action will leave the window visually “dimmed” and unresponsive to input. The next Get to the window will automatically reset this condition.

Hiding Objects

The preceeding section described how window objects could be made unavailable or available to the user by using dimming. EZWindow also provides a related capability that allows you control the available of user functions by “hiding” and “unhiding” objects in the window.

First, the objects to be hidden must be contained in a scrolled area using a :scrolled_area/:escrolled_area tag pair. Second, the objects to be hidden must be grouped within :ttb/:ettb or :ltr/:eltr tag pairs, with the :ttb or :ltr tags being assigned an id using the id option. Objects may be initially hidden by using a hide=yes option with the :ttb or :ltr tags. Objects may then be later hidden or unhidden using the Update command id hide=yes|no. Additionally, the group option may be used to hide/unhide groups of objects with one update command; see “Using the group Option” in “Dimming for Profit and Pleasure” on page 24.

You may also use the frame=no option on the :scrolled_area tag to hide the frame and scrollbars normally displayed when using that tag. When using this option, if you try to “unhide” more objects then will fit in the reserved space, the scrollbars will “magically” appear to allow all objects to be accessed;

This can best be explained by example. In the following simple example, three sets of radio buttons are contained within a scrolled area, followed by a row of pushbuttons. Since the second and third :ttb tags use the hide=yes option, these objects will be initially hidden, making initially only the radio button selection of “colors” available. Clicking on any of the pushbuttons will result in the issuing of three update hide commands, unhiding the specified title and radio button set and hiding the other two, thus changing the set of buttons seen by the user.

#!/bin/ksh
  wid= ezwindow -Open w1 < $0
  while :
  do
     unused= ezwindow -Get $wid
    rc=$?
     case $rc in
           4 ) break ;;
         20 ) update_str="colors hide=no; animals hide=yes; fruits hide=yes;" ;;
         21 ) update_str="colors hide=yes; animals hide=no; fruits hide=yes;" ;;
         22 ) update_str="colors hide=yes; animals hide=yes; fruits hide=no; " ;;
    esac
     ezwindow -Update $wid "$update_str"
  done
  ezwindow -Close $wid
  exit
  :start w1 indent=3 exit_buttons=no
  :scrolled_area. height=75 width=50 frame=no
      :ttb id=colors
             :title text="Select a Color"
            :radio_buttons
            red,green,blue
      :ettb
       :ttb id=animals hide=yes
             :title text="Select an Animal"
            :radio_buttons
            cat,dog,monkey
      :ettb
       :ttb id=fruits hide=yes
             :title text="Select a Fruit"
            :radio_buttons
            apple,pear,guava
      :ettb
  :escrolled_area
  :hot_button_row
  name=Colors rc=20
  name=Animals rc=21
  name=Fruit rc=22
  name=Quit            rc=4
  :stop

Pointer Warping

Pointer warping tends to be a “religious” issue with some people, since the Motif Style Guide forbids it based on the philosophy that the user should be in control of the pointer at all times. With that said, by default EZWindow warps the pointer to the center of the window when it is opened. This warping may be inhibited in two ways:

 1. Your application may use the warp=no option on the :start tag.
 2. Users may use the following .Xdefaults entry to control all EZWindow applications.
      EZwarp: false

When appropriate, your application may cause the pointer to be warped on all (subsequent) Gets by using the Update command Window warp=yes.

Causing a Window Timeout

Frequently an application would like to obtain control if a user-initiated exit hasn’t occured after some period of time. This can be accomplished by updating the window with the command:

   Window timeout=n

where n is in seconds, and may be fractional (e.g. timeout=.5). When such a timeout occurs the Get call will exit with rc=8.

Every time control is returned to your application any pending timeout request is reset. Therefore, if a timeout is an ongoing requirement, the update command to request the timeout must be reissued before the next Get call.

Here is an Kornshell example of using a timeout to display the elapsed time in a window.

#!/bin/ksh
  seconds=0;
  wid= ezwindow -Open timeout < $0
  ezwindow -Update $wid "Window timeout=2"
  while :
  do
      unused= ezwindow -Get $wid
     rc=$?
      if (( $rc==8 ))
     then
          #-- Timeout --#
          ((seconds = seconds + 2))
          update_str="msg text=\"Elapsed time = $seconds seconds\";Window timeout=2;"
          ezwindow -Update $wid "$update_str"
     else
         break
     fi
  done
  ezwindow -Close $wid
  exit
  :start w0 width=25
  :title text="Timeout Example" font=Larger
  :text id=msg
  Waiting ...
  :exit_buttons ok=NONE
  :stop

Window Definition Indentation

To improve the readability of nested definitions you may use a indent=n option on the :start tag, where n is the number of columns of indentation to be used. The use of this option can best be explained by example:

:start w1 indent=2
:ltr
    :title Title 2
   :ttb
        :title Title 3
        :title Title 4
   :ettb
    :title Title 5
:eltr
:stop

When the indent option is specified, the indentation must be used inside all of the following:

     ltr/eltr and ttb/ettb tag pairs.
     pulldown/epulldown tag pairs.
     scrolled_area/escrolled_area tag pairs.
     if/else/endif conditional sections

Cascading Pulldowns

Cascading pulldown menus use an extension of the basic :menu_bar syntax, and are defined by nesting :pulldown/:epulldown records. The syntax can be best explained by example:

  :start my_window indent=2
  :menu_bar rc=25
  :pulldown Colors
     :pulldown Foreground
        Red
        Blue
        Green
     :epulldown
     :pulldown Background
        Red
        Blue
        Green
     :epulldown
  :epulldown
  :stop

If the syntax is not obvious at first glance, play with the pulldown example in ezwindow.demo (which the above is a subset of) and things will hopefully become clear.

When a choice is made, what is returned is the full “path”, e.g.

  Colors,Foreground,Blue

If your reaction to the returned format is “yuk”, then specify the results=brief option on the :menu_bar tag to limit the returned information. For example, let’s re-do the previous window:

   :start my_window indent=2
   :menu_bar rc=25 results=brief
  :pulldown Colors
     :pulldown Foreground
        Red\1
        Blue\2
        Green\3
     :epulldown
     :pulldown Background
        Red\4
        Blue\5
        Green\6
     :epulldown
  :epulldown
  :stop

Now what will be returned is the values 1 through 6, which would allow you to use a case statement to process the choice. Obviously, the choices must all be unique to use this option. Notice also that the indent option was used on the :start tag to make the definition (somewhat) more readable.

Automatic Save/restore Feature

The auto save/restore feature allows the user’s last- specified data to be the defaults the next time the window is displayed. The feature is triggered by the using the savefile option on the :start tag;

      :start window-id savefile=filename        (filename can be a $VAR)

Objects who’s values are to be saved must be marked by a “save” qualifier on the “id” option; e.g.

     :radio_buttons id=rb1,save
     ...
     :entry
     Name:\id=name,save

(See “Updating a Window” for more information on the id option.)

By default, values will be saved in the filename specified in the directory $HOME/.ezwsave. Optionally, the directory may be specified in the environment variable EZWSAVE. In either case the directory will be created if it does not exist. Alternatively, if the filename specified with the “savefile” option begins with a ‘/’ it will be assumed to be fully-qualified and used directly.

If you default to having the save file stored in the $HOME/.ezwsave directory, keep in mind that this directory may also be used by other EZWindow applications unknown to you. Therefore you should make the name of your save file unique; perhaps using the form “app_name.filename”. Also keep in mind that multiple windows in your application cannot “share” the same save file.

Values are restored when a window is first displayed. Values are saved:

      Standard Mode        On the return from a Get, except when the exit code is 4 (cancel/closed) or 8 (timeout).

The following values are saved/restored:

                           Value
      Tag
      :entry               text entered
      :radio_buttons       button(s) selected
      :list                item(s) selected
      :options             option selected
Notes:
  1. As a special case, when :list selected items are saved, data is also saved that will preserve the position of the
     top viewable item.
  2. If alias names are specified for radio_buttons or options, the alias names will be saved.

Manual Save/Restore Mode Alternatively, data may be saved and restored manually by omitting the savefile option on :start tag, and then using the following two Update commands.

        Window restore=filename
        Window save=filename

The rules for the filename are the same as with the previously described savefile option.

When needed, an application can obtain the current information in a save file. If the window is currently open you may use the Update comand:

  Window get_immediate=savedata

If the window is not open, depending on the interface you are using;

   shell:   -GetOther savedata filename

In all cases the information is returned in the same form as with a Get.

The :scrolled_text Search Feature

The EZWindow scrolled_text object has a facility for searching for a text string within the text “held” by the object. A search is initiated using the Update command:

   find=text

If the string is found, the window in scrolled (if necessary) to make the text visible, and the text is highlighted. If the string isn’t found the “bell” is sounded. The initial search begins at the beginning of the text. If the text is found and an addition search command is issued, the search will continue from the last-found text point. If the additional search is successful the previously-found string will be unhighlighted. Unsuccessful searches terminate at the end of the text; i.e. there is no wrap.

Additional controls over this feature are available using the update command:

  find=special

where special can have the following values, with the indicated command results:

      {top}                 Starts next search at the beginning of the text.
      {clear}               Unhighlights any highlighted text.

.Xdefaults and App-defaults files

EZWindow applications can allow users to tailor window fonts or colors by either placing entries in their .Xdefaults file, or by modifying an app-defaults file distributed with the application. To allow user customization you must specify an application name using the class option on the :start tag. For example, if the following is used:

   :start class=myapp ...

a corresponding entry in a .Xdefaults file might be:

  myapp.StandardFont: bld14

and the corresponding app-defaults file name would be Myapp.

Specifying Fonts

By default, EZWindow uses a font of &deffont. for all window text. Use of other fonts may be specified in three ways:

   1. Use of the font option on the :start tag will specify the default font for the window. Here is an example:
           :start ... font=bld17
   2. The :font tag may be used to specify a font to be used as a default font for all following window objects, or
       until another :font tag is encountered. This tag has the syntax:
           :font font-name
   3. To specify a font for a specific window object the font option can be used. This has the syntax:
           font=font-name
          Example:
              :title text="My Title" font=bld17

To make font selection easier, the following names may be used to specify a compatible set of “EZ” fonts:

       Tiny
       Small
       Standard
       Italic
       Large
       Larger
       Jumbo
    Example:
        :title text="My Title" font=Jumbo

A matching set of san-serif fonts may also be specified by appending “-sans” to the preceding list of EZfont names; e.g.

    Example:
        :title text="My Title" font=Large-sans

Fonts may be specified by hardcoding fontnames as in the preceding examples. However, you may wish users to be able to tailor the window fonts using their .Xdefaults file. EZWindow provides three techniques for accomplishing this:

 1. If your application specifies a default font using the font option on the :start tag, users may override this font
     by using the .Xdefaults entries:
          myappfont:          fontname
          myappfontlist: fontname
 2. If your application uses the pre-defined "EZ" font set, users may override these fonts by using .Xdefaults
     entries such as:
          myapp.LargeFont: fontname
     The font names specifiable in an .Xdefaults file are: FontTiny, FontSmall, FontStandard, FontItalic,
     FontLarge, FontLarger, and FontJumbo.
 3. The application may define it's own set of up to five fonts using the names: font_1, font_2, font_3, font_4,
     and font_5. The font set is defined using the :font_defs tag as follows:
           :font_defs font_1=fontname1 font_2=fontname2 ...
       This tag should precede any font-specifying tags or options in the window definition. The defined fonts can
       then be used as in the following examples:
           :font font_1=bld12
           :title font=font_1 ...
     and users may override the specified fonts using .Xdefaults entries like:
           myapp.font_1: bld17

If you are dissatisfied with the EZ font set, you may find that selecting alternate fonts is a daunting task, since there are thousands to choose from. You can get a list of all available fonts by using the xlsfonts command, and a particular font set may be displayed using the xfd command. You may want to take the time to write a simple EZWindow application that displays the font names in a scrolled list, with a double-click displaying a particular font using xfd or opening another window that shows a text sample using that font. One hint - for most window text you will want to use a mono-spaced (fixed pitch) font; look for a m (not p) in the font name.

Note: When using multiple fonts, the automatic reflow of :text text may not work correctly. If you wish the use the reflow feature you must:

    1. Use the same font for all :text objects.
    2. Assure that the default font in effect at the end of the window definition is the same one used for the text. This may require preceding the :stop tag with a :font tag.

If after following the above rules a problem still exists you will have to empirically determine the proper reflow width (in number of characters) and then specify it using the reflow_width option on the :start tag.

Specifying Colors

Window colors may be specified using two basic techniques:

   1. The default foreground and background colors may be specified by using the fg and bg options on the :start
      tag; e.g.
         :start fg=wheat bg=seagreen ...
   2. The fg and bg options may also be used to specify the color of a specific window object. Here are some
      examples:
        :text fg=navy
        :scrolled_text bg=wheat
  Shown below are additional tags used to control the color of specific areas as noted:
    Table 3. Additional Color Options
    Option                                Applicable tags                         Area controlled
    input_fg/bg=color                     :entry                                  Input
    ONcolor=color                         :radio_buttons                          Color of button when on
   bar_color=color                       :scrolled_text, :list                   Color of the "trough" for
                                                                                scrollbars
  Notes:
   1. While hex color notation is supported (e.g. bg=#FCFCFC), it should be generally avoided because is
       discourages the sharing of colors between applications, thus increasing the possibility that a requested color
       may not be available.
   2. As a special case, the color name "nonE" may be used to inhibit the setting of a color. This would only be
       used when colors were set using environment variables, and if under certain circumstances if was necessary to
       use default colors.
 To make multi-color assignment in a window easier, and to allow the specification of colors via an .Xdefaults or
 app-defaults file, the following "EZ" color names may be specified/used:
   Table 4. EZcolors
   Assignment        Option and .Xdefaults              Used for
                     Resource Name
   Automatic         pri_fg                             The default window colors
                     pri_bg
   Automatic         sec_fg                             &tentry., :scrolled_text, and :list
                     sec_bg
   Automatic         msg_fg                             EZmsg area
                     msg_bg
   Automatic         on_color                           :radio_buttons "on" color
   Manual            hi1_color                          Highlight foreground (e.g. titles)
                     hi2_color
   Manual            alt_fg                             Anything
                     alt_bg

The EZcolors are specified in your application using options on the start tag. Here is an example:

    :start main pri_fg=Wheat pri_bg=SeaGreen hi1_color=Yellow                    \
                    sec_fg=Brown sec_bg=Wheat msg_fg=Brown msg_bg=Yellow

Users may overide these specifications by using the .Xdefaults resource names in statements in their .Xdefaults file such as:

     myapp.foreground: Wheat
     myapp.background: SeaGreen
     myapp.hi1_color: White

Color names in the preceding table that have “assignment” specified as automatic will be automatically assigned to the specified areas; i.e. all &textentry., &textgrp., &textarea., :scrolled_text, and :list objects will be assigned the sec_fg and sec_bg colors.

Color names with manual assignment must be assigned using fg and bg options on specific tags. Here are some examples:

     :title fg=hi1_color
     :text fg=alt_fg bg=alt_bg

Note: The EZmsg colors may be specified either with the :start tag or the EZmsg :text tag.

Using Palettes

To make color specification even simpler, EZWindow provides a set of palettes, where each palette defines a set of EZcolors. A palette is specified by using the palette option on the :start tag; e.g.

     :start ... palette=DesertDawn

The available palettes may be viewed by using the command:

    ezwindow.demo -colors

This will display a window that will allow you to open secondary sample windows using each of the palettes supported. You will also be able to easily define and display your own custom EZcolor palettes. If you would like to use one of the standard palettes, but with minor modifications, you may specify one or more EZcolors preceding the palette specification on the :start tag; e.g.

     :start ... on_color=skyblue palette=DesertDawn

Users may also specify palettes in their .Xdefaults file by using:

    myapp.palette: DesertDawn

Colors and the AIX Desktop

X Windows has a very sophisticated (and frequently confusing) technique for specifying window resources such as colors. The AIX desktop adds additional complexity to the process. Here’s what’s needed to deal with the situation.

Default window colors are specified with EZWindow using:

     :start ...fg=color bg=color &dotdodot.

There are a number of ways for users to override these defaults. Unfortunately (in my opinion), the AIX desktop chooses to act as a “super user”, and overrides these defaults in an attempt to make all application windows have the same foreground and background colors. If as an application developer you are not satisfied with this design philosophy, and your application may be run under the desktop, you will need to do additional work to override the desktop’s override. To do this you will have to create an app-defaults file for each application. This file can reside in any directory, and must be “pointed to” by your application. Here are the steps:

  1. Assign a "class name" to each window. This is done by using the class option of the :start tag. For example,
     the following statement assigns the class name "Myapp" to the window "MyWindow"
          :start MyWindow class=Myapp ...
     By convention, if the name of an application is "myapp" then the class name is "Myapp". This capitalization
     isn't required, but if you use it, it must be used consistently, in particular for the entries in the app-defaults file.
     If you want multiple windows windows to use the same defaults you may use the same class name for each
     window.
  2. Create an "app-defaults" file with the file name equal to the class name. This file should contain statements
     similar to the following:
          ! Defaults for myapp
         Myappforeground: wheat
         Myappbackground: seagreen
  3. Copy the app-defaults file to some suitable directory, perhaps the "etc" directory corresponding to the "bin"
     directory that your application resides in. Then, in your application, before any window is opened, concatenate
     this directory (using the format shown below) to the environment variable XUSERFILESEARCHPATH and
     export the variable.
     For example, if the app-defaults file resides in:
         /whereever/etc
     the appropriate statement (in KornShell) would be:
         export XUSERFILESEARCHPATH=$XUSERFILESEARCHPATH:/whereever/etc/%N
     Please note: you must include the "/%N" as shown at the end of the path.

If a user wishes to override the defaults specified in an application’s app-defaults file, either the app-defaults file may be copied to the user’s $HOME directory and modified, or modified entries from the file may be added to the user’s .Xdefaults file.

Adding Frames and Borders

Borders

Simple borders may be added surrounding some of the window object types by using the border=yes option; e.g.

      :radio_buttons border=yes

The tags that support this option are: title, text, text_entry, and radio_buttons.

Frames

The frame option provides a more flexible alternative to the border option. It is used to add a “frame” around one or more objects in the window by adding frame=yes option to a :ttb or :ltr tag.; e.g.

      :ttb frame=yes
      whatever
      :ettb

The syntax of the frame option is:
   frame=yes[,options]
     options:
        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)
        title=text    Specifies the frame title. The title text is not double-quoted, and the character '_' should be
                      used for a blank.
The options are specified in a comma-delimited list containing no blanks.
        Example:
           :ttb frame=yes,type=out,title=My_Frame,border=5

Conditional Window Definition Processing

To allow the use of a single window definition in varying situations, sections of the definition may be included or excluded using the special :if, :else, and :endif tags. Their use can best be described by example:

:radio_buttons
:if $MY_VAR1
one
two
three
:else
red
green
blue
:endif
:if $MY_VAR2
:radio_buttons
yes
no
maybe
:endif

In the preceding example, if $MY_VAR1 is set to “TRUE” then the radio buttons one/two/three will be displayed, otherwise (if the variable is undefined or defined as other than “TRUE”) the buttons red/green/blue will be displayed. The :else clause is optional, and thus if $MY_VAR2 isn’t set to “TRUE” the second set of radio buttons won’t be displayed.

As you can see, use of these tags makes the definition quite hard to read. The readability can be improved by using the indent=n option on the :start tag, where n is the indentation to be used. Here is an example:

:start indent=4
:radio_buttons
:if $MY_VAR1
     one
     two
     three
:else
     red
     green
     blue
:endif
Notes:
  1. Use of the indent option also requires the use of of indentation in other circumstances. See “Window
     Definition Indentation” for details.
  2. Nesting of conditionals is not supported.

Using Hidden Windows for Performance

In applications where the user typically opens the same window numerous times, you can significantly decrease thetime it takes to display the window using the “hidden window” feature. This is accomplished as follows:

The window to be hidden must use the hide=yes option on the :start tag. When the window is first opened it willbe “built”, but will remain hidden. Then, when a Get is done the window will be displayed. When you are temporarily finished with the window, instead off closing it, do an Update using the command “Window hide=yes”. This will re-hide the window. Again, the next Get will display it.

Notes:
  1. Don't forget to close all hidden windows before exiting the application. In particular, you must handle the
     fact that a Get exits with rc=4 if the user closes the window using the Mwm pulldown.
  2. You will notice that the first time the window is displayed the performance improvement is minimal.
     However, on all subsequent displays the improvement will be significant (2-3X).
  3. If you want to re-display the window with an UpdateGet using the command "cursor=here", you must first do a
     separate Update using the command "Window hide=no".

Dynamic Window Definition

While many applications are satisfied by an unchanging window, frequently it is necessary to vary the composition of the window, either at creation time, or during application use. This section provides a summary of the techniques that may be used for varying the available objects in a window. Details on each technique may be found in other sections of the document.

At Creation Time

The following techniques may be used to dynamically define the composition of a window when it is first opened:

Environment variables Environment variables may be used to specify the value for tag options, thus allowing you
                        to vary, for example, the set of radio buttons displayed or the number of lines in a scrolled
                        list. Environment variables may also be used to specify the value of a line in the window
                        definition, and may be set to any valid window definition line, including a tag line. See
                        the introduction to the "Window Definition Language" in the Reference Guide for details.
:include                While the :include tag is typically used to specify the values for a list or scrolled_text
                        object, if the windowdef=yes option is specified the included information may contain
                        window definition statements. See the description of the tag in the Reference Guide for
                        details.
:if                     The :if/else/endif tag set is used to include or omit sections of the window definition
                        based on the value of an environment variable. See the description of the tag set in the
                        Reference Guide.
Dimming                 Use of the dim=yes option on a tag, or on an item in a :radio_buttons, :options, or
                        :menu_bar pulldown list, will initialize the window with the object or item visible, but
                        dimmed and inactive. See “Dimming for Profit and Pleasure” on page 24 for details.

At Post-Creation Time

The following techniques may be used to vary the objects available in a window after it has been opened:

Dimming                 Use of the dim=yes|no update command may be used to dim/undim any object or a
                        selection item from a :radio_buttons, :options, or :menu_bar pulldown list. This is the
                        most user-friendly window modification technique. See “Dimming for Profit and
                        Pleasure” on page 24 for details.
Hiding                  Use of the hide=yes|no update command may be used to make an object visible or
                        invisible. See “Hiding Objects” on page 26 for details.
scrolled_area           A scrolled_area allows different window objects to be displayed and interacted with by
                        using scrollbars to make the items visible. See the description of the tag in the Reference
                        Guide for details.
Child windows           An alternative to modifying the current window to provide additional function for the user
                        is to pop up a temporary (child) window containing the desired function. The primary
                        (parent) window should be dimmed when this is done to indicate that it is inactive. If this
                        function is to be used frequently, make the child a "hidden" window; see “Using Hidden
                        Windows for Performance” on page 39 for details..

Problems

Exceeding ARG_MAX

There is a “system-wide configuration variable” named ARG_MAX, who’s value can be displayed with the command “getconf ARG_MAX”. (On AIX 3.2.3 it is set to 24K bytes.) It limits the maximum length, in bytes, of the arguments passed to a program, including environment data. If this limit is exceeded when initializing a window using environment variables you may encounter the error “0403–027 The parameter list is too long”. If you are using the shell interface, the limit may also be exceeded when updating a window with a long update command string. In this situation there is no error message displayed, and the symptoms are varied and confusing.

  The solution to this problem are:
   1. When opening a window use the :include tag.
   2. When updating a windows use a temporary file and the :filename notation; supported by appropriate tags.

Using UpdateGet get_immediate=geometry

The UpdateGet get_immediate=geometry call returns the X-Y location of the specified window. This information is typically used to place a second window at a certain offset from an initial window. This call should be made immediately preceding the OpenWindow call for the second window.

Experience has shown that many users make this call immediately after opening the first window. This is not good practice for two reasons:

  1. The use may have moved the first window from the original location.
  2. Under certain circumstances it is possible to request the window location before it has actually been
     established. Under these circumstances, EZWindow will return the value of zero for the X and Y locations.
     Requesting this information after the user has had at least one interaction with the window will avoid this
     timing problem.

Appendix C. RPG ezWindows Colors Available

Here is a copy of the ezwindow foreground/background color schemes available.

static char *loadColor[] = {

  “white”, “black”, “grey6″, “grey14″, “grey58″, “grey64″, “grey72″, “grey80″,
  “magenta”, “red”, “MidnightBlue”, “blue”,”DarkGreen”,”green”,”SteelBlue”,
  “grey18″,”grey26″,”grey36″,”grey88″,”DarkGreen”,”grey42″,”grey50″,”cyan”,
  “turquoise”,”green”,”YellowGreen”,”wheat”,”orange”,”brown”,”firebrick”,
  “grey2″,”grey10″,”grey60″,”OrangeRed”,”LightYellow”,”violet”,”gold”,
  “purple”,”NavyBlue”,”plum”,”grey20″,”grey28″,”grey38″,”grey90″,”grey98″,
  “seashell”,”MediumBlue”,”LightCyan”,”MediumAquamarine”,”SeaGreen”,
  “LimeGreen”,”grey57″,”goldenrod”,”DarkViolet”,”grey11″,”grey13″,”grey59″,
  “MistyRose”,”NavajoWhite”,”grey91″,”SlateGrey”,”tomato”,”PaleVioletRed”,
  “cornsilk”,”DarkOrange”,”honeydew”,”moccasin”,”maroon”,”grey61″,
  “GreenYellow”,”chocolate”,”VioletRed”,”BlueViolet”,”grey99″,”RoyalBlue”,
  “grey87″,”DarkSeaGreen”,”grey25″,”LightSalmon”,”LightPink”,”pink”,
  “AntiqueWhite”,”PaleVioletRed”,”grey65″,”grey9″,”PapayaWhip”,”grey63″,
  “grey41″,”grey39″,”grey47″,”LightSteelBlue”,”grey27″,”grey15″,”grey69″,
  “MediumVioletRed”,”MediumPurple”,”MediumTurquoise”,”DodgerBlue”,
  “DarkTurquoise”,”PeachPuff”,”grey70″,”PowderBlue”,”FloralWhite”,”orchid”,
  “aquamarine”,”khaki”,”grey74″,”SlateBlue”,”grey49″,”GhostWhite”,”grey56″,
  “lavender”,”grey35″,”MediumSpringGreen”,”grey51″,”grey37″,”grey17″,
  “PaleTurquoise”,”SpringGreen”,”snow”,”grey45″,”SpringGreen”,”grey33″,
  “BlanchedAlmond”,”grey23″,”DarkSlateGrey”,”OldLace”,”salmon”,”LawnGreen”,
  “grey73″,”DarkSlateBlue”,”grey77″,”grey12″,”grey62″,”DeepPink”,”burlywood”,
  “LightSlateBlue”,”grey71″,”grey43″,”grey75″,”PaleGoldenrod”,
  “DarkOliveGreen”,”grey31″,”grey68″,”grey55″,”LightBlue”,”grey53″,”grey22″,
  “MediumOrchid”,”grey19″,”tan”,”grey54″,”MintCream”,”grey3″,”grey76″,
  “grey66″,”grey78″,”LavenderBlush”,”grey16″,”grey67″,”grey24″,”linen”,
  “LightCoral”,”grey84″,”azure”,”PaleGreen”,”ivory”,”coral”,”grey8″,”grey48″,
  “grey4″,”grey96″,”grey34″,”grey1″,”DarkSalmon”,”DarkKhaki”,”grey40″,
  “grey32″,”ForestGreen”,”LightSkyBlue”,”grey30″,”PaleGreen”,”grey7″,”sienna”,
  “LightGoldenrod”,”grey5″,”grey52″,”AliceBlue”,”CornflowerBlue”,”grey21″,
  “grey92″,”grey46″,”CadetBlue”,”grey82″,”grey44″,”grey86″,”DarkOrchid”,
  “DarkGoldenrod”,”bisque”,”thistle”,”chartreuse”,”grey94″,”grey29″,
  “HotPink”,”SandyBrown”,”DeepSkyBlue”,”LightSeaGreen”,”LemonChiffon”,
  “SaddleBrown”,”OliveDrab”,”LightGoldenrodYellow”,”IndianRed”,
  “MediumSeaGreen”,”beige”,”LightSlateGrey”,”LawnGreen”,”RosyBrown”,”azure”

};