Built-in Functions
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 Python expression |
| HeardWord |
Execute a command as if words were spoken |
| 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 |
| Wait |
Pause for a specified time interval |
| WaitForWindow |
Wait until a desired window appears in the foreground |
Here is the complete list:
ActiveControlPick
ActiveMenuPick
AppBringUp
AppSwapWith
Beep
ButtonClick
ClearDesktop
ControlPick
DdeExecute
DdePoke |
DllCall
DragToPoint
Eval
GoToSleep
HeardWord
HTMLHelp
MenuCancel
MenuPick
MouseGrid
MsgBoxConfirm |
PlaySound
RememberPoint
Repeat
RunScriptFile
SendKeys
SendSystemKeys
SetMicrophone
SetMousePosition
SetNaturalText
ShellExecute |
ShiftKey
TTSPlayString
Wait
WaitForWindow
WakeUp
WinHelp |
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.
Eval
| Syntax |
Eval(expression) |
| Description |
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. 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 a integer (e.g., 13 or -1 but not 013 or +2),
in which case they are treated as integers. To force Eval to
treat $var as an integer use
int($var); to force it to treat
$var as a string use
str($var). |
| Argument |
| 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. |
|
| Examples |
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 ) |
The following example uses Python's string length operator
len to place the cursor before a piece of varying-size
text:
Vocola:
Len(string) := Eval('len(str($string))');
secure copy to <machine> =
"scp $1:~/import{left " Len(" $1:~/import") };
Say: secure copy to jumbo
Sent: scp _ mdl@jumbo.hpl.hp.com:~/import
|
Here _ indicates the position the cursor is left at. The
function Len here is copied from the sample file
string.vch, which contains a small library of useful string
functions. Len uses str($string), which
converts $string to a string if it is a number,
instead of just $string, so that it can work on
numbers as well as strings (len is not defined on
numbers).
|
HTMLHelp
| Syntaxes |
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)
HTMLHelp("", "HH_CLOSE_ALL")
|
| Description |
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.
|
| Arguments |
| 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.
|
|
| Examples |
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")
|
|
| Notes |
- 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.
|
Repeat
| Syntax |
Repeat(count, actions) |
| Description |
Executes an action sequence a specified number of times. |
| Arguments |
| count |
|
Number of times to repeat the specified actions. |
| |
|
|
| actions |
|
Vocola actions to be performed the specified number of times. |
|
| Examples |
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 Mozilla 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) |
|
SetNaturalText
| 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. |
| Argument |
| enable |
|
A value of 1 enables dictation, while a value of 0 disables dictation. |
|
ShiftKey
| Syntax |
ShiftKey([option[, action]]) |
| Description |
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.
|
| Arguments |
| option |
|
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 |
|
| |
| action |
|
Specifies the key state, as follows:
|
|
| Example |
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(); |
|
WaitForWindow
| Syntax |
WaitForWindow(caption[, windowClass[,
timeout]]) |
| Description |
The WaitFor Window call suspends execution of a Vocola command
until a desired window appears in the foreground.
|
| Arguments |
| caption |
|
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.
|
|
| Examples |
In the following example actions the * in the caption is an
instruction to ignore "Document1":
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)
{Alt+n}
|
|
|
