Event Types
The Language Reference Guide online help describes the events you can include in your application. These events can be grouped into the following basic types: frame events, field events, and menu events. Each event type is described in the following sections.
Frame Events
Frame events include events that are triggered by user interactions with the frame's window, such as the WindowResized event that is triggered when the user resizes the window. Frame events also include interactions with the background of the frame, such as the Details event, which is triggered for the frame when the user clicks the Details button on the area surrounding the fields.
The following sample script shows the event block for the WindowIcon frame event. This event is triggered whenever the user iconifies the frame. The code in Step 2 prevents the child, graphic_frame, from remaining displayed if the parent frame is iconified. If a user iconifies the parent frame, this event does the following:
1. Verifies that graphic_frame is displayed.
2. Sets the WindowVisibility of that frame to iconify.
on windowicon =
begin
if graphic_frame is not null then
graphic_frame.WindowVisibility = WV_ICON;
endif;
end
begin
if graphic_frame is not null then
graphic_frame.WindowVisibility = WV_ICON;
endif;
end
A frame also receives child events when the user interacts with the fields on the form. Because the form associated with a frame is considered a single subform containing all non‑menu fields on the frame, events triggered in any field also trigger a child event for the frame. This enables the frame to provide generic code that is triggered when any of the fields on its form receive a particular event.
For example, a frame receives a ChildEntry event when any of its child fields receives an Entry event. The following ChildEntry event block changes the color of the field that the user has entered to pale cyan. This code uses the TriggerField attribute of the FrameExec system class to determine which entry field triggered the current event:
on childentry =
begin
if CurFrame.TriggerField.ISA(class =
EntryField) = TRUE then
EntryField(CurFrame.TriggerField).
BgColor=CC_PALE_CYAN;
endif;
end
begin
if CurFrame.TriggerField.ISA(class =
EntryField) = TRUE then
EntryField(CurFrame.TriggerField).
BgColor=CC_PALE_CYAN;
endif;
end
WindowClose and Terminate are two other important frame events:
WindowClose
Is triggered when the user selects the window manager close operation for the running frame.
Terminate
Is triggered in any of the following circumstances:
• When the frame is closed by the Terminate method
• When the frame's parent frame closes itself
• When the frame's parent is itself closed by another frame or procedure
• When the user selects the window manager Close operation for the running frame
You can use an event block for either the WindowClose or Terminate events to clean up a frame (for example, to close open transactions) prior to closing it. To keep the window open under specified circumstances, use the WindowClose event. For more information about keeping a window open after a WindowClose event has been triggered, see How You Can Interrupt an Event Block.
The UserEvent event, which is a user‑defined event used primarily for communicating between frames and with external programs, is also considered a frame event. For more information about this event, see Inter-Frame Communication Techniques.
For more information about OpenROAD events in general, see the Language Reference Guide.
Field Events
Because users mostly interact with individual fields on a form, the events for fields are the most diverse and complex. For example, the following table summarizes the events that a user can trigger for a button field:
Event | How Triggered by User |
|---|---|
Click | User clicks the field with the Select mouse button when the field has a bias of FB_LANDABLE or FB_CHANGEABLE. |
DoubleClick | User double‑clicks the field with the Select mouse button. This event is not available for fields with biases of FB_VISIBLE, FB_DIMMED, and FB_INVISIBLE. |
ClickPoint | User clicks a field that has a bias of FB_CLICKPOINT. |
Details | User clicks the field with the Details button. This event is not available for fields with biases of FB_VISIBLE, FB_DIMMED, and FB_INVISIBLE. |
DragBox | User draws a drag box in a field that has a bias of FB_DRAGBOX. |
DragSegment | User draws a drag segment in a field that has a bias of FB_DRAGSEGMENT. |
Moved | User moves a field with a bias of FB_MOVEABLE or FB_FLEXIBLE. |
Properties | User clicks a field with the Properties button. This event is not available for fields with biases of FB_VISIBLE, FB_DIMMED, and FB_INVISIBLE. |
Resized | User resizes a field that has a bias of FB_RESIZEABLE or FB_FLEXIBLE. |
Select | User selects a field that has a bias of FB_FLEXIBLE, FB_RESIZABLE, FB_MOVEABLE, or FB_MARKABLE. |
UnSelect | User deselects a field that has a bias of FB_FLEXIBLE, FB_RESIZABLE, FB_MOVEABLE, or FB_MARKABLE. |
For a complete list of the events for each of the OpenROAD fields, see the Language Reference Guide online help.
Many events are triggered only when a field is set to a certain bias, allowing you to provide code that is executed only when the user is actually performing a certain task. For example, the Click event can be triggered only when the user is actually allowed to click the button, as determined by the allowable biases. For more information about field biases, see the Workbench User Guide.
Event Chains
A simple user action often triggers a series of events called an event chain. An event chain is a linked series of events triggered by a starting event. For example, each time the user changes some data in an entry field and then moves to another field, three events are triggered, as shown in the following illustration:
Another important event chain occurs when the user selects a field. Each time the user selects a field, the following three events are triggered:
• UnSelect event for previous field
• Select event for current field
• SelectionChanged event for the frame
Event chains do not include user events, except when you issue the SendUserEvent method with a focusbehavior parameter setting of FT_SETVALUE or FT_TAKEFOCUS. In these instances, if the value of the current field has changed, the event chain begins with a SetValue event and includes the user event.
IMPORTANT! If you provide more than one event block for an individual field, you must consider the order in which the events are triggered.
Child Events
When a field belongs to a composite field, a single user action on the child field triggers a corresponding event for the parent field. For example, if field A belongs to subform X, and the user selects field A, a Click event is triggered for field A and a ChildClick event is triggered for subform X, its parent field.
Because all fields are considered to be children of the frame's top form, each field event that is triggered in turn triggers a corresponding child event for the frame. The rules for queuing these events are:
1. The original event for the child field is always queued first.
2. The immediate parent for the field is queued second.
3. The parent field of the parent field is queued next, and so on, up to the frame.
The following diagram illustrates this concept:
In the following example frame script, the ChildEntry event is specified for the frame, so that whenever the user enters any field on the form, the color of that field is changed to white. The ChildExit event is also specified for the frame, so that whenever the user leaves the field, the color is changed back to pale gray.
on childentry =
begin
CurFrame.TriggerField.BgColor=CC_WHITE;
end
on childexit =
begin
CurFrame.TriggerField.BgColor=CC_PALE_GRAY;
end
begin
CurFrame.TriggerField.BgColor=CC_WHITE;
end
on childexit =
begin
CurFrame.TriggerField.BgColor=CC_PALE_GRAY;
end
If there is a chain of events, OpenROAD queues all the child events for the first event in the chain before moving on to the second event in the chain. For example, field A and field B belong to subform Y. If the user changes the data in field A and tabs out of field A to field B, the events are triggered in the order shown in the following illustration:
Menu Events
Menu events are events triggered when a user selects a menu item. Menu events are simpler than field events because they have fewer available events. These menu events are:
Click event
The three menu fields (menu button, menu toggle, and menu list) all have a Click event, which is triggered when the user selects the menu item.
SetValue event
The menu toggle and menu list fields also have a SetValue event, which is triggered when the user changes the value of the menu item—that is, switches the toggle setting or selects a new item from the list.
Validate event
The menu toggle and menu list fields also have a Validate event, which is triggered at exactly the same places as the SetValue event, but is processed before the SetValue chain. Therefore, if a Validate event block contains a resume statement, control returns to the frame without triggering the SetValue event.
The following sample frame script is the Click event block for the Graphic operation on the View menu. This menu operation functions as a toggle field that lets the user turn on or turn off the display of the photograph associated with a given video.
on click menu.view_menu.show_graphic =
begin
if menu.view_menu.show_graphic = FALSE then
graphic_frame.Terminate();
graphic_frame = null;
else
graphic_frame = openframe
video_graphic(vid_graphic_bitmap =
video.vid_graphic_bitmapobject)
with windowtitle = video.title,
windowxleft = CurFrame.WindowWidth,
windowytop = 0;
endif;
Show_video_graphic = menu.view_menu.show_graphic;
end
begin
if menu.view_menu.show_graphic = FALSE then
graphic_frame.Terminate();
graphic_frame = null;
else
graphic_frame = openframe
video_graphic(vid_graphic_bitmap =
video.vid_graphic_bitmapobject)
with windowtitle = video.title,
windowxleft = CurFrame.WindowWidth,
windowytop = 0;
endif;
Show_video_graphic = menu.view_menu.show_graphic;
end
Based on user interaction, this block of code either terminates the graphic frame and reinitializes its FrameExec pointer to null, or opens it with the appropriate photograph and window location.
The difference between the Click event and the SetValue event is meaningful for the menu list, as follows:
• The Click event is triggered when the user clicks any list item, even the currently highlighted list item.
• The SetValue event is triggered only when the user actually changes the value of the field.
For example, assume there is a frame with a Get menu that contains a menu list called initial_acct, which offers the following choices:
• New Account
• Existing Account
• All Accounts
• Closed Accounts
Because the user might need to repeat the command, New Account, the event block for this menu list uses the Click event. If SetValue were used, nothing would happen the second time the user clicked New Account.
The Click, Validate, and SetValue events create an event chain in this order for menu toggles and menu lists.
Note: The form associated with each frame (CurFrame.TopForm) contains only non-menu fields. Menu fields are separate from the form because they are toolkit‑specific. Therefore, menu events do not trigger corresponding child events for the frame. There are no child events for a menu stack or for the menu as a whole.
Last modified date: 12/20/2023