Using Extensions
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:
- 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
- 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".