APPLY statement

Applies an event to a widget or procedure.

Syntax

APPLY event [ TO widget-phrase ]

event

An expression whose value is the key code or event name that you want to apply. A special value of event is the value of the LASTKEY function. The LASTKEY function returns the keycode for the last event read from the user (that is, from the keyboard or mouse) or the last character read from an input file. The value event can be either a character-string value (event name) or an integer (key code) expression. For more information on default system actions and events, see the Handle-based Object Events Reference.

TO widget-phrase

Specifies a widget or procedure to which the event is applied.

Example

This procedure shows how to use the APPLY statement to create keyboard accelerators. When you run this procedure you can invoke the trigger block attached to the order-but button by choosing the button directly or by pressing F10 in the Name field. When you press F10, the AVM sends the CHOOSE event to the button. This is equivalent to choosing the button with the mouse.

r-apply.p

DEFINE BUTTON order-but LABEL "Order"
  TRIGGERS:
    ON CHOOSE DO:
      FIND FIRST Order OF Customer NO-ERROR.
      IF AVAILABLE Order THEN
        UPDATE Order WITH FRAME upd-dlg
          VIEW-AS DIALOG-BOX TITLE "Update Order" SIDE-LABELS.
    END.
  END TRIGGERS.

FORM order-but Customer.Name WITH FRAME x.
   
ON F10 OF Customer.Name DO:
  APPLY "CHOOSE" TO order-but IN FRAME x.
END.
   
FIND FIRST Customer NO-LOCK.
DISPLAY order-but Customer.Name WITH FRAME x.
ENABLE ALL WITH FRAME x.

WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW.

Notes

• You can apply any event to any widget, including an insensitive widget. Most event-widget pairs have a default system action, but a few do. For example, the default system action for the A event on a fill-in widget is to insert the letter A into the fill-in at the current cursor location; however, there is no default system action for the A event on a button widget. Also, if you APPLY an event to a button, for example, the image of the button does not "depress" and then "pop back out." 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. For more information on default system actions and events, see the next note and the Handle-based Object Events Reference.

• When, in a graphical interface, you APPLY an event to a widget, you cannot easily invoke the widget animation code that runs when the user interacts with the widget physically. For example, if you APPLY a "choose" event to a button widget, you cannot easily make the image of the button move down and up, as occurs when the user clicks on the button. The difficulty exists because the AVM does not provide access to the widget animation code, which resides in the windowing system. When the user clicks on the button, the windowing system detects the event, invokes the button animation code, perhaps performs other tasks, and passes the event to the AVM, which invokes the trigger code associated with the event. When you APPLY a "choose" event to the button, the AVM merely invokes the trigger code associated with the event. In neither case does the AVM access, or provide access to, the button animation code.

  One widget that does not have this difficulty is the fill-in. When you APPLY a character-string event to a fill-in, the character string appears in the image of the fill-in. The AVM accomplishes this by placing a copy of the character string into a buffer that maps to the same portion of the screen as the image of the fill-in.

• The APPLY statement serves as an important communications mechanism between procedures in an application. By defining triggers for events in a procedure, you can encapsulate functionality in the procedure. The APPLY statement allows you to access that encapsulated functionality from another procedure through a simple event interface.
• The APPLY statement is double-byte enabled. A character-string value specified for the event argument can contain double-byte characters.
• If a procedure calls another procedure from within an EDITING phrase and the called procedure uses the APPLY statement, the effect is the same as if the APPLY statement occurred directly within the EDITING phrase.
• If you are using APPLY in an EDITING phrase and expression is a key that causes a GO action (GO, or any key in a list used with the GO-ON option), the AVM does not immediately exit the EDITING phrase but instead processes all the remaining statements in the phrase. If RETRY, NEXT, UNDO RETRY, or UNDO NEXT is executed before the end of the phrase, the AVM ignores the GO and continues processing the EDITING phrase.
• APPLY -2 is the same as APPLY ENDKEY.
• For SpeedScript, you can apply an event to a procedure only.
• You cannot use the APPLY statement to apply (publish or send) an event on behalf of a .NET object. .NET provides its own mechanisms for publishing events. In some cases, this might include a method for publishing a given event on behalf of the object. For more information, see the .NET development documentation on MSDN.

See also

ON statement, Widget phrase