What is a list variable in Dragon Professional advanced scripting?

List variables are Dragon Professional’s specialized version of VBA variables. Given we’re dealing with dictation software, they’re not the same a general purpose variable, but they provide some structure to allow for command variations.

Practically speaking for us, we can use the same script to invoke different Word macros with slightly different phrasings.

Customizable command word lists

More specifically, a list variable in a Dragon Professional script is just a plain text list of possible words at a given position in a custom voice command. For example, you might create a list variable called <direction> holding various literal directions in the document.

The list is completely customizable with the exception of no blank entries are allowed. That means we can’t use a list variable to spoof an optional (omitted) command word.

Using a list variable

A list variable in a voice command name is surrounded by angle brackets like <direction>. Yeah, literally type it with angle brackets as shown.

This command could be invoked using the command:

We can mix and match words and phrases to make our voice commands roll off the tongue more naturally.

Awkward keyword editor

Unfortunately, it looks we must work through the Dragon advanced scripting interface to create or edit the lists for a variables, which is a little awkward, but it is functional.

We can create up to custom list variables, but more standard ones exist in the scripting editor.

What do list variables do for us?

While they are a little annoying, list variables reduce misidentification of words when invoking voice commands by restricting the phrase to a more limited set of words.

They also allow us to condense our collection of voice commands since we can combine similar variations, but we’ll still have to create some duplicates if we want more natural voice commands.

Any issues?

What should we watch out for?

Dragon doesn’t really care about the exact composition of your list variables, but to make your own life easier, you might …

Consistency

Keep the lists consistent, so they make sense. On the other hand, utility is more important than idealized list categorization. Just don’t go overboard with mix and match word lists.

Not too long

Avoid exceptionally long lists. In extreme cases, very long lists might slow down the command recognition, but any speed issues are usually dominated by the voice recognition engine. On the other hand, Dragon allows a maximum of 20 custom lists, so you may need to condense them some.

Variable tips

How can we use list variables smarter?

Include some simple word variations

I have a list called <which> which contains:

These and similar words allow some general phrasing differences since we naturally state things in context. For example, when moving more than one paragraph we might say “move those paragraphs” rather than “move that paragraph,” but the computer must be instructed about how the generalized phrases mean essentially the same thing. We also tend to vary our wording without thinking about it.

Include more than one word on a line

We can wring more utility our o list variables by using multiple words. For example, my <which> list also includes some multiple word variations

It may take some simple parsing logic to detect words like “first” or “last,” but we’ll cover such improvements in upcoming articles. With these extra variations, we could additionally say:

Lists don’t have to be mutually exclusive, but …

When you give a voice command, Dragon looks for the best command match.

Okay …

The same word can exist in more than one list variable which helps us organize our voice commands with different flavors for different Word macros, but …

Don’t go crazy with overlapping list variables because it will muddle the lists and make remembering the commands more difficult. More importantly, it could also lead to different commands having the same phrasing while being hidden behind the list variables. Dragon might not recognize and properly assign a command to the intended script.

Dictation list variable

Dragon provides a unique list variable <dictation> that encompasses all text at the end of a voice command. It must be placed at the end of the command, and any text at the end is parsed as if it were dictated text. This treatment has some implications if you want to write more general natural language scripts (that’s a hint for some upcoming articles), but we won’t be using it in this script.

What’s the plan?

In principle, how do we create a simple voice command script in Dragon Professional?

• Open the Dragon Professional advanced scripting editor
• Tell the script what application we want to connect to it (really part of the previously covered function)
• Create a command name which is also the voice command to use when invoking the script
• Set up a new list variable or use an existing one by typing the angle brackets around the variable name
• Tell the script which Word VBA macro to run based on the word combination using the mentioned function

In order to keep the decision logic simple, we’ll use a separate function to connect Dragon Professional to the Word application, so see that article for more information.

How do we control Word from a Dragon Professional script?

Create script skeleton

Since we covered this in a previous article, we’ll be brief here.

The advanced scripting editor is mostly a plain text editor where we type commands just like in Word VBA macros. The Dragon Professional script editor has fewer features than the already meager Word VBA editor, but it does the job with some idiosyncrasies.

What’s the difference between a macro or a script?

Let’s clarify some terminology.

A “script” in Dragon Professional is basically the same thing as a “macro” in Word VBA.

Generally speaking, macros tend to refer to automations for repetitive tasks in an application. Scripts will probably look more like programming where macros may look more like general steps, but significant overlap exists between the terms.

In Dragon Professional, a “macro” is a recorded or list of task steps, but a “script” is a set of VBA steps more like a Word VBA macro. In Word, we can record macros as a series of steps, or we can write our own steps as a macro directly using VBA. The same term macro is used for both in part because Word always creates a VBA macro even when recording steps.

Open the script editor

Open the command editor using the Dragon Bar menu: Tools → Command Center → Add new command …

In the middle, open the combo box for the Command Type and select Advanced Scripting. This will add some lines to the script editor below.

Baby script ...

After selecting the new command option, by default, it’ll create an empty VBA script like the following in the script editor.

Any VBA script steps will begin on the empty line after Sub Main. Now to the meat for our current project. We covered these lines in more detail in a previous article, so we’ll get to the point here.

Type the command name

In the MyCommand edit box at the top of the script window, type the first part of the voice command name.

We now need to give a general direction as part of the command.

Define a list variable

To define a list variable, start and end the list variable name in the command with angle brackets <direction>. Our command name for the script now literally looks like:

Of course, you can shorten or extend the phrase to your preference.

List variable dialog

Dragon will pop up another dialog where you can either chose an existing list to modify, or the editor will recognize and create a new list variable with that name. Each word or phrase should be on a separate line.

Double click the list variable name to open the list variable editor.

The words are simply listed as plain text on separate lines.

Accessing variable values

Invariably, you’ll want the variable value as stated by the user during a voice command. We’ll need to store it in a plain text variable called a String.

I wouldn’t call this opaque notation, but it’s definitely not obvious either. Still, that’s why you have the internet and this amazingly helpful and wonderful article to guide you.

The Dim variable declaration is only required if Option Explicit is used at the top of the script (which is the default). I like preceding any string variables with an “s” to remind myself what I’m storing in the variable, but that’s just my preference.

Context element 0 gives us the value of the first list variable used in the voice command name. Element 1 is the second, and so forth (indexing using zero as the first element is common in programming). In this script so far, there is only one list variable, so (0) gives us the correct the stated word(s) at that position in the voice command. There actually is a good reason for counting from zero in other contexts, but we’ll just have to get used to it here.

Using list variable values

All list variables will start out as plain text strings, so you need a string variable like above to store the voice command word at that position in the command. If you’re searching for text or just comparing to the value directly, that’s all you need. If you want a numerical value from the variable, you’ll need to convert it. We’ll cover both options below.

Direction example

Now we can specify a verbal direction to move our paragraph. Imagine invoking the command by saying:

Adapting the above context value stuff, we get the direction variable value said by the user specifically using:

In a stated voice command, the variable sDirection could contain a plain text value of “above” or “below”, but I like to allow even more options, so I further include word options: “before” and “after” as well as “up” and “down” or even “forward” and “backward.”

Using a Select statement

How do we conveniently allow all these possibilities?

We could chain together a series of If statements (see this previous article for a brief introduction to conditional statements in VBA), but it gets unwieldy quick. A Select-Case statement is much more natural here.

The SomeVariable after Select Case should be a variable that we can compare against known values like a number or a string (plain text). Essentially, this is an extended If statement that is cleaner to read and thus easier to use when many options exist.

Case conditions

We chain a series of Cases together as shown where we list the values corresponding to that case.

More than one value can be specified for each Case just by using a comma to separate the values. We can also be fancier with ranges of values (like Case 1 To 3 and other variations), but we don’t need it here since we’re comparing the direction list variable result to specific words.

If no matches are found, we could optionally include a Case Else to catch any other unspecified conditions. In these voice command scripts, I usually only use this option to notify myself that something went wrong such as a word was misinterpreted by Dragon.

What happens?

When a match is found, only the commands up until the next Case line are run (this is different than some other languages where the execution can fall through into the following cases).

If no matches are found, the Case Else steps are run.

If no matches are found but no Case Else is included, nothing happens.

While not forbidden, it’s best to not include any overlap in the cases since only the steps corresponding to the first match will be run.

Back to our example

Let’s apply this in skeleton form to our specific voice command. For our direction example, “above” and then “below” are the two cases. We use the sDirection variable to pick between the Cases.

Looking at the Case options, I also added some other variations to provide flexibility in how we say our voice command. For example, we could also say:

Or …

But keep reading because we’re still building our command.

Only allowed keywords work

The above Select Case statement excluded the Case Else at the bottom, so no backup action is allowed.

That is, nothing happens if we don’t detect one of the specified direction keywords. The voice command will only work with the specified keywords even if they are included in the <direction> list variable, but this isn’t a bad thing. I’ve used this multiple times to enable only the word variations I want for a specific command while keeping my list variables more general within reason.

For example, my <direction> list variable also includes the word “left”, but this phrasing would be awkward.

Huh?

It should do the same thing since left basically means before the current paragraph, but it doesn’t make English sense (at least to me), so I don’t enable that word for this command. I suppose one could argue the same thing about above or below since they’re prepositions with no object, but the object is implied clearly enough for me.

No optional command words

Unfortunately, we can’t include optional words in a voice command name as of Dragon Professional version 16.0. Omitting optional words is an unfortunate omission itself, but we can allow some flexibility as shown using list variables.

If you want some different phrasings for the same voice command, you can further duplicate the script and/or use some clever list variable values, but as of Dragon Professional v16, if your command includes a list variable, you must say something at that position in the command.

Running the Word macro

Candidate VBA commands to run the relevant Word macros might be:

Or …

I say candidates because these aren’t my actual macro names since we can be more concise if we use a subroutine with parameters (see previous article for a partial explanation). Also, these macros are probably more easily stored in your Word application (the VBA editor which usually stores the VBA in the Normal.dot Word template).

For me, I already have many stand-alone macros (no arguments are allowed on a Word macro if you assign it to a keyboard shortcut or a button), but I’ve also created many commands that include parameters just waiting for arguments. We can determine these values with the voice command within the Dragon script and then provide that information to the Word macro. These versions are often more convenient to use in Dragon Professional scripting.

Allowing for errors

Here is where is gets messier and why using a function to run the Word macro is probably better.

We are connecting two different applications, so what happens if the command encounters a problem when trying to run the macro?

The script would fail, but we don’t want it to crash. We’ll get a nasty message from Dragon Professional or Microsoft Word. We need some steps to handle the error and exit the script gracefully.

That’s where the function enters the picture. I think the easiest way to do this is to just make a separate function that just accesses the Word application and runs the macro. We can check for any errors there and quit a script gracefully if one occurs. That way all the extra stuff is in one place. Nice and tidy.

Call a macro function

The relevant function in this Dragon Professional script is long enough for its own article, so let’s use the result without much extra explanation here. To use this function, we’ll call it with the macro name.

Remember Call is used to run a function or subroutine when we have to provide arguments for the function parameters. Otherwise you can omit it.

The returned result from this function indicates whether it was successful or not, but we don’t need it, so I didn’t store it in separate variable. If we did, that would look like:

No library in Dragon Professional

Unfortunately, Dragon Professional advanced scripting doesn’t allow us to create libraries unless you want to store the function as a separate file.

Unfortunately, as far as I could tell through internet digging, the script then loads the file from the hard drive every time the script runs. I prefer not to open a file on my computer every time I give a voice command, so I copy and paste this function between scripts (which is generally bad when you need to make any changes).

I keep other common macros in a Word VBA module which makes sense since those actions are run within Word anyhow. Still, I would prefer to have script interpretation stuff inside a Dragon Professional script. That division just makes sense to me, but alas, the powers that be have said “No” (for now?).

However, Dragon Professional should allow our scripts to access or create a library since there will invariably be common functions between scripts (like the RunWordMacro function above). We need to work around this limitation for now. Fortunately, as long as we’re working with Microsoft Word, the latter solution of storing the common scripts in a Word VBA module is a good backup solution overall.

Running the Word macro with a function

So here is the snippet to pick the correct Word macro to run.

Notice how the Case statement is automatically selecting the correct macro to run based on the direction variable value.

See the function RunWordMacro below.

Gotchas

Here’s the “what could go wrong?” section.

Voice recognition issues

Well, I hate to say it, but voice command recognition is dependent on the voice recognition engine, the work environment, the microphone, and your own pronunciation.

Ambient noise pollution

If you’re like me, and your intake vent for your air conditioner is literally twelve feet away (about 4 meters) from your computer desk, it can cause garbled commands (like it just did for me half a minute ago). Sometimes I may not even realize the AC is running since I tune the noise out. My microphone doesn’t.

Just misses a word …

Also, sometimes Dragon just misses a word, and I have a nice microphone setup (not professional but pretty good). The ambient noise just seems to take over, and while Dragon is powerful, it just isn’t as good as a human brain at filtering out all background noise or discerning between slightly different inflections when saying the same phrase.

Arghhh.

You could lean toward the microphone (annoying since I like to remain nice and slouched in my office chair) or just use keyboard shortcuts while the cacophony of apartment noise refuses to cooperate with the dictation software.

Not a silver bullet

I’m not telling you voice commands solve everything. They have their own issues, but overall, they’re a nice plus to our productivity.

More natural language commands later …

Later in upcoming articles, we’ll further account for some common spelling errors when we get more sophisticated with our natural language commands.

Initial Script

The final script looks messier than it is.

The function will catch an error when trying to execute the macro, so the script doesn’t crash. See the previous article for directions on how to enable the Word 16.0 Object Library.

This script can be readily extended to include more complex scenarios. This function also allows a single parameter such as the number of paragraphs. A later implementation will allow more parameters.