Copyright 2002-2015 Rick Mohr

Before an extension can be used, it must be installed so that Vocola knows about it. Otherwise, Vocola commands with calls to its routines will generate unknown extension routine errors. Note that Vocola 2 and Vocola 3 extensions are currently only usable with their respective versions of Vocola.

Installing an extension is straightforward:

  1. place the Python files the extension creator/distributor has given you in Vocola's extension directory:
    • at C:\NatLink\NatLink\Vocola\extensions if you used the combined installer and default install location
    • at <install>\NatLink\Vocola\extensions if you used the combined installer and install location <install>
    • otherwise try <install>\Vocola\extensions
  2. Either restart Dragon NaturallySpeaking or say "Load [Voice] Extensions".

Hopefully, the extension creator has provided you with documentation on the extension's routines. You call extension routines just like you would call a built-in. Just like with the existing built-in's, there are two kinds of extension routines:

Extension Functions

Extension functions are like Eval in that they return a string value that may be used in keystroke commands. For example, if we had a math extension that among other things provided Math.Mult, we could do:

Vocola: scroll down 1..10 = {down_ Math.Mult($1,20) };

Say: scroll down 5  Sent: {down_100}

Note that is sometimes important that one keystroke sequence be performed before computing the next; in these cases use Wait(0) to separate such key sequences. For example, given an extension function Clipboard.Get(), one correct way to write a command to capitalize the start of the current selection is:

Vocola: capitalize selection = {ctrl+c} Wait(0) Eval( Clipboard.Get() ".capitalize()" );

If we omit the Wait(0), then Vocola will first compute the entire keystroke sequence (including the {ctrl+c} and calling Clipboard.Get()) and only then send it. This will result in replacing the current selection with the capitalized version of what was already on the clipboard. The Wait(0) causes Vocola to send the control-C before calling Clipboard.Get() so hopefully we use the current value of the selection rather than the previous value of the clipboard. (For some slow applications, we might have to increase the Wait time to make sure they have time to copy the selection.)

Extension Procedures

Extension procedures are like ButtonClick in that they do not return a value but rather perform an action. For example, given an extension procedure Window.SwitchTo(title) for switching to a different window, we might write:

Vocola: Excel window = Window.SwitchTo("Microsoft Excel");

Say: Excel window  Done: switch to Excel window

Extensions and User-defined Functions

Calls to user-defined functions in Vocola 2 are completely equivalent to the function's body with its parameters replaced with copies of it's arguments. For example, given the following function definition,

Vocola: Twice(action) := "#1:" $action "#2:" $action;

the call Twice(HeardWord(press, backspace)) is equivalent to "#1:" HeardWord(press, backspace) "#2:" HeardWord(press, backspace) and ultimately produces "#1#2". This behavior differs from most programming languages and allows the passing of action sequences rather than just string values.

This behavior applies to passing extension routine calls as well; for example, given an extension function Math.Random(n) that produces a random number between 0 and n-1 each time it is called, Twice(Math.Random(10)) might produce "#1: 3 #2: 7" or "#1: 6 #2: 2".