11. Managing Event Queues : Event-based Programming : Event Types : Field Events
 
Share this page                  
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
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: