TOC PREV NEXT INDEX DOC LIST MASTER INDEX



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

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

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:

or

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:

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:

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:

and place the following lines in a file called directory_rules, in the editor_files directory:

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

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

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:

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:

where

mylabel
Widget name.
label
Widget type. Specifies that mylabel will be a text label widget.
-label "This is a test"
Widget attribute which specifies that the label will consist of the string "This is a test, enter some text".

In the second line of our example, the widget definition has the following components:

where

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:

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:

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:

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:

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

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

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

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

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

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:

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:


Arguments to apex_guigen

The 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

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:

-trace

Invokes a trace option that can be used internally to debug apex_guigen

-name dialog_name

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.

-task_dlisp

Generate the dlisp skeleton for a Task Editor dialog. If not set, it will generate a default skeleton dlisp file.

-output file_name

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.

-template_dir dir_name

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.

-fm

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 Types

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

The ':' 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 Notes

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

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

parent_name*child_name

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

file_list

frame

hist_text_combo

label

list

non_file_list

options_menu

push_button

scrolled_list

scrolled_text

task_context

text

text_alt

text_combo

text_field

text_nav

text_nav_combo

toggle_button

transition_menu

Combining widget attributes

checkbox

dialog

pack

pages

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

row_column


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS