Introduction to ABL events

This section covers the following topics:

Event priority

Applying events

Triggers and low-level keyboard events

Event priority

The priority of events is an important concept. For any mouse or keyboard action on a widget, ABL generates a single event. Thus, certain events take priority over others that are generated by the same keyboard or mouse action for the same widget. Without direct manipulation, the priority (first to last) of keyboard events is key label, key function, and then high‑level widget events such as CHOOSE. The priority of mouse events is three‑button, portable, and then high-level widget events. Within three‑button and portable mouse events, low‑level mouse events (up, down) take priority over high‑level mouse events (click, double‑click). For more information on keyboard and mouse event priority, see the chapter on handling user input in OpenEdge Development: Programming Interfaces.

Applying events

You can apply any event to any widget using the APPLY statement. Depending on the event‑widget pair, the APPLY statement may or may not perform the default system action. Regardless of whether there is a default system action associated with an event‑widget pair, you can write a trigger for the pair. The APPLY statement executes a trigger associated with an event‑widget pair. If the event‑widget pair has a default system action, that action occurs before or after the trigger executes, depending on the event.

The APPLY statement also serves as a communications/dispatch mechanism between procedures in an application. You can define a trigger for an event‑procedure pair. For example:

 

ON CLOSE OF THIS-PROCEDURE DO:   APPLY "CLOSE" TO WINDOW-1. END.

To define a trigger for a procedure, specify any ABL event in an ON statement for a procedure handle. This capability allows you to encapsulate functionality in a procedure. To access that functionality, simply use the APPLY statement to apply the appropriate event to the handle of the procedure. For more information, see the APPLY statement reference entry.

When working with browse widgets, you can apply events to the browse widget and to a browse cell in the currently focused row. For example:

 

ON CHOOSE OF button1 DO: APPLY "ENTRY" TO my-browse IN FRAME a. /* Code to focus a particular row in the browse. */ APPLY "ENTRY" TO column3 IN BROWSE my-browse. END.

Since a browse cell is the intersection of a column and row, referencing the column name references the intersection of that column and the currently focused row.

Note:

The most flexible technique for encapsulating functionality in a procedure is to define and call internal procedures of a persistent procedure.

Triggers and low-level keyboard events

Some low‑level keyboard events cannot have associated triggers and maintain their default behavior at the same time. In general, if the AVM gets an event from the user interface system (UIS) that has a trigger associated with it, the AVM handles the default behavior and tells the UIS to ignore the event. This allows the AVM to cancel the default behavior in response to a RETURN NO-APPLY invoked by the trigger.

However, there are some low‑level keyboard events for which the AVM does not handle the default behavior. These include the cursor keys, especially. When the AVM gets one of these events with an associated trigger, it tells the UIS to ignore the event as usual, but because the AVM does not handle the default behavior for the event, the standard UIS behavior is lost, as well. Thus, a cursor key event (for example, CURSOR-UP) that has an associated trigger does not move the cursor.

Note that for many low‑level events, such as mouse button and printable character events in fill‑in fields and editors, the AVM does provide the default handling. Triggers on these events have no effect on the default event behavior unless they return NO-APPLY. The same is true of keyboard events that generate high‑level functions, such as TAB and RETURN.

For those low‑level, non‑printable, keyboard events that are not handled by the AVM, do not associate triggers with them unless you do not want the default behavior of the event. For those low‑level events that have no standard UIS behavior (such as, programmable function keys) triggers have no negative effects, and in fact, are very useful in defining a program action. In general, check any questionable low‑level events in a test procedure both before and after associating triggers with them to see if any standard behavior is affected. An empty trigger block is sufficient to detect differences in behavior. For example:

 

ON event ANYWHERE DO: END.