Convert Vocola 2 Files

Vocola 2 users can convert existing command files to Vocola 3 syntax using the command line utility vcl2to3. This utility handles the main syntax changes from Vocola 2 by converting include statements and context statements to Vocola 3 syntax. You must handle the third syntax change manually by making sure that any keystroke sequence containing the < or > character is quoted. The utility also handles converting the primary global command file from _vocola.vcl to _global.vcl

In addition, the utility can optionally convert calls to Vocola 2's "built-in functions" (from the Dragon Macro Language) to their recommended analogs in the Vocola Function Library. See the table below for the conversions performed. (If you don't choose this option you can continue to use most Vocola 2 functions by setting the Option Panel's base using set to the "Vocola 2 default".)

In all likelihood the utility will convert most of your commands correctly and you will have to manually convert a few yourself.

Call the utility as follows:

    vcl2to3 [-functions] inputFolder outputFolder

Here inputFolder is the pathname of a folder containing Vocola 2 command files and outputFolder is the pathname of the folder where you want converted Vocola 3 command files to be written. If the -functions argument is specified, function calls will be converted to their recommended Vocola 3 analogs.

Say the user "Pat" has installed Vocola 3 in C:\Program Files\Vocola3 and has Vocola 2 files in C:\Vocola2Commands. From a Command Prompt the files could be converted using these commands:

    cd "C:\Program Files\Vocola 3.1\Bin"
    vcl2to3 -functions C:\Vocola2Commands C:\Users\Pat\Documents\Vocola3\Commands

First the directory is changed to the Vocola 3 Bin folder, which contains the vcl2to3 utility. Then the utility is invoked, writing converted command files to the Vocola 3 default command folder for user "Pat", C:\Users\Pat\Documents\Vocola3\Commands.

Function call conversions

When the -functions argument is specified, vcl2to3 converts function calls as specified in the following table. The table assumes that the Option Panel's base using set is set to the "Vocola 3 default". So, Vocola 3 calls in the table with no class name are in the Main class.

Vocola 2 call	Vocola 3 call
AppBringUp	SwitchTo
AppSwapWith	SwitchTo
ButtonClick	Pointer.Click
ControlPick(...)	HearCommand("Click ...")
DragToPoint	Pointer.DragFromSavedPoint
GoToSleep	HearCommand("Stop Listening")
HeardWord	HearCommand
MenuPick(...)	HearCommand("Click ...")
RememberPoint	Pointer.SavePoint
SendKeys(...)	...
SetMousePosition(0, ... )	Pointer.MoveTo(..., "ScreenInner")
SetMousePosition(1, ... )	Pointer.MoveTo(...)
SetMousePosition(2, ... )	Pointer.MoveBy(...)
SetMousePosition(3, ... )	Pointer.MoveToEdge(..., "ScreenInner")
SetMousePosition(4, ... )	Pointer.MoveToEdge(...)
SetMousePosition(5, ... )	Pointer.MoveTo(..., "WindowInner")
SetMousePosition(6, ... )	Pointer.MoveToEdge(..., "WindowInner")
WaitForWindow(a,b,c)	WaitForWindow(a,c)
WakeUp	HearCommand("Start Listening")

Calls to ShellExecute must be manually converted to RunProgram.

Calls to the following Vocola 2 functions are not converted, and there are no direct function library analogs. (But extensions are easy to write...)

ActiveControlPick ActiveMenuPick Beep ClearDesktop DdeExecute DdePoke

DllCall HTMLHelp MenuCancel MouseGrid MsgBoxConfirm PlaySound

RunScriptFile SetMicrophone SetNaturalText ShiftKey TTSPlayString WinHelp

If you're mourning the loss of ShiftKey, note that clicking a mouse button with a modifier key (achieved in Vocola 2 by calling ShiftKey followed by ButtonClick) can be accomplished in Vocola 3 using keystroke syntax such as {Shift+LeftButton}.