Function Calls

Function calls are a useful supplement to keystrokes for writing voice commands. In your command actions you can call functions from four sources:

1. Functions from the Vocola Function Library, such as SwitchTo, WaitForWindow, HearCommand, and many others.
2. User-defined functions you create in your Vocola command files.
3. Functions from Vocola Extensions written by others or yourself.
4. Special Forms such as If, Repeat, and Eval. (Strictly speaking these aren't functions, but they use function call syntax.)

Here are some simple examples of calls to library functions:

Use Explorer = SwitchTo(explorer); Edit Words = HearCommand("Open Speech Dictionary"); Slam Left = Window.MoveToScreenEdge(Left);

Here's how these three commands work:

1. Calls the library function Main.SwitchTo to activate Windows Explorer when you say "Use Explorer".
2. Calls the library function Main.HearCommand to simulate the WSR command "Open Speech Dictionary" when you say "Edit Words".
3. Calls the library function Window.MoveToScreenEdge to move the active window to the left edge of the screen when you say "Slam Left".

(See the Function Library page to understand why 'Window.' was used as an explicit prefix in the above commands while 'Main.' was not.)

Note that function calls such as SwitchTo(explorer) are case sensitive; referring to switchTo would not work.

Function calls in action sequences

A command's actions can be a mix of keystrokes and function calls, as in this example which pastes the current clipboard contents as plain text:

Paste Clean = Clipboard.ConvertToPlainText() {Ctrl+v};

Data on the Windows clipboard may be in a format other than plain text, such as formatted text. This command calls the library function Clipboard.ConvertToPlainText to convert the clipboard data to plain text, and then sends the keystroke {Ctrl+v} to paste the converted text.

Function arguments

A function argument needn't be a constant. For example, you can use a reference to a variable term as a function argument as in this command to activate an application by its taskbar number:

Use 1..9 = TaskBar.SwitchToButtonNumber($1);

If you say "Use 2" the reference $1 matches the spoken "2" and so 2 is passed as an argument to the library function TaskBar.SwitchToButtonNumber, which then activates the second taskbar item.

Also note that a function argument can be built by concatenating more than one action. For example, the SwitchToButtonNumber function can count from the right side of the taskbar instead of the left side if you pass it a negative number. Here we construct a negative number argument by concatenating the text "-" with the spoken number:

Use 1..9 Right = TaskBar.SwitchToButtonNumber(-$1);

Return values

Some functions are useful for the value they return rather than for the action they perform. Often the value returned is used as an argument to another function, as in this example to capitalize the just-dictated phrase:

Cap That = Dictation.Replace( String.Capitalize( Dictation.Get() ));

This command uses three Vocola library functions. Dictation.Get returns the just-dictated text. That text is passed as an argument to String.Capitalize, which returns a capitalized version. Finally the capitalized version is passed as an argument to Dictation.Replace, which uses it to replace the just-dictated phrase. (See Dictation for a discussion of Vocola dictation.)

You can also use a function's return value directly as a keystroke sequence. For example, this "Paste That" command works in programs like Command Prompt which don't support the {Ctrl+c} shortcut:

Paste That = Clipboard.GetText();

Here clipboard text returned by the call to Clipboard.GetText is sent as keystrokes to the current application.

Exceptions

If an exception is encountered while executing a function call, Vocola aborts the calling command and displays an error message in the Vocola Log window.