Vocola Information Pages   by Rick Mohr (this page updated January 15, 2005)
 
 Introduction
 Using Vocola
 Language Tutorial
    Keystroke Commands
    Quotes And Whitespace
    Using Alternatives
    Defining Variables
    Substituting Actions
    Capturing Dictation
    Optional Words
    Function Calls
    Built-in Functions ->
    Defining Functions
    Contextual Commands
    Include Statements
    Comments
    Example File
 Command Sequences
 Install Vocola
 Vocola Versions
 Converting DVC Files
 Troubleshooting
 Support
 Wish List
 My RSI Story
 Voice Resources
 

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

Here is the complete list:

ActiveControlPick
ActiveMenuPick
AppBringUp
AppSwapWith
Beep
ButtonClick
ClearDesktop
ControlPick
DdeExecute
DdePoke
DllCall
DragToPoint
Eval
GoToSleep
HeardWord
MenuCancel
MenuPick
MouseGrid
MsgBoxConfirm
PlaySound
RememberPoint
Repeat
RunScriptFile
SendKeys
SendSystemKeys
SetMicrophone
SetMousePosition
SetNaturalText
ShellExecute
ShiftKey
TTSPlayString
Wait
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. Vocola is not a general-purpose programming language, so expressions such as arithmetic and conditionals are achieved using Python. The specified expression (which may be constructed from a sequence of Vocola actions) is evaluated using the Python interpreter, and the resulting value is used as a Vocola action or function argument.
Argument
expression     Vocola actions, which when evaluated and concatenated yield an expression in the Python language.
Example

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 )

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:

0   Clear
1   Set (default)
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(); 

 

 


This page (c) Copyright 2002-2005 by Rick Mohr.