|Home | Vocola 2 | Vocola 3|
Vocola supports all scripting commands defined for the Dragon Macro Language, as well as adding some built-in functions. Here are the most useful functions in the combined set:
|AppBringUp||Start or switch to an application|
|ButtonClick||Click the specified mouse button|
|DragToPoint||Drag the mouse to the current point|
|Eval||Evaluate a simple Python expression|
|EvalTemplate||Evaluate a Python expression|
|HeardWord||Execute a command as if words were spoken|
|If||Execute actions depending on the value of a condition|
|MenuPick||Select a menu or menu item|
|RememberPoint||Record the current mouse pointer position|
|Repeat||Execute actions a specified number of times|
|SendSystemKeys||Send system keystrokes to Windows|
|SetMousePosition||Place the mouse pointer at a specified position|
|ShellExecute||Execute an application, with command line arguments|
|Unimacro||Perform Unimacro actions|
|Wait||Pause for a specified time interval|
|WaitForWindow||Wait until a desired window appears in the foreground|
|When||Execute actions depending on a value being empty (e.g., missing)|
Here is the complete list:
The Dragon Macro Language documentation describes most of these functions (see pp. 74-115). For those not so described, and for Vocola's built-in functions, see the descriptions below.
Note that the SendKeys function that Vocola provides is the one provided by early versions of Dragon NaturallySpeaking; later versions renamed this function to SendDragonKeys and introduced a different function confusingly called SendKeys. The modern version of SendKeys is not available from Vocola.
Evaluates an expression in the Python language that may refer to Vocola references and function arguments as if they were Python variables. Vocola is not a general-purpose programming language, so arithmetic and complex string processing are achieved using Python.
The specified expression is evaluated using the Python interpreter, and the resulting value is converted to a string, which is treated as a keystroke action if not passed to another call. Thus, Eval($x*2) by itself where $x is "3" types 6.
Eval attempts to guess the type of the referred-to Vocola values. They are treated as strings unless they have the standard form of an integer (e.g., 13 or -1 but not 013 or +2), in which case they are treated as integers. If you are concerned that Eval may guess wrong, use EvalTemplate instead.
It's useful to position the mouse by voice using screen units larger than pixels. This command places the mouse pointer at a specified screen position using a coordinate system of 15 pixels per unit. Saying for example "30 10 Go" moves the mouse pointer to screen pixel position (150, 450):
|Syntax||EvalTemplate(template[, argument1[, argument2 ...])|
Evaluates an expression in the Python language that may refer to Vocola values as if they were Python variables. Vocola is not a general-purpose programming language, so arithmetic and complex string processing are achieved using Python.
Unlike Eval, the desired expression is constructed by filling in a template with values provided as additional arguments. While somewhat more cumbersome, this allows the template to be constructed at runtime and allows specifying which arguments should be interpreted as integers and which should be interpreted as strings.
The constructed expression is evaluated using the Python interpreter, and the resulting value is converted to a string, which is treated as a keystroke action if not passed to another call. Thus, EvalTemplate("%i*2", 3) by itself types 6. An runtime error occurs if an argument cannot be converted to the desired type; for example, passing foo instead of 3 in the previous call produces an error because foo cannot be converted to an integer, which is required by the %i descriptor.
The following example uses Python's string length operator len to place the cursor before a piece of varying-size text:
Here _ indicates the cursor position after the command is executed. The function Len here is copied from the sample file string.vch, which contains a small library of useful string functions. Note that if we had instead used Eval('len($string)') as the definition of Len, then Len(3) would produce an error because len is only defined on strings, not integers.
The following example takes advantage of the ability to construct the template at runtime to choose which arithmetic operator to use:
Note that although Python's modulo operator is %, we have to pass %% because of the requirement to double existing percent signs in the template.
|Availability||Since Vocola version 2.7.|
Calls the Microsoft HTML Help API. This call enables you to display HTML Help and close HTML Help windows. Available subcalls include:
For more information on the HTML Help API, see the Microsoft HTML Help documentation.
This action opens dragon_enx.chm in the default window, displays the Contents tab in the navigation pane, and displays the htmlhelp.htm topic (this topic) in the topic pane:
This action opens MyProg.chm in a Help window named "HiddenNav" and displays the topic with the context ID 133096 (Hex 207E8):
|Syntax||If(condition, then-actions[, else-actions])|
|Description||The If built-in executes one of two specified action sequences depending on the value of condition. If condition has the value "True" (case insensitive) the then-actions are executed; otherwise, the else-actions are executed. Omitting else-actions is equivalent to giving "" for else-actions.|
If is primarily useful in conjunction with extensions. For example, suppose we had an extension function Window.MatchTitle(title) that returned true iff the title of the current window contains title. We could use this to build a global command for moving backwards a word that would work even in Emacs, which uses nonstandard keyboard commands, asssuming all our Emacs windows have "emacs" in their title somewhere:
In rare cases, it can be useful to combine If and Eval for conditional logic like If(Eval("$x < 10"), ...) or If(Eval('$y == ".doc"'), ...).
|Availability||Since Vocola version 2.8.1.|
|Description||Executes an action sequence a specified number of times.|
In an "Open File" dialog box, this command moves up a given number of levels in the folder hierarchy. Saying for example "Go Up 3" constructs the pathname "..\..\..\" to move up three levels:
In the Thunderbird mailer it's useful to delete several messages in a row by saying for example "Kill 3" to send 3 "delete" keystrokes. But unless these keystrokes are separated by "Wait" commands only 1 message is deleted. This command sends a specified number of "delete" keystrokes, separated by "Wait" commands:
|Description||Controls whether dictation is enabled in applications which do not support "Select-and-Say". (No visual feedback such as a system tray icon is provided.) This is an undocumented built-in function of the Dragon macro language.|
Either adds the specified key to the first character of the next non control keystroke or clears the specified key from the keystroke if the keystroke would normally be applied. That is, ShiftKey doesn't actually press any keys. Instead, it alters the keystroke that follows. You can sequentially execute more than one ShiftKey command to specify multiple keys.
This is an undocumented built-in function of the Dragon macro language. In Vocola it must be followed by a call to another built-in function such as ButtonClick or SendKeys.
This example shows how to use modifier keys with mouse clicks, such as saying "Control Click" to click the mouse while holding the Ctrl key:
|Description||If Unimacro is not available, produces a runtime error when called. Otherwise, passes actions to Unimacro, requesting that Unimacro perform them as Unimacro actions.|
Unimacro can send Unicode characters by putting a Unicode character on the clipboard and then pasting it:
For more on how to use Unimacro from Vocola, see the Unimacro Actions section.
|Availability||Since Vocola version 2.6.2.|
|Syntax||WaitForWindow(caption[, windowClass[, timeout]])|
|Description||The WaitFor Window call suspends execution of a Vocola command until a desired window appears in the foreground.|
In the following example actions the * in the caption is a wildcard matching anything before the specified text.
The following example waits for Word's main window by class name:
The following example starts Outlook, waits as long as 30 seconds in case the network is slow, and then types Alt+n to create a new E-mail:
|Syntax||When(test-value, present-actions[, missing-actions])|
|Description||The When built-in executes one of two specified action sequences depending on the value of test-value. If test-value has a non-empty value (anything but ""), the present-actions are executed; otherwise, the missing-actions are executed. Omitting missing-actions is equivalent to giving "" for missing-actions. The argument names here come from the primary use of When, namely testing whether optional terms are present. (References to omitted variables evaluate to "" so When($1,...) fires when the variable $1 refers to has been supplied unless its supplied written form is "".)|
When is primarily useful in conjunction with optional variables/ranges. Consider a command to start an email message where the details of how to open up the email client and start a new message have been abstracted out into a user-defined function, Compose():
This command allows 0-3 email addresses to be given and types them into the recipient line separated by commas. When is also commonly used to specify default values:
Here, we default to one line feed when no explicit count is given.
|Availability||Since Vocola version 2.8.1.|