Helpers

Home Up

 

Group Helper Commands

In order to fill in certain gaps left by the main command types, Helper commands are introduced (28 in all). 

They are classified in the following 6 command categories:

  1. Waiting 

  2. Window 

  3. Character 

  4. Input 

  5. Mouse 

  6. Other 

Helper commands can be specified in two ways: functional and heuristic. Functional form represents the standard function name and arguments in brackets syntax which is short and very powerful. On the other hand, heuristic form is more natural (actually, quite close to natural language) more flexible but it has some limitations (e.g. all subcommands have to be specified in the functional form).

Below, yellow marks necessary syntax elements.
Equals sign (=) designates alternative words in the heuristic syntax.

 

WAITING COMMANDS

COMMANDS DESCRIPTION HEURISTICS
Wait(n) Pauses execution of the next command for n/100 seconds, i.e. 1 second pause is specified by Wait(100). Wait for <N> one-hundredths of a second.

Wait = Pause = Break

WaitFor(title)
WaitFor(title, n, error)
Suspends execution of the next command until a window with 'title' in the window's title (contained, not equal; case insensitive) comes to foreground. There is a default timeout after which the remaining commands in the group are not executed. The default timeout can be specified in the Options dialog on the Advanced tab, Command Execution category. Alternatively, user can specify a timeout of n/100 seconds, after which the rest of the commands in the group are not executed. Instead, the specified 'error' command is executed. Wait for window <title>. Give up after <N> one-hundredths of a second and execute <error>.

Wait = Pause = Break
Window = Wnd

WaitWhile(title)
WaitWhile(title, n, error)
Suspends execution of the next command until a window with 'title' in the window's title (contained, not equal; case insensitive) is not in the foreground. By default there is no timeout. Alternatively, user can specify a timeout of n/100 seconds, after which the rest of the commands in the group are not executed. Instead, the specified 'error' command is executed. Wait for not window <title>. Give up after <N> one-hundredths of a second and execute <error>.

Wait = Pause = Break
Window = Wnd

WaitOpen(title)
WaitOpen(title, n, error)
Suspends execution of the next command until a window with 'title' in the window's title opens (not necessarily in the foreground). There is a default timeout after which the remaining commands in the group are not executed. The default timeout can be specified in the Options dialog on the Advanced tab, Command Execution category. Alternatively, user can specify a timeout of n/100 seconds, after which the rest of the commands in the group are not executed. Instead, the specified 'error' command is executed. Wait for application <title>. Give up after <N> one-hundredths of a second and execute <error>.

Wait = Pause = Break
Application = Program = App

WaitClose(title)
WaitClose(title, n, error)
Suspends execution of the next command until a window with 'title' in the window's title is not open. By default there is no timeout. Alternatively, user can specify a timeout of n/100 seconds, after which the rest of the commands in the group are not executed. Instead, the specified 'error' command is executed. Wait for not application <title>. Give up after <N> one-hundredths of a second and execute <error>.

Wait = Pause = Break
Application = Program = App

Confirm(qn#yes#no) Character asks the 'qn' question and waits for a response: 'yes' to continue executing the rest of the group and 'no' to cancel their execution. There is a default timeout after which 'no' response is assumed. Both 'yes' and 'no' are optional parameters since there are defaults in the Options dialog under Advanced tab, Command Execution category (where the default timeout can also be changed). Positive confirmation can also be done by double-clicking the character and negative confirmation by holding down SHIFT key while double-clicking the character. Confirm by asking <question#yes#no>.

Confirm = Ask = Verify

ConfirmEx(qn#yes#no,n,err) Same as Confirm() except that there is a timeout of n/100 seconds after which execution is stopped and 'err' command is executed instead. Confirm by asking <question#yes#no>. Wait for <N> and then execute <err>.

Confirm = Ask = Verify
Wait = Timeout = Execute

 

WINDOW COMMANDS

COMMANDS DESCRIPTION HEURISTICS
Restore(title)
Restore(title,correction)
Attempts to bring the window with 'title' in its title to the foreground. If unsuccessful, the first form does not continue with execution of the rest of the group, while the second form executes 'correction' command before continuing with the execution of the rest of the commands in the group. Restore <title> window. If not present execute <correction>.

Restore = Bring up = Bring back = Bring to top

IfOpen(title,command) Executes specified command only if a window with 'title' in its title is open. If window <title> is open execute <command>.

Open = There

IfNotOpen(title,command) Executes specified command only if a window with 'title' in its title is not open. If window <title> is closed execute <command>.

Closed = Not there = Not open

 

CHARACTER COMMANDS

COMMANDS DESCRIPTION HEURISTICS
Say(text) Character speaks 'text' while the execution of the commands in the group continues at the same time.

Say <text>.

Say = Announce = Speak

SayEx(text) Character speaks 'text'. The execution of the rest of the group is paused until the character finishes speaking.

Say <text> and pause until done.

Say = Announce = Speak
Pause = Wait = Break

MoveTo(x,y)
MoveTo()
Moves character (it's upper left corner) to the specified screen coordinates. If no coordinates are specified then character is returned to its default position.

Move character to (<X>, <Y>).

Move = Place = Position

Animate(anim) Character plays the specified animation. The execution of the rest of the commands continues at the same time. Animation has to be specified exactly by name (case sensitive).

Play <animation>.

Play = Animate

 

INPUT COMMANDS

COMMANDS DESCRIPTION HEURISTICS
KeyIn(text) Inserts 'text' by simulating keyboard input. It is the same as the Insert Text type commands but is introduced here in order to simplify entering group commands and to reduce the number of Insert Text type commands. Type <text>.

Type = Insert = Key in

PressKeys(keys) Presses specified keyboard combination. Supported special keys are CTRL, SHIFT, ALT and WIN (windows key). For example, PressKeys(CTRL+SHIFT+A) will hold CTRL and SHIFT, then press 'A' key and then release CTRL and SHIFT. Press <text> keys.

Press = Hold = Hit

PressButton(caption) Presses message box or dialog button with the specified caption (must be a full match, case insensitive). If button is not found the rest of the commands are not executed. Press <text> button.

Press = Hit = Click

ShiftTab(N) Holds SHIFT key down, presses TAB key specified number of times and then releases the SHIFT key. This is used when moving focus between controls in a dialog. N/A
AltTab(N) Holds ALT key down, presses TAB key specified number of times and then releases the ALT key. This is used to switch focus between top level windows.
NOTE: This method of switching between windows should be avoided because it is highly unreliable.
N/A

 

MOUSE COMMANDS

COMMANDS DESCRIPTION HEURISTICS
Left(x,y)
Left()
Presses the left mouse button at the specified coordinates. To obtain the desired coordinates there is a tool available from the Tools>>Coordinates/Titles... menu item. If the coordinates are not specified then left-click is performed at the current cursor position.

Left mouse click at (<X>, <Y>).

Right(x,y)
Right()
Same as above but with the right mouse button

Right mouse click at (<X>, <Y>).

Double(x,y)
Double()
Same as above but with double-clicking the left mouse button

Double mouse click at (<X>, <Y>).

Drag(x,y,X,Y)
Drag(X,Y)
Drags with the left mouse button from the point (x,y) to (X,Y). Drag(X,Y) drags from the current cursor position to the point (X,Y).

Drag mouse to (<X>,<Y>) from (<x>, <y>).

 

OTHER COMMANDS

COMMANDS DESCRIPTION HEURISTICS
Multiple(n,command) Executes the command N times. This is often used to press keys several times (e.g. TAB or arrow keys). Repeat <N> times the command <command>.
CloseApp(file) Terminates the process associated to the application 'file'. An example is CloseApp(notepad.exe).
WARNING: This causes a forceful closure of an application and therefore is only a last resort.
Close application <file>.

Close = Exit = Terminate

QuickAlarm(alarm) Set specified Quick Alarm. Specification is either a name of a custom Quick Alarm or a number of minutes to countdown. Sound alarm in <N/custom> minutes.
Batch(cmd) Executes one command-line (DOS-type) instruction. Execute batch command <cmd>.

Batch = DOS

Periodic(N,command) Set command to be periodic with period of N seconds. Repeat every <N> seconds the command <command>.

 

 

Windows® and Agent® are trademarks of Microsoft®. All other products mentioned are registered trademarks or trademarks of their respective companies.

Questions or problems regarding this web site should be directed to webmaster@quantum-intelligence.com.
Copyright © 1999-2002 Quantum Intelligence Group. All rights reserved.
Last modified: Saturday October 19, 2002.