Trigger phrase

Defines triggers on one or more user-interface events for a single user-interface component. Use the Trigger phrase within the statement that defines or creates the associated user-interface component.

Note: Does not apply to SpeedScript programming.

Syntax


TRIGGERS: { ON `event-list` [ ANYWHERE ] { `trigger-block` \| PERSISTENT RUN `procedure` [ IN `handle` ] [ ( `input-parameters` ) ] } } ... END [ TRIGGERS ]

event-list

The event or events with which the trigger block is associated. To specify more than one event, separate them with commas as follows:


`event1` , `event2` ...

The events you can specify depend on the type of the associated widget. See the reference entry for the appropriate widget. For more information on each user interface event that ABL supports, see the "Handle-based Object Events Reference" section.

ANYWHERE

Specifies that the trigger is a group trigger. This means that it applies not only to the widget being defined or created, but also is a default to any widget contained within that widget. This allows you to create a default trigger for all widgets in a frame or window. You can override the group trigger by defining a trigger on the same event specifically for the widget (or by defining a group trigger on an intervening widget).

trigger-block

A sequence of ABL statements to be executed when any of the specified events occur. The trigger block must be a single ABL statement or a DO block.

PERSISTENT RUN procedure [ IN handle ] [ ( input-parameters ) ]

Specifies a persistent trigger; that is, a trigger that remains in effect after the current procedure terminates. A persistent trigger must be a procedure specified by procedure. The trigger procedure can take one or more input parameters; it cannot have any output parameters. The parameters are evaluated when the trigger is defined. They are not re-evaluated each time the trigger executes.

If you specify the IN handle option, procedure must be the name of an internal procedure defined in the external procedure specified by handle, where handle is an expression that evaluates to a valid procedure handle. The external procedure must be in scope when you run procedure.

Example

This procedure defines triggers for two buttons:

r-trigp.p
DEFINE FRAME cust-frame. DEFINE QUERY custq FOR Customer. DEFINE BUTTON nextcust LABEL "Next" TRIGGERS: ON CHOOSE DO: GET NEXT custq. DISPLAY Customer WITH FRAME cust-frame. END. END TRIGGERS. DEFINE BUTTON prevcust LABEL "Previous" TRIGGERS: ON CHOOSE DO: GET PREV custq. DISPLAY Customer WITH FRAME cust-frame. END. END TRIGGERS. OPEN QUERY custq FOR EACH Customer. GET FIRST custq. DISPLAY Customer WITH FRAME cust-frame. ENABLE nextcust AT COLUMN 1 ROW 7 prevcust WITH FRAME cust-frame. WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

r-trigp.p

DEFINE FRAME cust-frame. 
DEFINE QUERY custq FOR Customer. 
DEFINE BUTTON nextcust LABEL "Next" 
  TRIGGERS: 
    ON CHOOSE DO: 
      GET NEXT custq. 
      DISPLAY Customer WITH FRAME cust-frame. 
    END. 
  END TRIGGERS. 
DEFINE BUTTON prevcust LABEL "Previous" 
  TRIGGERS: 
    ON CHOOSE DO: 
      GET PREV custq. 
      DISPLAY Customer WITH FRAME cust-frame. 
    END. 
  END TRIGGERS. 
OPEN QUERY custq FOR EACH Customer. 
GET FIRST custq. 
DISPLAY Customer WITH FRAME cust-frame. 
ENABLE nextcust AT COLUMN 1 ROW 7 prevcust WITH FRAME cust-frame. 
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

Notes

If you specify the Trigger phrase in the definition of a user-interface component, the Trigger phrase must be the last option in the component definition.

If you specify a trigger when you define a widget then that trigger applies to every instance of that widget. For example, in r-trigp.p, if you enable the nextcust button in more than one frame, each of those buttons inherits the nextcust trigger.

The input parameters for a persistent trigger are evaluated when the trigger is attached. (For the Trigger phrase, the trigger is attached when the widget is realized.) This means, for example, that you cannot pass the SELF handle as an input parameter.

The external procedure specified by handle is in scope if it is the current procedure, a procedure on the call stack, or a persistent procedure.