Home > Language Reference > Program Flow Functions > OnAction

OnAction

The OnAction...EndAction function handles events.

Usage

Used to launch a Sub when an unexpected event occurs.

Syntax

OnAction <action_identifier>
    Button(<Button>,<Type>)|Key(<key_list>)|Menu(<menu_item>)|Text(<text>)|Date(<Date>)|Time(<Hour>)
    DoSub <sub_name>
    EndAction
or
OnAction <action_identifier>
    WinStatus(Exists|NotExists|Active|NotActive[,Exact|Near])
    inWindow(<window_name>,<instance>)
    DoSub <sub_name>
    EndAction
or
OnAction <action_identifier>
    WinStatus(Exists|NotExists|Active|NotActive[,Exact|Near])
    InWindowAnyInstance(<window_name>)
    DoSub <sub_name>
    EndAction


Parameters

<action_identifier>, constant, name of the event to be handled. This identifier can be used to deactivate only this event.

For Button event:
<Button>, keyword, Left or Right, mouse button to be pressed to trigger the event
<Type>, keyword, click type, Down or Up or Double.

For Key event:
<key_list>, string, key(s) to be typed to trigger the event. Key combination follows SendKeys syntax (for example "<Alt <F1>>"). Note that the PrintScreen key cannot be used to trigger a key event.

For Menu event:
<menu_item>, constant, menu item to select in order to trigger the event. Menu item follows ChooseMenu syntax.

For Text event:
<text>, string, text to be found in order to trigger the event.

For Date event:
<date>, string, date which triggers the event.

For Time event:
<time>, string, time which triggers the event.

For Window event:
<window_name>, string, name of the window which triggers the event.
<instance>, integer, instance of the window which triggers the event. If InWindowAnyInstance keyword is used, any instance triggers.
Exists|NotExists|Active|NotActive, keyword. The event triggers if <window_name> exists, does not exist, is active, is not active.
Exact|Near, keyword. The event triggers if the exact same window as specified in <window_name> is found. With Near keyword, a fuzzy match is done.

<sub_name>, constant, name of the Sub to run when the event triggers. The Sub cannot have parameters.

Remarks

Such an event can happen at any time. But its nature is known - keyboard event, mouse event, menu event, date/time event, window event. All these events are external: if WinTask simulates the action the event is not fired.

For every event, an entry is created in a table of events. During execution, WinTask continually checks to see if one of the events listed in the table has occured.

If an event occurs during execution of the script, the procedure <sub_name> is immediately executed, then the script continues. This <sub_name> is a subroutine without any parameters.

This event handler mechanism is reentrant : during the execution of <sub_name>, if the same event or another event in the table occurs, <sub_name> is suspended and the new subroutine for this new event is launched. When the second event handler is complete, execution continues in the previous event handler.

Activation of the event handler:
An event handler (and the execution of the associated subroutine) is activated as soon as OnAction has been interpreted in the script. It stays active until the script ends. At the end of the script, all the events handled by that script are removed from the table of events, unless you use the SLEEP function (see the full example below). If a script launches another script (using the Run function), the event handler in the parent script remains active during execution of the child scripts (the table of events is shared by all the scripts currently running).
It is possible to deactivate the one event handler by the DISABLE function, but this function must be inserted in the script in which the event was defined (not in a parent/child script).

When an event handler is re-triggered:
For keyboard/mouse/menu events, each time the event occurs.
For text events, the text which has been handled must have disappeared before it can be triggered again.

See also

Enable
Disable
Sleep
OnAction Error

Example

'This script shows the use of OnAction for doing some actions when user presses some keys.
'The structure is :
'OnAction touche (touche is the onaction identifier)
'Key("<Alt <F2>>") 'the key will be Alt+F2
'DoSub appuie_touche (when the user press the specified key, Alt+F2, the subroutine appuie_touche is launched)
'REMARK : The compiler needs that the subroutine appuie_touche has been defined BEFORE the OnAction using it
'EndAction
 
'Definition of the subroutine which will be launched when "<Alt <F2>>" will be pressed
sub appuie_touche()
'here you can do what you want
msgframe("Key displayed",1)
pause 1
removeframe(1)
endsub
'--------------------------------------
'Definition of the subroutine to stop the script if you press "<Alt <F1>>"
sub termine()
msgframe("Script ended",1)
pause 1
removeframe(1)
stop
endsub
'---------------------------------------
'OnAction definition for "<Alt <F2>>"
OnAction touche
Key("<Alt <F2>>")
DoSub appuie_touche
EndAction
'---------------------------------------
'OnAction definition for "<Alt <F1>>"
OnAction Fin
Key("<Alt <F1>>")
DoSub termine
EndAction
'----------------------------------------
 
'The OnAction is active until the end of the script
'If the script has a SLEEP instruction, all the OnAction stay active
 
'SLEEP
sleep()