---------------------------------------------------------------------- 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