Built-in Functions

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:

Command Description
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.

You will find additional useful functions in the official extensions; see Extensions for more details.


Syntax Eval(expression)

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.

expression     In its simplest form, a single quoted string holding a Python expression where all Python variables have been replaced by Vocola references (e.g., $1) or function arguments (e.g., $height). As usual, the quotes can be omitted if no special characters or whitespace are needed.

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):

Vocola: <n> := 0..99;
        <n> <n> Go = SetMousePosition( 0, Eval(15*$2), Eval(15*$1) );

Say: 30 10 Go  Sent: SetMousePosition( 0, 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.

template     This should evaluate to a string holding a Python expression where all Python variables have been replaced by %i or %s's and all %'s have been replaced by %%'s. Integer variables should be replaced by %i's and string variables by %s's.
argument1     The result of this expression will be the value of the first %i or %s in the template if any.
argument2     The result of this expression will be the value of the second %i or %s in the template if any. Any additional arguments are treated similarly.

The following example uses Python's string length operator len to place the cursor before a piece of varying-size text:

Vocola: Len(string) := EvalTemplate('len(%s)', $string);

        secureCopy($path) := "scp $path" {Left_ Len($path) }; 
        secure copy to <machine> = secureCopy("  $1:~/import");

Say: secure copy to jumbo  Sent: scp _ [email protected]:~/import

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:

Vocola: <op> := (plus=+ | minus=- | divide=/ | mod=%%);
         what is 1..10 <op> 1..10 = EvalTemplate('%i $2 %i', $1, $3);

Say: what is 2 plus 2  Sent: 4

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.


HTMLHelp(helpFile[>window], "HH_DISPLAY_TOPIC", topic)
HTMLHelp(helpFile[::/topic][>window], "HH_DISPLAY_TOC")
HTMLHelp(helpFile[::/topic][>window], "HH_DISPLAY_INDEX"[, indexSearchText])
HTMLHelp(helpFile[>window], "HH_HELP_CONTEXT", contextId)

Calls the Microsoft HTML Help API. This call enables you to display HTML Help and close HTML Help windows. Available subcalls include:

HH_DISPLAY_TOPIC     Opens the specified topic.
HH_DISPLAY_TOC     Displays the Table of Contents navigation pane and opens the specified topic, if any.
HH_DISPLAY_INDEX     Displays the Index navigation pane and enters the indexSearchText string, if any, in the keyword field.
HH_HELP_CONTEXT     Displays the Help topic for the specified contextId in the specified window. The contextId must be the numeric ID in the [MAP] section of the Help project (.hhp) file for the topic to display.
HH_CLOSE_ALL     Closes all HTML Help Windows opened by this program. The first argument must be an empty pair of double quotes.

For more information on the HTML Help API, see the Microsoft HTML Help documentation.

helpFile     The name of the complied HTML Help file to open, for example, dragon_enx.chm. If you do not specify a full path, Dragon NaturallySpeaking looks in the currently active Dragon NaturallySpeaking Help folder. If the file is not found there, the normal HTML Help file search rules apply.
topic     The specific HTML topic to display. If the compiled help uses subdirectories, this parameter must include the subdirectory. For example, the dragon NaturallySpeaking version of this topic is scrptref/htmlhelp.htm. Note that the identifier uses a forward slash (/).
window     The name of the window in which to display the HTML Help, for example, main. This parameter is always optional.

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:

HTMLHelp("dragon_enx.chm::/scrptref/htmlhelp.htm", "HH_DISPLAY_TOC")

This action opens MyProg.chm in a Help window named "HiddenNav" and displays the topic with the context ID 133096 (Hex 207E8):

HTMLHelp("C:\\MyProg\Help\MyProg.chm>HiddenNav", "HH_HELP_CONTEXT", "133096")

  • Dragon NaturallySpeaking does not get error returns from the HTML Help engine. As a result, it cannot display any messages when an HTML Help error occurs.
  • If the HTML Help file name does not use an absolute path, The HTMLHelp call first checks in the Dragon NaturallySpeaking Help directory for the requested help file. If the file is not found, then the normal HTML Help file search rules apply.


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.
condition   The expression to be evaluated and tested for true.
then-actions     Vocola actions to be performed if condition is true.
else-actions     Vocola actions to be performed if condition is not true.

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:

Vocola: back word = If(Window.MatchTitle(emacs), {esc}b, {ctrl+left});

Say: back word  Sent to Emacs: {esc}b

Say: back word  Sent to other windows: {ctrl+left}

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.


Syntax Repeat(count, actions)
Description Executes an action sequence a specified number of times.
count   Number of times to repeat the specified actions.
actions     Vocola actions to be performed the 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:

Vocola: Go Up 1..9 = Repeat($1, ..\) {Enter};

Say: Go Up 3  Sent: ..\..\..\{Enter}

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:

Vocola: Kill 1..10 = Repeat($1, {Del} Wait(100));

Say: Kill 3  Sent: {Del} Wait(100) {Del} Wait(100) {Del} Wait(100)


Syntax SetNaturalText(enable)
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.
enable     A value of 1 enables dictation, while a value of 0 disables dictation.


Syntax ShiftKey([option[, action]])

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.


Specifies which key to add to the first character of the next non-control key, as follows:

0   Clears all (ignores the action argument)
1   Left Shift (default)
2   Left Control
3   Left Alt
4   Right Shift
5   Right Control
6   Right Alt

Specifies the key state, as follows:

0   Clear
1   Set (default)

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:

Vocola: (Shift=1 | Control=2 | Alt=3) Click = ShiftKey($1) ButtonClick();

Say: Control Click  Sent: ShiftKey(2) ButtonClick()

  • [7/17/2010] In spite of the above, ShiftKey appears to only modify mouse clicks, not keystrokes. In particular, experimentation seems to show that it only modifies ButtonClick and DragToPoint.


Syntax Unimacro(actions)
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.

One or more Unimacro actions. For the syntax of Unimacro actions and what actions are possible, consult the Unimacro documentation. Note that the exact syntax required to call an action may vary depending on the version of Unimacro being used.


Unimacro can send Unicode characters by putting a Unicode character on the clipboard and then pasting it:

Vocola: paste Greek Delta = Unimacro("U Delta");

Say: paste Greek Delta  Pasted: Δ

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.

A text string to match against the window caption. The string may (and often will) include the asterisk (*) character as a wild-card to match against variable parts of the window caption. If parts of the actual window caption are guaranteed to be unpredictable, you MUST use an * wild-card to get a successful match.

The caption may also be an empty string "", to indicate that the caption does not matter.

windowClass     A text string which, when not empty (""), must exactly match (case-sensitive) the window class name of the window you are looking for. The window class name is usually obtainable only through programmer utilities like "Spy".
timeout     The length of time, in milliseconds, to wait for the window to appear. If no matching window appears by then, a timeout error is displayed, and the Vocola command stops without executing any subsequent actions following WaitForWindow. If not specified, defaults to 10 seconds.

In the following example actions the * in the caption is a wildcard matching anything before the specified text.

AppBringUp("(correct path here)winword.exe")
WaitForWindow("*Microsoft Word")
"this text will appear in the Word document, not the splash screen"

The following example waits for Word's main window by class name:

AppBringUp("(correct path here)winword.exe")
WaitForWindow("", "OpusApp")
"this text will appear in the Word document, not the splash screen"

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:

AppBringUp("(correct path here)outlook.exe")
WaitForWindow("*Microsoft Outlook", "", 30000)


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 "".)
test-value   The expression to be evaluated and tested for non-emptiness.
present-actions     Vocola actions to be performed if test-value is non-empty (e.g., the associated variable has been supplied).
missing-actions     Vocola actions to be performed if test-value is empty (e.g., the associated variable has not been supplied).

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():

Vocola: compose message [for <email> [and <email> [and <email>]]] = Compose() $1 When($2,", $2") When($3,", $3");

Say: compose message for Bob and Sally

Sent after Compose(): [email protected], [email protected]

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:

Vocola: line feed [1..10] = Repeat(When($1,$1,1),{ctrl+j});

Say: line feed  Sent: {ctrl+j}

Say: line feed 2  Sent: {ctrl+j}{ctrl+j}

Here, we default to one line feed when no explicit count is given.

Availability Since Vocola version 2.8.1.
Copyright © 2002-2023 Rick Mohr