List Variables

A list is a variable part of a voice command name that is replaced by an actual item from a list of pre-defined variables.

Move Cursor to <Position> is an example of a command that contains a list. The list, <Position>, can be replaced by one of a list of predefined values, including Top, Bottom, Beginning, and End.

Adding a list variable to a command name

To add a list variable to a command name, type the list name with angle brackets. For example, type "Send Email to <Employee>", where Employee is the name of a new list.

A command with a list can:

  • Perform different actions depending on the particular list value that is used. For example, the command Move Cursor to <Position> performs a different action depending on the list value (Top, Bottom, Beginning, and End) used for <Position>.
  • Perform the same action but have different spoken forms. For example, the commands "Move to End of Line" and "Go to End of Line" are forms of the same command. The command includes the list <MoveTo>, which has two synonymous values: "Move to" and "Go to".

You can use lists that are already defined or create your own. To include a list, type its name (enclosed in angle brackets) in the Command Name box. In the next step, you will be prompted to enter (or edit) the values for any lists you include.

Notes

  • If the command will perform a different action depending on the list value used, the command can be implemented only with a script.
  • You can access the values of the lists from the script by means of the ListVarX() function, where X is of 1..20 range. Once created, it appears in the Lists Already Defined box.
  • To refer to the value of a list variable, use the UtilityProvider object. UtilityProvider.ContextValue(n) returns a string containing the value of the nth list variable, where the variables are numbered starting with 0. (In debug mode, this same function returns the name of the variable, though you can change it to debug your script, see Debugging section below.) UtilityProvider.ContextValueCount returns the number of lists in the command name. For an example of a script using list variables, see the example custom command called "sample script <1to10> <samplelist>", which is in the user-defined global commands.

Debugging

In debug mode, ListVarX() and UtilityProvider.ContextValue(n) functions return the name of the corresponding variable. If you want these functions to return more meaningful values while debugging your script, you can use UtilityProvider.SetContextValue(n,value) function to set the necessary value. And to determine whether your script is being executed under the debugger you can query UtilityProvider.IsDebugMode boolean property. The following example will set the first list value to "5" and the second list value to "snakes", but only if the script is executed under debugger in MyCommands Editor.

Sub Main
     If UtilityProvider.IsDebugMode Then
           UtilityProvider.SetContextValue(0,"5")
           UtilityProvider.SetContextValue(1,"snakes")
     End If
     MsgBox UtilityProvider.ContextValue(0) + " " + UtilityProvider.ContextValue(1)
End Sub

At runtime when the appropriate command gets recognized and the script is executed the UtilityProvider.IsDebugMode returns false and the list variables will be set to their appropriate values uttered by the speaker.