![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Customizing Task Editors with Apex_guigen Apex_guigen is a tool that allows a user to customize the graphical layout of Apex and Summit dialogs. In particular it was designed to aid in the customization of the Task Editor dialogs used in the Rational Summit/TM product. Apex_guigen is the natural complement to dlisp, the interpreted language that Apex and Summit use to specify the actions taken by a dialog. The dlisp language is described in the chapter Customizing Task Editor Actions using Dlisp.
By providing apex_guigen to generate the look and feel of dialogs and dlisp to describe the actions taken by a dialog, Apex and Summit offer a customization facility which allows the user to modify or create from scratch new dialogs that are consistent with the existing dialogs. apex_guigen provides a high level GUI customization language for with special support for manipulating Apex and Summit idioms such as navigators, histories, and tabbed dialogs, and for combining graphical elements to form standard Apex and Summit dialog boxes. Further, it provides special support for customizing the Task Editor dialogs associated with the user-definable task kinds offered by the Rational Summit/TM product.
Apex_guigen takes as input a file that contains a high-level graphical description of a dialog and dlisp actions for a dialog and generates output (a graphical layout file and a dlisp dialog execution file) that modifies an existing dialog or to creates a new dialog. This document provides the following sections:
- Introduction and Tutorial
- What To Do When Something Goes Wrong
- Arguments to apex_guigen
- Specification Language and Widget Types
- Widget Type Attributes and Children
Introduction and TutorialThis section provides an introduction to the use of apex_guigen that will help you get started through very simple applications. The goals of the tutorial is to learn how to invoke apex_guigen, what the specifications look like, and how to run an example dialog. The tutorial builds up a simple dialog that demonstrates some of the main features of apex_guigen. The example assumes that you have defined $APEX_USER_DIR in your environment, prior to starting Apex or Summit, and that this environment variable identifies a directory which contains subdirectories called dialogs and editor_files.
Let's start with a very simple dialog that contains a text field, and a label that describes the information in that text field.
First, you should create an input file for apex_guigen called test.dgen (using your favorite editor) with the following contents:
mylabel: label -label "This is a test, enter some text:" mytext: text -columns 20 -rows 10
Note, by convention, apex_guigen knows that files that end in the suffix .dgen are apex_guigen files and can find them accordingly.
Then invoke apex_guigen in the directory containing test.dgen as follows:
% apex_guigen test.dgen
% apex_guigen test
apex_guigen is an Apex and Summit executable and is visible on your path environment variable in any Apex or Summit shell.
You may receive output like the following:
06:04:32 !!! Base.cat could not be located on the messages path 06:04:31 ++* Error - Illegal widget definition type: dialog 06:04:32 ++* Error - Is /export/home/srw/apex_dev/taskmgmt/taskmgmt_guigen.ss/sol.srw.wrk /tests/gui_templates/dialog.guigen the template directory? 06:04:32 ++* Error - Does the template file dialog.guigen exist?If so, you have made an error in running apex_guigen. This tool must be invoked from an Apex or Summit shell,
After opening a shell window, invoke apex_guigen. There should then be a new file called test.dlg in the same directory. This file defines a dialog that can be read by Apex or Summit. You can display the dialog immediately by using the following apex_display command in the shell window:
% apex_display dialog test -action_file ./test.dlg -revert
There are two minor details that are important here. First, specify a complete pathname, such as ./test.dlg as the argument to the -action_file switch. This forces apex_display to search for this file first and not to use the environment variable $APEX_DIALOG_PATH as a place to search for a dialog by the same name. Second, you should employ the –revert switch on apex_display. If you are debugging a dialog and invoke it repeatedly and don't include the –revert switch, apex_display will think that you want to use a cached version of the dialog definition and won't read in any new changes that you have made. Including the –revert switch insures that the dialog server will reread the definition for the test dialog.
After you are satisfied with the look and feel of the dialog, you can install it as part of Apex or Summit using a menu customization. Customizations may be defined within the $APEX_USER_DIR directory. First, copy test.dlg file into the directory $APEX_USER_DIR/dialogs. Next, create a menu customization, that will invoke your new dialog, in the directory $APEX_USER_DIR/editor_files. For this example, place the following line in a file called apex_menus in the editor_files directory:
append pushbutton *.file.new.test_guigen "Test Gui Generator"
and place the following lines in a file called directory_rules, in the editor_files directory:
action test_guigen apex_display dialog test -action_file \ <ENVIRONMENT_APEX_USER_DIR>/dialogs/test.dlg \ -revert end_action
The above lines define an action (a procedure) which employs some useful features of the action language used in Apex and Summit menu definitions. The expression
<ENVIRONMENT_APEX_USER_DIR>
uses a general mechanism for obtaining the value of an Apex or Summit switch within an action. (Since actions are not interpreted by a shell, you cannot directly use shell variables such as $APEX_USER_DIR). If an action line gets too long you can continue it by using '\' as the last character on the line.
The customization files and directories mentioned should be created, if necessary. If you now restart Apex or Summit to load the new menu customizations, you should see the result of your efforts. There should be a new button at the bottom of the File > New menu and when you activate that menu button, the dialog should appear just as in the case when you tested it with apex_display.
Changes to the menu files can only be reloaded by restarting Apex or Summit. However, changes to the directory_rules files can be reloaded by the shell command
apex_display -editor directory reread_rules
You've taken the first step in creating or modifying your own dialog. Now, although the dialog will appear, it doesn't really do anything at this point. To make it functional, you must write a dlisp program for the dialog.
Just to complete the example, we can now add a dlisp program to the existing apex_guigen specification by changing test.dgen to have the following contents:
mylabel: label -label "This is a test, enter some text:" mytext: text -columns 20 -rows 10 dlisp: %prog exec <msg,"<valw,mytext>" is the text that was entered.> <return,nowait>
Now, you can go through the steps that were outlined before for invoking apex_guigen and running the dialog (either with apex_display or via the menu entry). When the dialog is displayed, enter some text into the text box. You should see the text that was entered displayed in a Message Window when you press the OK or Apply button.
The example above demonstrates the fundamentals of the description given to apex_guigen (called a dgen description). A dgen description is a sequence of graphical element or widget definitions. Each widget has a type that describes its look and feel. Further, the look and feel of these widget types can be controlled by several attributes. In the first line of our simple example, the widget definition has the following components:
mylabel: label -label "This is a test, enter some text:"
In the second line of our example, the widget definition has the following components:
mytext: text -columns 20 -rows 10
mytext Widget name.
text Widget type. Indicates a text box widget is required.
-columns 20 -rows 10 Widget attributes that specify the initial size of the mytext widget.
In addition to the description of individual widgets, there is a need to define the spacial relationship between the widgets. In the simplest case, this is controlled automatically and, in our example, the text widget mytext is placed directly below the label widget mylabel in the resulting dialog, in accordance with the order in which the widgets are defined in the dgen file. We will see other ways of controlling the layout of widgets later in this document.
Dlisp code can be included in the dgen description through the keyword dlisp: or by simply including the dlisp file in the dgen file. In fact, it is not necessary to include the dlisp in the dgen file at all; you may have some other file containing the dlisp for the dialog. The dlisp language is described in detail in Customizing Task Editor Actions using Dlisp
In the example above, the lines of dlisp code are interpreted as follows:
%prog exec
<msg,"<valw,mytext>" is the text that was entered.>
<return,nowait>
Causes the %prog exec to terminate without waiting for notification. (In many cases it is useful to wait for the completion of an operation invoked by the dlisp code; that is the default for return).
The example above is a very simple, but demonstrates the ease with which you can define a dialog that looks like a standard Apex or Summit dialog with your own fields.
Now let's look at an example where we exert more control over the layout of the widgets. For this example, use the following file as test.dgen:
mylabel: label -label "This is a test, enter some text:" mytext: text -columns 20 -rows 10 row: pack -side left mylabel mytext
Generate the test.dlg file and invoke the dialog as before. You will notice that this time the fields represented by mylabel and mytext are laid out from left to right, instead of from top to bottom. The only difference from the preceding example is the use of a pack widget called row to constrain the arrangement of the widgets. The top to bottom arrangement is the default.
This example shows one way that apex_guigen can layout widgets on the screen. The apex_guigen tool supports several widget types that control the layout of the different base widgets. Examples of these are: pack, pages, and row_column. The complete documentation for these is in the next section, but briefly, pack controls the layout of widgets either horizontally and vertically, pages allows you to define a "tabbed" dialog, and row_column allows you to define a grid box arrangement.
The next example illustrates one of the standard widget types supported by apex_guigen, the text_nav_combo widget:
mylabel: label -label "This is a text_nav_ombo widget:" mytext: text_nav_combo row: pack -side left mylabel mytext %prog build <popup,navigate,mytext*navigate,mytext*value,nav,, mytext*value> %prog nav <dialog,nav,fileLocator,<arg,1>,,Find File>
Standard widget types like text_nav_combo are included to help you create dialogs with the standard Apex/Summit look and feel. By specifying a widget type of text_nav_combo, you get a text field accompanied by four bit-mapped (drawn) buttons. The first button is a navigator button which is used to navigate through the file system and select files. The second button is used (by convention) to popup the common alternatives for the value of this text field. The third button is used to popup the recent history of values for this text field. The fourth button is used to popup a list of possible file name completions. The navigator and alternative buttons require additional dlisp code. A sample of dlisp code for the navigator button is illustrated above in %prog build and %prog nav. Dlisp code for popup buttons is described in detail in Popup Menus.
As a final example, let's add a new button to the sample task_editor dialog in Task Editor Example. This sample dialog can be run under Apex or Summit just as the other dialogs can and contains examples of most of the combining forms that you will need to build and modify dialogs.
In this example, suppose that there is some attribute associated with the children of a task that you need to add to the 'Related Tasks' page of the task_editor dialog. The related tasks page is described by the following lines of apex_guigen (dgen) code within the file task_editor.dgen:
# page describing the parent/child relationship parent_text_label: label -label "Parent:" -alignment alignment_beginning parent_text: text_field -editable false children_label: label -label "Children:" -alignment alignment_end children_list: scrolled_list -visible_items 15 -editable false c_action1: push_button -label "child_action_1" c_action2: push_button -label "child_action_2" c_action3: push_button -label "child_action_3" c_action4: push_button -label "child_action_4" children_actions: row_column -orientation horizontal -packing pack_column -entryAlignment alignment_center -isAligned true c_action1 c_action2 c_action3 c_action4 related_task_page: pack -side top -label "Related Tasks" -grow children_list parent_text_label parent_text children_label children_list children_actionsNote that this defines a label Children:, below which is a scrolled_list widget called children_list, which may contain a number of items. We have specified the default size of the list widget to display 15 items. Finally, there are a number of push_button widgets that are laid out from left to right below the list. The overall layout of this portion of the dialog is controlled by the pack widget called related_task_page.
For the element that we are adding, we choose a toggle_button widget and want to put it next to the list. So our first attempt is,
# page describing the parent/child relationship parent_text_label: label -label "Parent:" -alignment alignment_beginning parent_text: text_field -editable false children_label: label -label "Children:" -alignment alignment_end children_toggle: toggle_button -label "Our toggle button" children_list: scrolled_list -visible_items 15 -editable false c_action1: push_button -label "child_action_1" c_action2: push_button -label "child_action_2" c_action3: push_button -label "child_action_3" c_action4: push_button -label "child_action_4" children_actions: row_column -orientation horizontal -packing pack_column -entryAlignment alignment_center -isAligned true c_action1 c_action2 c_action3 c_action4 related_task_page: pack -side top -label "Related Tasks" -grow children_list parent_text_label parent_text children_label children_toggle children_list children_actionsIf you try this example out, you will notice that the new toggle_button occurs below the Children: label and above the scrolled_list. That isn't quite the layout we want; we want the toggle_button to the right of the list.
Our second try employs a new pack widget called children to arrange the new toggle_button and the scrolled_list.
# page describing the parent/child relationship parent_text_label: label -label "Parent:" -alignment alignment_beginning parent_text: text_field -editable false children_label: label -label "Children:" -alignment alignment_end children_toggle: toggle_button -label "Our toggle button" children_list: scrolled_list -visible_items 15 -editable false children: pack -side left children_toggle children_list c_action1: push_button -label "child_action_1" c_action2: push_button -label "child_action_2" c_action3: push_button -label "child_action_3" c_action4: push_button -label "child_action_4"
children_actions: row_column -orientation horizontal -packing pack_column -entryAlignment alignment_center -isAligned true c_action1 c_action2 c_action3 c_action4
related_task_page: pack -side top -label "Related Tasks" -grow children_list parent_text_label parent_text children_label children_toggle children_list children_actionsThe new widget children lays out the children_toggle and children_list from left to right. Note that this time, we included an error in that we listed children_toggle and children_list in the two pack widgets. The children_toggle and children_list widgets in the related_task_page should be replaced with the new pack widget children. Apex_guigen should complain that these widgets have been used as a child of another widget more than once. If a widget is not used as a child, apex_guigen will not complain, but will treat it as a top-level widget that should follow the default packing (that is, top-to-bottom).
In any event, the final correct change is the following:
# page describing the parent/child relationship parent_text_label: label -label "Parent:" -alignment alignment_beginning parent_text: text_field -editable false children_label: label -label "Children:" -alignment alignment_end children_toggle: toggle_button -label "Our toggle button" children_list: scrolled_list -visible_items 15 -editable false children: pack -side left children_toggle children_list c_action1: push_button -label "child_action_1" c_action2: push_button -label "child_action_2" c_action3: push_button -label "child_action_3" c_action4: push_button -label "child_action_4"
children_actions: row_column -orientation horizontal -packing pack_column -entryAlignment alignment_center -isAligned true c_action1 c_action2 c_action3 c_action4
related_task_page: pack -side top -label "Related Tasks" -grow children_list parent_text_label parent_text children_label children children_actionsIn addition to these examples, all of the dialogs specifically associated with the Rational Summit/TM product are available as examples in $APEX_HOME/dialogs/taskmgmt_dialog).
What To Do When Something Goes WrongWhat happens when something goes wrong. You've written you're new dialog and when you bring it up, the dialog has the wrong look and feel or doesn't execute the dlisp as you imagined. There are a number of things to diagnose what is going wrong. Here is some information that may help:
- 1 . Use apex_display.
Apex_display is a general purpose utility, which includes a command (as described above) to display a dialog. You can use this command to repeatedly display a dialog to observe the effects of changes.
- 2 . Use <msg,...>.
The dlisp language defines the <msg,...> operation which will write text to the message window. By putting messages of this sort in your dialogs you can see if the dlisp that you have written is being invoked and you can see what values are computed.
- 3 . Use apex_display to trace dialog execution.
Apex and Summit have an extensive tracing system that can be used to find problems in new dialogs or dlisp. For instance, if for some reason the dgen is not well-formed then some errors may appear in the trace output when the dialog is displayed. In addition, syntax errors from dlisp are only reported when tracing is on. Here's how to invoke apex_display to turn on tracing:
% apex_display {trace, trace_total, trace_verbose, trace_all} dialog -logfile <logfile_name>
You provide a log file where you want to send the tracing information. The different commands provide different levels of tracing. The trace_all option is generally recommended because it provides information about each dialog that is loaded and about each dlisp expression that is successfully parsed. The information presented in the trace is voluminous, but searching for the words error, warning, and undefined after you have tried to load your dialog will probably lead you to the widget or dlisp expression that contains the error.
To turn off tracing, using the command:
% apex_display trace_off dialog
- 4 . Restart the dialog server
Apex and Summit execute as a number of processes that handle different tasks. One of those is the dialog server which displays all dialogs. A final resort when trying to figure out what is going wrong with your enhanced or rewritten dialogs is to restart the dialog server and thereby cause all dialogs to be reloaded. This can be done by bringing up the Jobs window by invoking Navigate > Jobs and then invoking Navigate > Servers in the Jobs window. Highlighting the dialog server in that display and then invoking File > Kill will kill the dialog server. Note that all dialogs and data in the dialogs are cancelled by this action! Invoking a menu item or calling apex_display to display a dialog will automatically re-start the dialog server. The dialog server can also be shutdown by invoking apex_display as follows:
% apex_display shutdown dialog
Arguments to apex_guigenThe apex_guigen tool reads an input specification of a dialog box and generates a .dlg file that can be read by Apex or Summit to modify existing dialogs and create new dialogs. The command syntax is
apex_guigeninput_file
[ -trace | -namedialog_name
| -task_dlisp -outputfile_name
| -template_dirtemplate_dir
]The input_file is a dgen source specification that describes a dialog by defining its widgets. The input file may contain dlisp code as well. The other arguments are:
Invokes a trace option that can be used internally to debug apex_guigen
Controls the name of the dialog (in the .dlg file). By default, the name is the same as the name of the input file without its extension.
Generate the dlisp skeleton for a Task Editor dialog. If not set, it will generate a default skeleton dlisp file.
Place the generated output in a file named file_name. If omitted, the name of the .dgen file is used with the suffix changed to .dlg. If the suffix is omitted, .dlg is added.
A directory containing apex_guigen templates. Templates are used by apex_guigen in the generation of widget specifications and dlisp code. By default, apex_guigen uses the directories named by $APEX_GUIGEN_PATH and $APEX_HOME/gui_templates after substituting the values of the environment variables. The APEX_HOME environment variable is automatically set by Apex and Summit. The APEX_GUIGEN_PATH environment variable, if set, specifies directories to be searched for templates before $APEX_HOME/gui_templates is searched. The dir_name specified by this option, if any, is searched before both of these default directories.
Generate .fm and .dlisp files instead of a .dlg file. This option is temporary and supports obsolete outputs of apex_guigen.
In normal use of apex_guigen, only the input_file parameter is required and the .dgen suffix may be omitted.
Specification Language and Widget TypesThis section describes the input language read by the apex_guigen tool. Each dialog is created from a set of graphical elements such as push buttons, text boxes, etc. called widgets. Each input file to apex_guigen specifies a set of widgets, optional dlisp action routines, and some directions about how to combine them together. Running apex_guigen on this input will check for errors in the specification and generate output that can be read directly by Apex or Summit to modify existing dialogs and create new dialogs.
Input Form
An apex_guigen input file is a sequence of widget definitions, fields definitions and dlisp action routines. Syntactically, these constructs have the following forms:
- 1 . widget_name: widget_type
[-attribute_name attribute_value]* [child]*- 2 . fields: [field_name widget_name]*
- 3 . dlisp: [name]
arbitrary_textThe ':' character is used to identify the start of a widget definition, a fields definition or a dlisp section. The ':' must always be followed by a space (' '). The identifier appearing before the ':' is the widget name or a special keyword. The ':' must immediately follow the name or keyword. A widget or fields definition extends until the next token preceding a ':' character or to the end of the input file. A dlisp section extends to the end of the input file.
Tokens are separated by white space. A comment line is indicated by a line which begins with the character '#' (excepting a line which begins with #include). Include files are supported via the use of #include analogous to the C programming language. Tokens that contain white space (for example, labels) can be specified as quoted strings. For example, the quoted string, "a long token", is interpreted as a single token. There are two special widget names, fields and dlisp, which are essentially keywords and define special sections of the input. The name parent is a keyword because the underlying mechanism that is used to read files treats the word parent as a special identifier.
As indicated by the syntactic form, there are three distinct forms of input.
- 1 . The first form describes the individual widgets that form the dialog. Semantically, a widget definition defines a new widget and assigns it a widget_name. The widget_type token defines the form of the widget by naming a widget type. The name of the widget type comes from a pre-defined set of types. Each pre-defined widget type is specified by a template which describes the basic graphical look and feel of the widget type (text, push_button, label etc.).
The attribute_name tokens are taken from a pre-defined set of attributes that are associated with each widget type. These attributes specify parameters of a particular widget type (for example. the number of rows and columns for a text widget can be specified via the rows and columns attributes). Attributes are also used to specify callbacks.
Finally, the child tokens refer to other widgets by name and indicate that each named widget is a child of the widget being defined by this widget definition. A child widget must be defined before it is used. Any given widget may be a child of at most one widget.
- 2 . In the second form, the keyword token 'fields:' is followed by a sequence of pairs of names which specify a correspondence between task fields and widgets in a Task Editor dialog. This section is only used when creating a Task Editor dialog. If the 'fields:' section is omitted from a Task Editor dialog, apex_guigen deduces, based upon the widget types, which widgets are likely to be fields of a task and uses those (with their widget names) as the field names for the task.
- 3 . In the third form, the token 'dlisp:' is followed by an optional standard %prog name, such as exec, init, etc. These correspond to the %prog's that can be defined in a dlisp dialog program. The dlisp code which follows, up to the next '%' is associated with the named %prog. In general, these tagged dlisp sections are gathered up and deposited in the appropriate %prog in the generated dlg file (see Dialog Programs (%prog) for a discussion of %prog's). The order of the combined sections is preserved. If the optional %prog name is omitted in the 'dlisp:' clause, the dlisp code which follows is simply inserted into the output dlisp code before the standard %progs.
As far as apex_guigen is concerned, the rest of a dlisp section is arbitrary but is assumed to be a collection of dlisp %prog's, %popup's, %functions's and other dlisp constructs (see Customizing Task Editor Actions using Dlisp). The apex_guigen tool does not check the syntax of the dlisp code; dlisp code is parsed and interpreted dynamically when the dialog is actually displayed by Apex or Summit.
When the dialog is displayed and manipulated by the user, the dlisp %prog's are invoked as required according to the user-interface events which occur. Most widgets may have associated callbacks which are activated by specific events, such as changing the text in a text widget. These callbacks may be linked to dlisp %prog's such that a particular %prog is called for a particular event associated with a particular widget.
There can exist multiple 'dlisp:' sections in a given input file and these are concatenated together and included directly in the .dlg output file of apex_guigen.
Widget Type Semantics
From the point of view of apex_guigen, the widget definitions contain most of the semantics of the dgen language. This section contains a brief description of the predefined widget types that are supported and their properties. The attributes defined for these types are described in the next section of this document. In general, most attributes correspond to the resources defined for the respective X/Motif widgets.
Some apex_guigen widget types are represented as composite widgets (including some of the "basic" widget types described below). A composite widget has a tree structure consisting of a root parent widget and children widgets which may also have descendents. The children for each widget type are described in the next section of this document.
Basic Widgets
drawn_button
This defines a bitmap push button. That is, a push button that has a graphical bitmap as the surface of the button. The bitmap for the push button is defined by an attribute, and is searched for in the path defined by the FMPIXMAPSPATH environment variable.
file_list
This widget type combines a list of file names with a text field and a button that are used to add file names to the list, and a button that removes selected elements from the list. The widget type takes care of removing elements from the list and inserting them via the add button in a manner consistent with other Apex and Summit dialogs. See the Control > CheckIn dialog for an example of the file_list widget type.
hist_text_combo
This is a text field (a single line of text) with a history button to the right of the text field. Attributes exist to set the size of the text field.
label
This defines a basic label. Attributes exist to set the contents of the label and alignment of the label. A text of a label usually doesn't change and cannot be edited by the user.
list
This defines a list. Each line in the widget is an element of the list. An attribute exists to set the number of visible elements.
non_file_list
This widget type is similar to a file_list, except that the list elements are simply strings rather than file names.
options_menu
This defines a variable-sized popup menu that can be used to select and display a label from a fixed set of choices. (For example this is used in the Task Editor dialog to implement the choice of pages). The main argument is single string with a space separated list of choices to be presented when the menu is activated. An options_menu can be manipulated dynamically in dlisp using the <set_option_menu,...> command.
push_button
This is a simple button which can contain a label. The label attribute is used to set the text of the button label.
scrolled_list
This is a list widget with horizontal and vertical scroll bars for making different parts of a long or wide list visible. It takes the same attributes as the list widget to control its size.
scrolled_text
This is a multi-line text widget with scroll bars for scrolling the text horizontally and vertically. Also, see the text widget type below.
task_context
This specialized text widget is used to implement the 'Associate Tasks' field which appears in dialogs such as Check In. It contains text_nav widget whose navigator button is linked to the Select Tasks dialog. See the text_nav widget type below for a description of navigator buttons,
text
This is a multi-line text widget. It provides an editing window in which arbitrary text can be entered. It has attributes for controlling the horizontal, and vertical size.
All of the widget types with names of the form *text* take attributes which control the horizontal size of the text field and specify the callback %progs (dlisp procedures) invoked by the widget in response to certain user interface events.
text_alt
This is single-lined text field, with an associated alternatives button which provides a popup menu containing alternative values for the text field.
text_combo
This is single-lined text field, with an associated alternatives button which provides a popup menu containing alternative values for the text field and a history button which provides a popup menu containing previous field values.
text_field
This is a single-lined text field with no associated buttons.
text_nav
This is a single-lined text field, with associated navigator, completion, and history buttons.
The navigator button displays (by convention) a dialog for browsing the file system and selecting a file to place in the text field when the navigator dialog's OK or Apply button is selected.
The completion button completes partial file names entered into the text field.
The history button places previous text field values into the text field
text_nav_combo
This is single-lined text field, with navigator, completion, history, and alternatives buttons.
toggle_button
This is a widget for representing a boolean state. The label attribute allows one to associate text with the value being set. Toggle buttons may be combined into a set of radio buttons.
transition_menu
This widget is identical to an options_menu widget except that it is recognized as a special options menu for a state machine field by the apex_guigen template files used to generate Task Editor dialogs ($APEX_HOME/gui_templates/task_edit.*).
Combining widgets
In general terms, combining widgets are used to collect a number of user-defined child widgets together into a composite widget. For example, the pack widget type specifies how a number of child widgets are laid out as a group within the dialog. As composite widgets types, each of the widget types described below takes a number of child widgets as arguments in addition to attribute arguments. A composite widget type (along with the attributes specified) describes how the child widgets are laid out. The child widget names should always follow any attributes specified. Any given widget may occur as a child widget of only one composite widget.
checkbox
A checkbox presents a number of options which are not mutually exclusive. The children of this combining widget are expected to be of type toggle_button. The toggle buttons are shown as squares which are filled when the option is selected.
dialog
This type defines a basic dialog. It is automatically generated when not provided by the user. However, when it is provided by the user, the attributes specified for this widget (e.g. the dialog title) are used instead of the defaults. The children are laid out top to bottom.
frame
The frame widget simply draws a frame around its single child.
pack
The pack widget combines its child widgets into a row or column. The children are laid out next to each other as governed by the side attribute. The side attribute can take the values: left, right, top, or bottom. This determines the manner in which the children are organized. For example, -side left means that the first child widget is attached to the left hand side of an invisible box surrounding the child widgets and that each remaining child is taken in order and attached on its left side to the previous child. The argument -side top means start at the top and attach downwards. Similarly, -side right means start at the right and attach each successive child on its right side to the previous child. Finally, -side bottom means to start at the bottom and attach upwards.
The evenly attribute spaces widgets out evenly within a column (or row), so that several such columns (or rows) can be packed together to form a table of widgets in which both rows and columns are aligned.
Use of the pack widget is not necessary. By default, all widgets which have no parent widget are 'packed' in a dialog as though the user had indicated -side top.
The pack widget includes attributes to control spacing and to draw a box or frame around the children widgets.
pages
A pages widget is a "tabbed" widget in which the children are selectable alternative widgets and only one child appears at a time. At the top of a pages widget there is an options menu which contains a menu entry for each child widget specified. Making a menu selection will cause the corresponding child widget to be shown and the others to be hidden. By default, the first child in the list is displayed. The names used in the options menu entries are the values of the label attributes for the child widgets. A border is drawn enclosing the options menu and the alternative child widgets.
pages_form
A pages_form widget is used internally by apex_guigen, to determine the overall form of a child page in a pages widget, and may be manipulated by the user to control the border look and feel for a child page.
paned_window
A paned_window widget defines an window separated into adjustable panes each containing a child widget. The children are laid out vertically (top to bottom) with an adjustable line between each pair. The user can drag the adjustable line to control the vertical sizes of the panes and the child widgets they contain.
radiobox
A radiobox widget defines a number of alternatives which are mutually exclusive. The children are expected to be toggle_button widgets (the behavior is undefined if they are not). The radiobox widget ensures that only one of the alternatives (the toggle buttons) is set at a given time. The toggle buttons are drawn as diamonds which are filled when set.
row_column
A row_column widget lays out child widgets in rows and columns. The number of rows and columns in which widgets are organized can be set via attributes. The widgets can be packed tightly or packed into uniformly-sized cells. When a row or column is filled, it may be wrapped producing a grid-type layout of child widgets. Unlike the pack widget type, the row_column widget does not change size if the size of the dialog changes.
Widget Implementation NotesIn general, the widgets types defined for apex_guigen correspond to X-Motif widgets with similar names and have similar properties. For more detailed information about these widgets, refer to Motif documentation. Note that the pack widget type is implemented via the Motif XmForm widget.
The mapping of the above abstract widget types to Motif was formerly specified in the template files used by apex_guigen. These template files are no longer used and therefore no longer provide a means of customizing individual widget types.
Widget Type Attributes and ChildrenThe apex_guigen widget attributes control certain visible aspects of widgets and provide a mechanism by which you can define callbacks for widgets. A callback is a dlisp %prog that is called whenever a particular event occurs involving the widget. Dlisp %progs are named dlisp procedures within the dlisp code for a dialog. The syntax for an attribute is:
-attribute_name attribute_value
Attribute names are identifiers and generally correspond to directly to Motif resources associated with the underlying Motif widget class that implements the widget type. The accessibility of Motif widget resources via attributes depends upon the apex_guigen template files in the directory $APEX_HOME/gui_templates. The attributes which may be applied to each widget are generally specified in the corresponding apex_guigen template file in the form $attribute_name. The attributes may be extended by making a new version of a template which overrides the predefined version. Some attributes are interpreted directly by apex_guigen and do not appear in the templates.
Some of the widget attributes control visual or layout aspects of the widgets. An attribute whose name ends with Callback is used to name a dlisp %prog that is to be called whenever a specific event affecting the widget occurs. The name of a callback attribute is suggestive of the event which will cause the named dlisp %prog to be called. Callbacks for the OK, Apply, etc. buttons at the bottom of a standard Apex or Summit dialog are predefined to invoke the dlisp %progs such as exec and init (see the dlisp documentation on ).
Except for the case of push_button and drawn_button widgets, callbacks are generated only if a callback attribute is specified. The push_button and drawn_button widgets have, by default, an activation callback with the same name as the widget.
All text widgets share a common set of attributes which are described with the text widget type.
Some apex_guigen widget types are represented as a single X/Motif widget and others are actually composite widgets. Simple widget types are accessed in dlisp using only the widget_name. Composite widgets have child widgets which also have names. The syntax used in dlisp to reference a child widget is:
where parent_name is the name of the composite widget and child_name is the name of a child of that widget. Some child widgets are predefined by the apex_guigen widget types and others are specified by the user when a combining widget is defined. When a child_name is unique within a dialog, the parent_name and * can be omitted.
The attributes and children for each apex_guigen widget type are described below. The children named in bold face type are predefined components of the widget type and have predefined names. The user-defined children of combining widgets have user-defined names.
Basic Widget Children and Attributes
drawn_button
- Attributes
Specifies the file that contains the bitmap for this drawn button. The file must be on the path defined by the FMPIXMAPSPATH environment variable.
Specifies the dlisp %prog called when this button is activated. By default a dlisp %prog with the same name as the button widget is called.
file_list
- Children
textEntry - the text input widget.
navigate - the navigate button.
completion - the completion button.
- Attributes
Specifies the number of visible items (rows) in the file_list.
frame
hist_text_combo
- Children
- Attributes
text attributesThe dlisp %prog to be called when the history button is activated.
label
- Attributes
Specifies the string that appears in the label.
Takes one of the values alignment_beginning, alignment_center, alignment_end. This indicates where the text of the label will rest within the space allocated for the label widget.
list
- Attributes
Specifies the number of items visible in the list.
Specifies the dlisp %prog called when an item in the list widget is double clicked.
Specifies the dlisp %prog called when the set of selected list items is changed.
non_file_list
options_menu
- Children
The pull-down menu widget containing the options. The value of the widget may be set via the dlisp command set_option_menu.
The widget which holds the current selected option. The value of this widget may be set to control the selected option. This widget's name can be specified through the menuValue attribute.
category_label - the option menu's label (optional).
- Attributes
Specifies a string that is used as the label for the options menu. If not specified, then the options menu doesn't have a label.
Specifies the dlisp %prog called whenever an option is selected. The name of the option selected and the name of the options_menu widget are passed as parameters (in that order) to the %prog called.
Specifies the name of the child widget containing the selected menu item in the options menu. The default is menuValue.
push_button
- Attributes
Specifies the dlisp %prog called when this button is activated. By default a dlisp %prog with the same name as the widget is called.
Specifies the string that appears in the push_button.
Takes one of the values alignment_beginning, alignment_center, or alignment_end, indicating where the label text will rest within the push_button.
scrolled_list
- Attributes
Specifies the number of items visible in the list.
Specifies the dlisp %prog called when an item in the list widget is doubled clicked.
Specifies the dlisp %prog called when the set of selected list items is changed.
scrolled_text
task_context
- Children
tasks_label - the (optional) label above the text widget.
navigate - the navigate button.
completion - the completion button.
tasks_inner - A containing widget that can be used to safely hide the widget when it is the child of a pack widget.
- Attributes
Specifies a label that appears above the internal text_nav widget. By default the label is "Associate Tasks:".
Specifies that no label is to appear above the internal text_nav widget. By default the label is "Associate Tasks:".
If true specifies that a border is placed around the internal text_nav and label widgets.
Specifies the dlisp %prog called when the text in the widget is changed. The call occurs after the text has been changed.
text
- Attributes
Specifies the minimum number of visible rows of text.
The remaining attributes of text apply to all widgets types with names matching the pattern *text*.
Specifies the minimum number of visible columns.
Indicates whether or not the text display in the widget can be edited by the user (true or false). The default is true.
Specifies the dlisp %prog called when the widget is activated.
Specifies the dlisp %prog called when the text in the widget is changed. The call occurs after the text has been changed.
Specifies the dlisp %prog called when the text in the widget is about to be changed. The call occurs before the text is changed. If the %prog returns true, the change is completed; if the %prog returns false, the text is not changed.
Specifies the dlisp %prog called when the widget receives the keyboard input focus.
Specifies the dlisp %prog called when the widget loses the keyboard input focus.
text_alt
- Children
alternatives - the alternatives button.
- Attributes
Specifies the dlisp %prog called when the alternatives button is activated.
text_combo
- Children
alternatives - the alternatives button.
- Attributes
Specifies the dlisp %prog called when the alternatives button is activated.
Specifies the dlisp %prog called when the history button is activated.
text_field
text_nav
- Children
navigate - the navigate button.
completion - the completion button.
- Attributes
Specifies the dlisp %prog called when the navigator button is activated.
Specifies the dlisp %prog called when the history button is activated.
Specifies the dlisp %prog called when the completion button is activated.
text_nav_combo
- Children
navigate - the navigate button.
alternatives - the alternatives button.
completion - the completion button.
- Attributes
Specifies the dlisp %prog called when the navigator button is activated.
Specifies the dlisp %prog called when the alternatives button is activated.
Specifies the dlisp %prog called when the history button is activated.
Specifies the dlisp %prog called when the completion button is activated.
toggle_button
- Attributes
Specifies the text that appears beside the toggle_button.
Takes one of the values alignment_beginning, alignment_center, or alignment_end, indicating where the label text will rest within the push_button.
Specifies the dlisp %prog that is called when the value of the toggle_button changes.
transition_menu
- Children
A transition_menu has the same children as an options_menu.
- Attributes
A transition_menu may have the same attributes as an options_menu.
Combining widget attributes
checkbox
- Children
One or more user-defined toggle_button widgets.
- Attributes
Specifies the arrangement of the toggle_button children widgets to be horizontal or vertical (rows or columns). The default is vertical.
Specifies either the number of rows or columns of child widgets depending on whether the orientation is horizontal or vertical, respectively. The default is 1.
Specifies the horizontal and vertical spacing between the children widgets in pixels. The default is 0.
dialog
- Children
OK, Apply, Reset, Cancel, Help - the dialog buttons.
All widgets belonging to a dialog which have no parent are implicitly children of the dialog widget. Widgets may also be explicitly specified as children of this widget.
- Attributes
Specifies the title of the dialog that appears at the top of the dialog when it is displayed. By default the name of the dialog widget is used.
pack
- Children
The user-defined widgets to be packed.
- Attributes
Specifies the direction of layout of the children widgets. The values are top, bottom, left, or right. The default is top. This indicates the side (of the area containing the packed widgets) from which the widgets are laid out.
When true, specifies that the children should be surrounded by a box. The default is false.
Takes the value true, false, or a widget_name of a child widget. Normally, when child widgets are specified in the pack widget, the last widget in the list of children will grow to fill the available space for the children. The –grow attribute allows the user to specify which widget (if any) will grow to fill the available space. The value true means the last widget will grow (the default); false, means that no widget will grow. A widget_name, specifies the particular child which will grow. The default is true.
The horizontal spacing between adjacent child widgets in pixels. The default is 0.
The vertical spacing between adjacent child widgets in pixels. The default is 0.
This attribute is only meaningful when the pack widget is used as a child of a pages widgets. The attribute specifies the label of the options menu entry to be used for the page represented by the pack widget within the pages widget.
This attribute causes the child widgets to be evenly spaced, otherwise widgets are packed tightly. If the value is true, each child widget is assigned a slot of the same size and the number of slots is the same as the number of children.
If the value is a positive integer, it specifies a number of slots which must be equal to or greater than the number of children. If there are fewer children than slots, the remaining slots are left vacant.
The slot to which a child is assigned may be modified by specifying a position attribute for that child. This attribute specifies which slot the child widget is placed in (the first slot is specified by –position 1). Children following such a child in the list of children are placed in successive slots until another child with a position attribute is encountered. Thus, children may be assigned to specific slots and other slots may be left vacant.
When evenly is used, the grow attribute is ignored. All of the slots grow evenly. Also, the value bottom for the side attribute is treated like top, and right is treated like left.
The children of a pack widget may have the following attributes which provide additional control over the layout of the children. (These attribute may be applied to any widget that is a child of a pack widget).
-leftOffset, -rightOffset, -topOffset, -bottomOffset
The *Offset attributes control spacing around individual widgets. These attributes specify the offset in pixels of the child widget with respect to the adjacent child widget on the indicated side, or the offset from the side of the packed group when there is no child widget on that side.
The position attribute specifies which slot the child is placed in, when the evenly attribute is specified for the parent. Succeeding children are packed in succeeding slots until another child with a position attribute is encountered.
pages
- Children
The options menu for selecting a page. This widget has the same children as an options_menu:
The pull-down menu widget containing the options.
The widget which holds the current selected option.
category_label - the option menu's label (optional).
- Attributes
Specifies the text that appears beside the options menu in the pages widget. The label Pages: is used by default.
Each child of the pages widget must specify a label which will appear in the options menu for the pages widget. The children of the pages widget should be pack widgets.
When true, specifies that the pages widget will not have a label beside the options menu. The default value is false.
pages_form
The pages_form widget is used internally by the pages widget and has no attributes but can be customized by overriding the template.
paned_window
radiobox
- Children
A set of user-defined toggle_button widgets.
- Attributes
Specifies the arrangement of the toggle_button children widgets to be horizontal or vertical (rows or columns). The default is vertical.
Specifies either the number of rows or columns of child widgets depending on whether the orientation is horizontal or vertical, respectively. The default is 1.
Specifies specifies the horizontal and vertical spacing between the children widgets in pixels. The default is 0.
row_column
- Children
The set of user-defined widgets to be arranged.
- Attributes
If this attribute has a value, the widget is used to define a pulldown menu. In this case, all children of the row_column widget must be push_button widgets. The value true should be used, when specified.
Specifies the arrangement of the children widgets to be horizontal or vertical (rows or columns). The default is vertical.
This attribute is meaningful only when packing is specified as pack_column. It specifies either the number of rows or columns of child widgets depending on whether the orientation is horizontal or vertical, respectively. The default is 1.
Specifies the horizontal and vertical spacing between the children widgets in pixels. The default is 0.
Takes the value pack_column or pack_tight. The pack_tight option causes each child widget to occupy an amount of space that depends upon its size in the direction of the orientation specified. The pack_column option causes each child widget to be allocated the same amount of space. Widgets may be laid out in a grid using pack_column and a value for columns greater than one.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |