----------------------------------------------------------------------
GUI Forms
----------------------------------------------------------------------

There are some cases for data collection and many cases for data display
where it makes sense to show a full form rather than a virtual form.
In ZW3D, we refer to these as GUI forms.  GUI forms are specified by 
template files similar to those used for virtual forms.  That is, 
we create an external ASCII file which describes all of the widgits 
used for data display and collection on the form.

The overall format for a GUI template is very similar to virtual template
formats.  There is a short header section followed by a series of FIELD
sections, where each field corresponds to a single widget that will 
appear on the form. As with virtual forms, GUI forms must be compiled
and loaded into Forms.Z3 (preferably a local copy).

To compile a single template file, type the following statement from
the command line of a Windows console (without the quotemarks):

      "zw3d -t template_file.t Forms.Z3".

If you have a folder which contains multiple templates then you
may compile all of them with the following command:

      "zw3d -d folder_name Forms.Z3".

The above commands must be executed from within your ZW3D user folder.
The "About..." option on the ZW3D Help pulldown menu shows the path to 
your ZW3D user folder.

----------------------
Example: GUI template
----------------------

# A line that starts with pound sign is treated as a comment

TEMPLATE=UiTestMenu
description=Test menu
function=CdTestMenu
gui_form
persistent
sole_focus
buttons = ok,cancel,reset

FIELD=Field 1
id=1
prompt=Enter form name.
wid_class=w_txt_btn
wid_rel_id = 0
wid_loc = b
options=color=16,font=3,

FIELD=Field 2
id=2
prompt=Enter form name.
wid_class=w_menu
wid_loc = r
options=format=2,height=2,width=2,btn1:cmd1,btn2:cmd2,btn3:cmd3,btn4:cmd4,icon,

FIELD=Field 3
id=3
prompt=Enter form name.
wid_class=w_opt
options=height=1,width=3,btn1:,btn2:,btn3:cmd3,

FIELD=Field 4
id=4
prompt=Enter form name.
wid_class=w_num
wid_rel_id = 0
options=format=1,width=2,step=2.5,min=-1.0,max=100.0,:$do_num,

--------------------


Format of GUI Form Templates
---------------------------------

TEMPLATE = Template name (up to 15 characters long)

description = Short command description (less than 80 char).  If you don't
               provide a description, then the form will have no title bar.

function = Optional name of function invoked when form is accepted.
           (maximum name length = 15 characters)

child (execute form as child of active form)

no_repeat (don't allow middle mouse button to cause form to repeat)

gui_form (required keyword)

persistent (keep this GUI form in memory for fast display)

sole_focus (when this form is active, it is the focus of all events)

buttons = {ok, cancel, apply, reset, help}

unit_x = {unit spacing in pixels to be used for widget's width(s)}

unit_y = {unit spacing in pixels to be used for widget's height(s)}

usr_ctl_ok (flag which allows widgets to be disabled/enabled by the user)

parent_form = Optional name of parent FORM.
              If this field is set, then when the specified form
              is taken down, then the child form will also be removed.


Form and Widget Location Commands
----------------------------------------

The following settings apply to the form and cursor placement.  All
of the values are optional since there is a default value for each
of parameters.

NOTE: The unit spacing are float values from 0.0 to 1.0.  These are
relative to the windows being referenced such that 1.0 is the
height and width width of the window.  The default values are
(0.0, 0.0).

pos_units = pixel, unit
   (units used for form & cursor placement, "unit" is the default)

form_pos = name, parameter1, parameter 2
   The are several different methods of positioning a form which gives
   great flexiblity in locating the form.

o Position relative to the base window or another form.

  There can be up to four of these settings which is enough to tie each
  edge of the form to another object.  Two settings are needed to locate
  the form relative to another object.  Additional settings would
  therefore constrain the height and width of the form using the location
  of the other objects to determine its size.

  "name" is used to specify the item upon which the form's placement
  is based with the following valid values:
     base     - position using the base window
     screen   - position using the entire screen
     disp_fix - position using the display window (fixed)
     disp_rel - position using the display window (relative)
     form   - position using the name of any form

  There are two options for anchoring forms to the display window,
  disp_fix and disp_rel:
     disp_fix  - the positioning is always fixed
     disp_rel  - the positioning is relative to the text area or sidebar
                 placement as set with the Vx.Gravity resources found in the
                 user's _config file.

  For backwards compatibility, disp is the same as disp_fix and is still
  supported.  See the IMPORTANT note below about overconstraining a form.

  "parameter1" is used to specify the type of positioning to be used
  with the following valid values:
     BT  = bottom of relative object to top of this form
     TB  = top of relative object to bottom of this form
     RL  = right of relative object to left of this form
     LR  = left of relative object to right of this form
     TT  = top of relative object to top of this form
     BB  = bottom of relative object to bottom of this form
     LL  = left of relative object to left of this form
     RR  = right of relative object to right of this form
     CTR = centers the form relative to object specified (NOTE: this
           will override all of the other contraints)

  "parameter2" is used to specify the offset from the relative object
  to the form--remember that this can either be in pixels or unit spacing
  depending on the value of "pos_units".

  DEFAULT:  The default value is to locate the form at the cursor.
     form_pos = cursor,0.0,0.0

  IMPORTANT:  Do not mix disp_rel with the other constraint types when
              overconstraining a form (ie specifying right AND left
              attachments, or top AND bottom attachments).  The following
              two examples illustrate this point:

      OK (both the top and bottom constraints use disp_rel):
         disp_rel TT 0.0
         disp_rel BB 0.0
         disp     LL 0.0

      NOT OK (the top is constrained with disp_rel, the bottom with disp):
         disp_rel TT 0.0
         disp     BB 0.0
         disp     LL 0.0

  Notice that it is ok to orthongonally mix disp_rel constraints with
  other constraint types as shown in the first example.

o Position relative to the cursor.

  This option give the ability to locate the form relative to the
  location of the cursor.

  name        - "cursor"
  parameter1 - x offset from the cursor
  parameter2 - y offset from the cursor

cur_pos = loc, fld, parameter1, parameter2
   This attribute gives the ability to jump the cursor to a specified (x,y)
   position or to a specific item within a widget on the form.  This is
   available for all of the form positioning types except for positioning
   the form based upon the location of the cursor.
   if "loc", parameter 1 = x position, and parameter 2 = y position
   if "fld", parameter 1 = widget field id, parameter 2 = item id
   DEFAULT:  no cursor jumping


Format of GUI Form Template Fields
------------------------------------------

FIELD = field label

id = integer field id (greater than zero)

class = field data class

options = Optional comma-delimited list of options

callback = Optional function that is called when the field is modified
           int function(char *template name, int field_id, int idx_data)
           Maximum name length = 15 characters.

usr_ctl  Optional flag making the widget available for the user to
         disable/enable for input, the form must be flagged in order
         for this flag to be valid.

##########################################################################
#   The following attributes define the visual representation of the field.
#   If the field won't be displayed as part of a visual form, these 
#   attributes are't required.
##########################################################################

wid_class = class of UI widget used to display the field

wid_const = {id},{constraint},{offset}
            {id} - integer id of field that widget is relative to (0=base
               form or group frame when part of a group)
            {constraint} - constraint setting that has the following
               possible values:
               BT = bottom of relative widget to top of this widget
               TB = top of relative widget to bottom of this widget
               RL = right of relative widget to left of this widget
               LR = left of relative widget to right of this widget
               TT = top of relative widget to top of this widget
               BB = bottom of relative widget to bottom of this widget
               LL = left of relative widget to left of this widget
               RR = right of relative widget to right of this widget
            {offset} - offset in unit spacing from the relative widget in
               the direction of the constraint

wid_label = {num},{alignment}
            {num} - label width in unit spacing
            {alignment} - character value for the alignment for label,
               r=right, c=center (default), l=left

#   If "wid_label" isn't specified, then the width will be set to the width
#  of the text used in the setting "FIELD = {field label}" and the align-
#   ment is center.  You may set one of the values without setting the
#  other by simply leaving that field empty.  However, make sure you
#  include the comma when setting the alignment.

wid_group = {integer id of group to which the widget belongs}

#   If "wid_group" isn't specified, it is set to "0" by default, which means
#   the widget doesn't belong to any group.

The {sole_focus} Option
------------------------------

If the "sole_focus" keyword is included in a GUI form definition, all 
other windows are de-activated while the specified form's window is active.  
It is the only form that can receive or generate events (i.e. it is the 
"sole focus" of all events).


The {buttons} Option
---------------------------

The "buttons" keyword is followed by a comma-delimited list of the types
of buttons shown at the bottom of the form (ok, apply, cancel, reset, help).
Up to four out of the five button types may be used.

If the "buttons" option is not included in the form definition, the form
will not have any buttons at the buttom, which means the application is
responsible for taking it down.


The {callback} Option
----------------------------

The "callback" keyword is used to define a function that is automatically
called each time input is added to a field.  You can use this function to
check the field's input and take appropriate action if necessary.

The callback function has the following arguments:

   int callback_function
   (
   char *template name,    /* I: name of active form */
   int field_id,             /* I: id of active field */
   int idx_data            /* I: index of form's VDATA object */
   )

Return 1 from the callback function if you want the Input Manager to
stay at the active field.  Otherwise, return 0 and the Input Manager
will process the field as usual.

For example, if the input associated with the field isn't what you're
looking for, you could force the Input Manager to re-execute the field.

Use "VxApiEventString(char *string)" to send null-terminated command strings
to the Input Manager from your callback function.  For instance, 
"VxApiEventString("@2")" tells the Input Manager to go to field number two
of the active template.  In this particular case, "field number" is not the
same as the "field id" included in the template definition.  "Field number"
refers to the field's sequence number within the template definition, 
numbered from zero. 

---------------------------------------------------------------------------
Widget Classes and Options
---------------------------------------------------------------------------

1. class = "w_num"
------------------
   format=0         numeric input without up/down arrows (default).
         =1         numeric input with up/down arrows
   width=num        numeric input width in unit spacing
   col=num          number of characters displayed in numeric input area
   step=value       step size
   sig_dig=num      number of digits to the right of the decimal place
                    with 0 being an integer value
   min=value        lower bound on input
   max=value        upper bound on input
   num_char=num     maximum number of characters allowed on input
   no_edit          Disable widget's callback activation while text field
                    is being edited. 
   expression       enable expression input

   (item 0 = label)
   (item 1 = numeric input area)


2. class = "w_slider"
---------------------
   format=0         slider value on top
         =1         slider value on left
         =2         slider value on right
   width=num        slider width in unit spacing
   txtWidth=num     slider input area width in unit spacing
   col=value        initial width of the text window as number of characters
   num_char=value   maximum length of string allowed as input from the keyboard
   min=value        lower bound on input
   max=value        upper bound on input
   step=value       step size
   sig_dig=num      number of digits to the right of the decimal place
                    with 0 being an integer value

   (item 0 = label)
   (item 1 = slider)
   (item 2 = slider input area)


3. class = "w_txt_in"
---------------------
   width=num        text width in unit spacing
   height=num       text height in unit spacing
   row=num          number of lines in text input area
   col=num          number of characters displayed in text input area
   num_char=num     maximum number of characters allowed on input
   on_char          activate callback for each character entered
   passwd           displays all characters as an asterisk (*) as they are
                    typed into the text control.
   text=string      initial text string (up to 128 characters)
   name             set the maximum number of characters allowed to
                    sizeof(vxName)-1


   (item 0 = label)
   (item 1 = text input area)


4. class = "w_txt_out"
----------------------
   width=num        text width in unit spacing
   height=num       text height in unit spacing
   col=num          number of characters displayed in text output area
   row=num          number of lines in text output area
   name             set the maximum number of characters allowed to
                    sizeof(vxName)-1

   (item 0 = label)
   (item 1 = text output area)


5. class = "w_txt_btn"
----------------------
   format=0         widget without toggle button (default)
         =1         widget with toggle button
   menu=string      name of menu to be displayed when button is pressed OR...
   command=string   name of command string to be sent to the application OR...
   form=string      name of form to be displayed when button is pressed
   width=num        text width in unit spacing
   col=num          number of characters displayed in text input area
   num_char=num     optional maximum number of characters allowed on input
   on_char          activate callback for each character entered
   name             set the maximum number of characters allowed to
                    sizeof(vxName)-1
   icon             icon labels (default is text labels)

   (item 0 = toggle button)
   (item 1 = button itself)
   (item 2 = text input area)


6. class = "w_txt_lbl"
----------------------
   format=0         widget without toggle button (default)
         =1         widget with toggle button
   width=num        text width in unit spacing
   col=num          number of characters displayed in text input area
   num_char=num     optional maximum number of characters allowed on input
   no_edit          prevents the user from entering or editing text
   name             set the maximum number of characters allowed to
                    sizeof(vxName)-1

   (item 0 = toggle button)
   (item 1 = label)
   (item 2 = text input area)


7. class = "w_list"
-------------------
   format           0-scrollbars displayed on demand
                    1-scrollbars are always displayed
   width=num        list width in unit spacing
   height=num       list height in unit spacing
   col=num          number of characters displayed in list
   row=num          number of rows in each column
   non_exc          non-exclusive buttons (default is exclusive) 
   vert             label is above the options (default) OR...
   horz             label is to the right of the options
   dbl_clk          allow left double-click, middle and right mouse button
                    clicks on the list widget items. To distinguish which
                    action caused the callback, we have overloaded the current
                    parameters to the callback such that:
                       o left double-click:   item{0
                       o right button click:  field{0
                       o middle button click: item=0
                       o left button click:   field}0 and item}0
   no_hilite        remove the highlight from the selected item

   (item 0 = label)
   (item N = Nth item in scrolling list)

   Use uiListMaskGet() to get a bit mask that indicates whether the SHIFT
   or CTRL key was held down during the last left-click on a scrolling list
   item.


8. class = "w_opt"
------------------
   format=0         radio buttons (default format)
         =1         text/icon buttons
         =2         buttons on "options" popup menu   
   row=num          number of rows
   col=num          number of columns (ignored for format=2)
   width=num        button width in unit spacing (for format=0,1)
   non_exc          non-exclusive buttons (default is exclusive) 
   vert             label is above the options (default) OR...
   horz             label is to the right of the options
   label:command:state label/command/state {on|off}
                    command may be undefined, but still put ':' after label
                    state only used when format=0 and non_exc are both used
   icon             icon labels (default is text labels)
   align=r,c,l      allignment for buttons, r=right, c=center (default), l=left
                    (for format=1)

   (item 0 = label)
   (item N = Nth option button)


9. class = "w_btns"
-------------------
   row=num           number of rows
   col=num           number of columns
   width=num         button width in unit spacing
   label:string:cmd  label/name of command string to be sent OR...
   label:string:menu label/name of menu to be displayed OR...
   label:string:form label/name of form to be displayed when button is pressed
                     (command may be undefined, but still put ':' after label)
   icon              icon labels(default is text labels)
   align=r,c,l       allignment for buttons, r=right, c=center(default), l=left

   (current maximum is 32 total buttons)

   (item N = Nth menu button)


10. class = "w_group"
---------------------


11. class = "w_label"
----------------------
   icon             icon labels (default is text labels)
   width=num        label width in unit spacing
   height=num       label height in unit spacing
   text=string      label string (up to 128 characters)

   (item 0 = label)

   Example:
   FIELD=text
   wid_class=w_label
   wid_label=60,l ---} width and alignment
   or
   wid_label=60 ----} width only
   or
   wid_label=,c ----} alignment only

   FIELD=hatch01.xpm
   wid_class=w_label
   options=icon,width=50,height=50, ---} label type + width + height

   uiFormItemSet() -} Set label text/icon
   uiFormItemGet() -} Get label text/icon

12. class = "w_separator"
-------------------------
   format=0         no line (default)
         =1         single line
         =2         double line
         =3         single dashed line
         =4         double dashed line
         =5         shadow etched in
         =6         shadow etched out
         =7         shadow etched in (dashed)
         =8         shadow etched out (dashed)
   horz             separator is horizontal (default) OR...
   vert             separator is vertical

13. class = "w_color"
---------------------
   format=0         display the standard color dialog
         =1         bypass the standard color dialog
   width=num        color box width in unit spacing
   height=num       color box height in unit spacing
   vert             label is above the options (default) OR...
   horz             label is to the right of the options

   (item 0 = label)
   (item 1 = color box)

14. class = "w_tree"
--------------------
   width=num        tree width in unit spacing
   height=num       tree height in unit spacing
   vert             label is above the options (default) OR...
   horz             label is to the right of the options
   drag_drop        enable drag&drop functionality
   onNode           activates callback when node expands or collapses
   image=ICON####   image list

   (item 0 = label)
   (item 1 = tree widget (all one entity))

15. class = "w_combo"
--------------------
   width=num        combo width in unit spacing
   height=num       tree height in unit spacing
   row=num          number of lines in text area
   col=num          number of characters displayed in text area
   label:           combo's item (make sure to put ':' after the item label)

   (item 0 = label)
   (item 1 = combo area)

16. class = "w_tab"
-------------------
   format=0             single line
         =1             multi line
   label/icon.bmp:id:hide{1,2,3}
                        page text/page icon:page id:hide option
                        refer to uiFormFieldVis for additional info
   image=ICON.bmp       image list

   (item N = Nth tab page)

   Example:
   options=tab1:100,tab2:200,image=imagelist.{xpm|bmp},
   options=icon1.{xpm|bmp}:100,icon2.{xpm|bmp}:200,
   options=icon1.{xpm|bmp}:100:hide1,icon2.{xpm|bmp}:200,hide2,

17. class = "w_progress"
------------------------
   format=0         filled with blocks
         =1         gradual and smooth filling
   width=num        progress control width in unit spacing
   min=value        lower bound on input
   max=value        upper bound on input
   step=value       step size

   (item 0 = label)
   (item 1 = progress area)


18. class = "w_table"
---------------------
   format=0         row + column caption
         =1         row caption
         =2         column caption
         =3         no caption
   row=num          number of rows (default=2)
   col=num          number of columns (default=2)
   width=num        table width in unit spacing (default=100)
   height=num       table height in unit spacing (default=100)
   editable=num     indicates if table is editable (default=1)
   align=r,c,l      alignment for table's cell
                    r=right, c=center (default), l=left

   utility macros:
   VmUiRC2Item ---} converts row and column info to item info
   VmUiItem2RC ---} converts item info to row and column info


19. class = "w_calendar"
------------------------
   format=0               date control (default)
         =1               time control
   width=num              calendar width in unit spacing (default=100)
   height=num             calendar height in unit spacing

   (item 0 = label)
   (item 1 = date/time control)


Widget Common Options
---------------------
*  help=STRING,INTEGER1,INTEGER2
   STRING   -} help text/help icon/ZW3D message file
               - up to 160 characters long
               - '@' and '\n' characters are converted to newlines
   INTEGER1 -} 0 for text and icon versions or
               message number for message file version
   INTEGER2 -} help container field id number

   Examples:
      text version         -} help=hello\nthere!,0,100
      icon version         -} help=icon.bmp,0,100
      message file version -} help=VxCad.MSG,20,100

*  hide{1,2,3}
      hide widget based on field visibility state
      (refer to uiFormFieldVis() for additional info)

*  hints=hint string,{item 1 hint string, item 2 hint string, ...}

*  wid_label=width,align
      width in number of pixels
      label alignment (l-left, c-center, r-right)

*  usr_ctl


Widget Style Guide
------------------
1 character width = 7 pixels
1 character height = 16 pixels


Sample Template Showing Usage Of Widget Options
-----------------------------------------------

TEMPLATE=FormTest
description=Test Form
function=CdTestForm
gui_form
persistent
sole_focus
form_pos=base,TT,0.1
form_pos=base,LL,0.1
cur_pos=loc,0.5,0.5
unit_x=20
unit_y=20
buttons=ok,cancel,reset
usr_ctl_ok

FIELD=Group
id=100
wid_class=w_group
wid_const=0,LL,0
wid_const=0,BT,0

FIELD=Numeric Input 1
id=1
prompt=Enter form name.
wid_class=w_num
wid_group=100
wid_const=0,LL,0
wid_const=0,BT,0
wid_label=6
usr_ctl
options=format=0,step=2.5,min=-1.0,max=100.0,sig_dig=1,col=8,

FIELD=Numeric Input 2
id=2
prompt=Enter form name.
wid_class=w_num
wid_group=100
wid_const=1,LL,0
wid_const=1,BT,0
wid_label=6
options=format=1,step=2.5,min=-1.0,max=100,sig_dig=1,col=8,hide1,

FIELD=Text Output
id=3
prompt=Enter form name.
wid_class=w_txt_out
wid_group=100
wid_const=2,LL,0
wid_const=2,BT,0
wid_label=6
options=col=8,row=1,hide2,

FIELD=Text Button
id=4
prompt=Enter form name.
wid_class=w_txt_btn
wid_group=100
wid_const=3,LL,0
wid_const=3,BT,0
wid_label=5
options=format=1,menu=menu,col=8,
hints=Text Button's hint,

FIELD=Options
id=10
wid_class=w_opt
wid_const=100,LL,0
wid_const=100,BT,0
options=horz,format=0,row=2,col=2,btn1:none,btn2:none,btn3:none,btn4:none,
hints=btn1 hints,btn2 hints,btn3 hints,btn4 hints,

FIELD=List
id=11
wid_class=w_list
wid_const=10,LL,0
wid_const=10,BT,0
options=horz,row=4,col=30,non_exc,

FIELD=Label
id=12
wid_class=w_label
wid_const=11,LL,0
wid_const=11,BT,0
id_label=6