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.