Progress
Programming
Handbook
Static Widgets
You can describe and instantiate a static widget in one or two statements, depending on the widget type.
Describing a Static Widget
You can describe a static widget in several ways, depending on the widget:
- Frame — You can use the Frame phrase as part of many other statements, including a FORM, DEFINE FRAME, I/O (DISPLAY, UPDATE, ENABLE, etc.), or block header (FOR, REPEAT, etc.) statement.
- Dialog box — You specify the VIEW–AS DIALOG-BOX option in the Frame phrase.
- Field-level data-representation widget (EDITOR, SELECTION–LIST, etc.) — You can use the VIEW–AS phrase as part of some other phrase or statement—in a Format phrase for variables and in the Data Dictionary View–As phrase dialog for fields.
- Browse, menu, submenu, menu-item, or a field-level widget not used for data representation, such as a button, image, or rectangle — You can use the DEFINE widget–type statement. Note that you describe menu-item widgets directly in a static menu or submenu description. You can also use this statement to define frames, as noted above.
Instantiating a Static Widget
Progress automatically instantiates any static widget whose unique identity is known when you describe or use it. Thus:
- When you start a non-batch-mode client session, Progress instantiates the default window.
- When you describe or use any static frame or dialog box widget, Progress instantiates that frame or dialog box, unless it has already been instantiated by a previous description or use. You use a named or unnamed frame when you execute a frame-oriented I/O statement (DISPLAY, UPDATE, etc.) with or without a frame name. For more information on named and unnamed frames, see Frames."
- When you describe any static menu widget, Progress instantiates that menu, including its menu-items, submenus, and descendents.
Name references to some widgets specify a unique widget. These include static frame, dialog box, menu, or menu-item of menu widgets. Progress creates only one such widget in a procedure at a time. Thus, Progress can instantiate the widget when you first describe it.
However, to instantiate the description for any other static widget type, including a field-level, browse, submenu, or menu-item of a submenu widget, you must instantiate a static widget that contains it. The reason for this is that when you describe a widget that requires a container, you are only specifying the qualifying attributes of the widget. You can only establish a unique identity (widget handle) for a contained widget by associating it with an instantiated container widget. For example, this code fragment describes an editor widget associated with the variable xvar, and creates an instance of the editor in frame a.
Also, the widget description for a static field-level, submenu, or submenu menu-item widget might specify more than one instance of that widget. When you include a reference to a field-level widget in the descriptions of more than one frame or dialog box, you instantiate a different, but identical, field-level widget for each frame or dialog box in which it appears.
This code fragment describes a button, b1, and creates two instances of it—one in frame x and one in frame y.
Similarly, when you include a reference to a submenu widget in the descriptions of more than one instantiated menu or submenu, you instantiate a different, but identical, submenu widget for each menu and submenu in which it appears.
This code fragment describes a submenu, sub1, and creates two instances of it—one in menu m1 and one in menu m2.
Thus:
- When you specify a static browse or field-level widget within the description of a static frame or dialog box, Progress creates a unique instance of that browse or field-level widget. Although a browse widget requires a container to be instantiated, you can only instantiate a single browse from a single browse description. Also, you can reference a single browse widget in only one frame description at a time.
On the other hand, all instantiations of a static field-level data-representation widget represent the same underlying variable or database field. This example shows two fill-in fields—one in frame x and the other in frame y—each for the same cust–num field in the current customer record.
For more information on browse widgets, see Using the Browse Widget." For more information on data-representation widgets, see Representing Data."
- When you specify a static submenu widget within a static menu description, Progress creates a unique instance of that submenu widget and each descendent submenu and menu-item widget.
- When you specify a static menu-item widget within a static menu description, Progress creates a unique instance of that menu-item.
- When you specify a static submenu or menu-item widget within another static submenu description, Progress creates a unique instance of the named submenu or menu item only when the containing submenu is instantiated by a succeeding menu description.
Working with Static Widgets
The VIEW–AS phrase for describing static data-representation widgets has the following general syntax:
The widget–type parameter is the name of the widget type, such as FILL–IN, TOGGLE–BOX, or SLIDER. The options parameter is a set of options that further describe the widget.
The DEFINE statement for describing other static widgets (buttons, images, rectangles, menus, submenus, and frames) has the following general syntax:
The name parameter specifies a name for the widget, much like a variable name for data-representation widgets.
Again, frames and dialog boxes are described using the Frame phrase in many statements. Some of these statements, such as the FORM, I/O, and block header statements can describe a named or unnamed frame and apply scoping to the frame. The DEFINE FRAME statement, however, describes a named, unscoped frame. For more information on frame scoping, see Frames."
NOTE: The VIEW–AS DIALOG–BOX option is a special case of VIEW–AS applied to the Frame phrase only.For example, this code fragment describes an editor widget and a frame. It instantiates the frame and editor widget in the frame description.
You can also specify triggers for all static widgets when they are defined using the Trigger phrase, except the browse, frame, menu, and submenu widgets. For more information, see the "User-interface Triggers" section.
Referencing Static Widgets
In general, you can reference static widgets using either the widget name or a widget-handle variable to which its handle has been assigned. For more information on widget handles, see the "Widget Handles" section. The widget name for data-representation widgets is the field or variable name. For frames, it is the frame name; and for all other static widgets, it is the name used in the DEFINE widget–type statement.
The following widgets also require that you qualify name references with the widget–type:
For example, this code fragment shows name references to menu and menu-item widgets:
This code fragment shows name references to field-level and frame widgets, including the browse widget, custbrow; the fill-in field, order.order–num; and the frame, x:
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |