Copyright 2002-2013 Rick Mohr

Vocola supports these special variables:

<_anything> Matches any spoken words.
<_vocolaDictation> Matches any phrase in recently-spoken Vocola dictation.
<_textInDocument> Matches any visible phrase in the current document (if the current application is fully speech-enabled).
<_startableName> Matches any item in the start menu or any "favorite" in Internet Explorer.
<_windowTitle> Matches words in the title of any open window.
<_itemInWindow> Matches any "clickable" item in the foreground window, such as a button or menu.

Use special variables in commands just as you would use regular variables.

Capture dictation using <_anything>

Sometimes you want a command which recognizes any words you might say rather than recognizing a particular set of alternatives. For example, searching for text is a common operation in Microsoft Word. It would be nice to be able to speak a single command to search for the text you want rather than needing to speak a command to open the "Find" dialog box, pausing, and then speaking the text you want to search for.

You can use the special variable <_anything> in a command to match any spoken words:

Vocola: Find Text <_anything> = {Ctrl+f} $1 {Enter};

Say: Find Text will do  Sent: {Ctrl+f}will do{Enter}

With this command you could search for the text "will do" by saying "Find Text will do", which opens the "Find" dialog box, enters the text "will do", and launches the search.

Modify Vocola dictation using <_vocolaDictation>

For applications using Vocola dictation you can use the <_vocolaDictation> variable to match any series of words in active dictation. (Active dictation contains all phrases dictated since the last command, possibly separated by pauses.) For example, this command allows capitalizing a specific phrase in recently dictated text:

Cap <_vocolaDictation> = Dictation.ReplaceInActiveText($1, String.Capitalize($1));

If for example you said "The town public library (pause) is excellent", and then "Cap public library", you would see "The town Public Library is excellent". Here <_vocolaDictation> matches "public library"; that text is then capitalized using String.Capitalize and both the original and capitalized versions are passed to Dictation.ReplaceInActiveText.

Several of Vocola's built-in dictation commands use this capability.

Note: <_vocolaDictation> works in Vista but unfortunately not in Windows 7 due to a Microsoft SAPI bug.

Select specific text using <_textInDocument>

If a document's text is fully speech-enabled by WSR you can use the <_textInDocument> variable to match any visible range of text. For example, this command puts brackets around a specific piece of text:

Brackets <_textInDocument> = HearCommand("select $1") Wait(250) "[$1]";

If the text "house band" is visible in the current document, saying "Brackets house band" invokes this command. The reference $1 then has the value "house band", and HearCommand("select house band") is called to select the text "house band". The command calls Wait, delaying until the selection is complete, and then "[$1]" replaces the selection with "[house band]".

Start applications using <_startableName>

The <_startableName> variable matches any sequence of words from items in the Windows start menu or "favorites" in Internet Explorer. For example, this command creates an alternate way of invoking the WSR "start" command:

Launch <_startableName> = HearCommand("start $1");

Saying for example "Launch Word" starts Microsoft Word by executing the WSR command "start Word".

Switch windows using <_windowTitle>

The <_windowTitle> variable matches any sequence of words in the title of a top-level window. For example, this command closes a window identified by its title:

Close <_windowTitle> = HearCommand("Switch To $1")
                       WaitForWindow($1) {Alt+F4};

If the file "Pumpkin Pie Recipe.txt" were open in Notepad, saying "Close Pumpkin" would bring it into the foreground by executing the WSR command "switch to Pumpkin". After WaitForWindow ensures the right window is in the foreground, the command closes it by sending the keystroke {Alt+F4}.

Invoke clickable items using <_itemInWindow>

WSR allows invoking a clickable item such as a button, menu, or hyperlink by saying its name. For example, to dismiss a dialog box with a "Cancel" button you can say "Cancel" or "Click Cancel". (The Vocola Options Panel offers the option of requiring the second of these.)

Vocola allows commands to refer to clickable items via the special variable <_itemInWindow>. For example, the following command allows you to say "Please" instead of "Click" because "Click" is difficult to say all day:

Please <_itemInWindow> = HearCommand("Click $1");

When a button with the label "Cancel" is visible, "Cancel" becomes one of the alternative words for the <_itemInWindow> variable. When you say "Please Cancel" the reference $1 gets the value "Cancel", the function argument becomes "Click Cancel", the HearCommand library function executes the WSR "Click Cancel" command, and the "Cancel" button is invoked.