Variables

For more on how to use payloads and other variables, see the Logical Command Builder page.

Payloads

Technically, payloads are not a type of variable, but in your commands the notation is similar so we list the concept here.

A payload is a packet of information that is passed to a command when the command is triggered, so that the information can be used in the command. To access that information, the following notation is used.

{1} etc.

• {1} represents payload 1 (the first payload under your command in the command tree)
• {2} represents payload 2 (the second payload under your command in the command tree)

and so on.

More on using payloads.

{PF.1} etc.

This is the syntax for "friendly" payloads. Friendly payloads give us access to the payload phrase rather than the value.

For example, if you have a "Play artist {1}" command that relies on artist IDs to return relevant tracks, you can use {PF.1} in your TTS.Speak action to have VoxCommando announce the name of the artist rather than the ID.

A neat trick: If you have the "Show OSD on Command" box selected in Options, there is a neat trick to make the message more dynamic for commands that use payload XML. If you use the regular payload notation (e.g., {1}, {2}, etc.) in your command name, VoxCommando will automatically replace that value with the friendly payload when displaying the recognized command. So, if your command is named "Play artist {1}", the OSD message will show the name of the artist when the command is recognized, rather than the artist ID.

{#P}

Returns the number of payloads available in the current command. This can be especially useful when your command uses optional payloads.

Matches

{Match.1} etc.

Various actions (e.g., GgCal.GetToday, Results.RegEx, and others) return multiple results as matches. Each individual result can then be accessed using {Match.1}, {Match.2}, etc.

For an example of this, see the VoxCommando forum thread on listening to Internet radio.

When capturing several separate patterns at once within a regular expression, all strings that are captured within parentheses will be concatenated and stored as {Match.#}. However, each captured submatch can be accessed separately as {Match.#.1}, {Match.#.2}, etc. Obviously, if your regular expression captures only one pattern, then the variables {Match.1} and {Match.1.1} will be the same string.

For an example of using regular expression submatches, see the VoxCommando forum post: Enhanced regex

{#M}

The total number of matches returned can be accessed using {#M}.

{Match.Rnd}

Returns a random match, assuming there are any.

User Variables

{var.<varname>}

Returns the value of variable <varname>. You can set variables using the action Results.SetVar.

Recent Commands

{LastResult}

{LastResult} will be replaced by the value returned by your last successfully executed command action.

It is important to note that some actions do not return a result and therefore do not alter the {LastResult}.

{LastEvent}

Returns the name of the last event triggered.

{LastSpoken}

Returns the text of the last recognized speech input (this could be a voice command, a prefix, a dictation payload, etc.)

{PreviousCommand}

Returns the name of the command (as it appears in the tree editor) issued prior to the current command.

{PreviousSpoken}

Returns the complete text of the speech that was recognized (what the user said) in the command immediately before the one that is currently executing.

File Paths

{Path.VC}

Will be replaced with the correct relative path for your VC folder.

{Path:PFx86}

Will be replaced with the correct file path to access your x86 program file directory.

{Path.Appdata}

Will be replaced with the correct file path to access your AppData directory.

Date/Time

Generally get replaced by Microsoft's standard date and time format strings.

NB: Apart from DtCustom, these formats are specific to your language setting. The string formats for en-US will not necessarily be the same for fr-FR, etc. The examples below are representative, not comprehensive.

Just do a quick test of your local format if you're not sure (e.g. an OSD of {ShortTime}), or look at your Windows date/time settings.

{LongDate}

The current date, in long format.

example:

Monday, June 15, 2009 (en-US)

Montag, 15. Juni 2009 (de-DE)

From http://msdn.microsoft.com/en-us/library/system.datetime.tolongdatestring.aspx

The string returned by the ToLongDateString method is culture-sensitive. It reflects the pattern defined by the current culture's DateTimeFormatInfo object. For example, for the en-US culture, the standard long date pattern is "dddd, MMMM dd, yyyy"; for the de-DE culture, it is "dddd, d. MMMM yyyy"; for the ja-JP culture, it is "yyyy'?'M'?'d'?'". The specific format string on a particular computer can also be customized so that it differs from the standard long date format string.

{ShortDate}

The current date, in short format

6/15/2009 (en-US) (i.e., m/dd/yyyy)

15/06/2009 (fr-FR) (i.e., dd/mm/yyyy)

{LongTime}

The current time, in long format

6/15/2009 1:45:30 PM (en-US)
15/06/2009 13:45:30 (es-ES)

{ShortTime}

The current time, in short format

1:45 PM (en-US)
13:45 (fr-FR)

{DtCustom.????}

Retrieve the current date and time in a custom format of your choosing. See Custom_DateTime_codes for more.

• Note that the format string should be at least 2 characters or it will be assumed that you want to use a standard format.

Misc. variables

{CR}

Will be replaced with a carriage return (line break).

{CHR.##}

Any character can be used by replacing ## with the decimal ASCII code for the character. http://www.asciitable.com/ Example the ascii code (decimal) for TAB is 9 so to use a tab character in your parameters you can write {CHR.09}

{Empty}

An empty string. Can be used to clear variables of previous data.

{i}

When an action is repeating, {i} will start at 1 and increment each time an action is repeated. This can be combined nicely with {#M} and {#P}. For example, you can set an action to repeat {#M} times, and then within the action parameters iterate through match values {Match.{i}}. (See:"List today's meetings" command screenshot) for an example.

{j}

Similar to {i}. When a loop block is repeating, {j} will change according to the values specified in the loop block.

{LastInfo}

Returns the last information or error string from the previously executed action. This value does not persist like {LastResult} does. As soon as you execute any other action, its value will change. (Added in VC version 2.2.1.7)

{M:<map name>.<key>}

Any time you store values in a map table in VoxCommando, you can access individual values directly using a map variable. See the wiki entry on Maps for more information.

{Rnd.1.10}

Generate a random number from 1 to 10. You can replace 1 and 10 with any integers, as long as the first one is less than the second one.

{Status}

The current listening mode of VoxCommando (i.e., "on", "off", or "standby").