Dragon Professional already includes some intuitive voice commands, but it would be nice to grab a power up and be able to run your own custom Word macros.
Today we create a basic Dragon Professional script to run a VBA macro in Microsoft Word, but it also works for any standard Word command.
Thanks for your interest
This content is part of a paid plan.
Dragon Professional advanced scripting with Microsoft Word
Well baby steps for now ...
Dragon Professional already includes some intuitive voice commands, but it would be nice to grab a power up and be able to run your own custom Word macros.
Today we create a basic Dragon Professional script to run a VBA macro in Microsoft Word.
Features and pricing
Please note advanced scripting is only available in the Dragon Professional® edition or above (specialized editions like Legal or Medical One). Dragon Professional is a paid application, and I am specifically working with Dragon Professional v16 for this content. Do not buy an older, discontinued version of Dragon Home if you wish to use any advanced scripting features.
As writers, we should make use of tools that enhance our productivity, especially ones with as much of a potential boost as Dragon Professional offers. If you’re sticker price sensitive (I’ve been there), you may want to come back to this article later. With that said, if you can afford it, a paradigm shift toward “will this expense make me faster, better, and/or more productive” is a valuable mindset adjustment for anyone who plans to or is already making money on their writing.
What’s the plan?
In principle, how do we create a simple voice command script in Dragon Professional that interfaces nicely with Microsoft Word?
That’s about it. It’s actually pretty easy when you see it below, and VBA makes it read even more like English, so you don’t even have to be a programmer to understand it.
So how do we control Word from a Dragon Professional script?
Using SendKeys …?
A quick side note …
It’s more common online to see people create Dragon scripts using SendKeys or similar commands to control an external application. This process emulates how you would give the commands manually, so it makes the scripting process easy to understand for the most part.
Nothing is wrong with this approach per se. It works … but it’s a little more fraught with potential problems like syncing input from the script sending the commands with the application receiving them. Plus I just feel like it's a clunky solution if there is a better way.
A better way …
Fortunately, there is a better way to make Dragon Professional interface with Microsoft Word. Further, it gives us more control and less room for syncing errors. It’s not even that complicated once you see it.
Create script skeleton
To get started, we need to open the advanced scripting editor which is basically a plain text editor where we give commands just like we do when creating Word VBA macros. Unfortunately, the Dragon Professional script editor has fewer features than the already meager Word VBA editor, but it still gives us tremendous opportunity to enhance our writing productivity.
Open the script editor
Open the command editor using the Dragon Bar menu: Tools → Command Center → Add new command …
In the middle of the scripting editor that appears, select the combo box for the Command Type and select Advanced Scripting. This will add some lines to the script editor below.
Later, you’ll probably want to use the Command Browser … window which lists various commands.
What you see?
After selecting the new command option, it’ll automatically create an empty VBA script in the script editor like the following.
What is it?
The first two lines tell the editor some specifics about your script.
Language
The language line tells the script what language mode to use. Supposedly, it allows us to use VBA, but the scripts seem to work without it (at least to some extent).
There’s no reason to delete it other than it looks messy, so leave it.
Explicit? Not here bub …
Option Explicit on the next line requires any variables to be explicitly declared.
It’s easier with it off, so if you prefer, you can “comment out” the line by adding a single quote before it.
Now we could be sloppier by not declaring variables, but the freedom does come with a little risk if we make any spelling errors on our variable names. If so, the script will just assume we’re creating another variable which makes errors harder to catch. Plus, the editor won’t give us as much information or help when we’re writing commands. It's annoying to get a wonderfully informative [sarcasm alert] error like, "Please correct syntax error(s) before saving a macro." Huh? Where? What?
I tend to use Option Explicit when I’m more serious, but I also like the freedom of not taking time to make variable declarations I mention in an upcoming article.
Main
You’ll enter your commands in the Main subroutine at the bottom of the script. All Dragon Professional scripts require one, but you can further create functions and other subroutines below it with some idiosyncrasies.
Name the script
Use the MyCommand edit box to name your script: with something descriptive about its function like: Select that heading.
These are the words you’ll say to Dragon to invoke the script.
Add a text description in the edit box below the name for yourself if you wish. Most of the time it won’t be necessary, but it might be more important if the macro has a concise name.
Word specific?
This is optional, but I prefer to restrict my VBA scripts to work only in Microsoft Word since it is main application for writing. Most of my macros are written in VBA there anyhow. I definitely appreciate generality, but it’s also safer to restrict it’s usage to Word since I’ll essentially never use these particular scripts in another application.
To restrict where the script runs, select the Application-specific radio button in the Availability section of the editor window. Then use the Application combo box to select Microsoft Word.
Get Word application
We need to tell Dragon we’ll be using the Word application.
WordApp is just a variable name that makes it easy to remember what we’re connecting to it and what we're doing.
We had to use Set because the Word application object is not just a value like a number or character. It includes a lot of other information associated with the object.
Get Object
GetObject is a stock VBA function that will retrieve identifying information for whatever object you specify. In this case we’re referring to the Word application object. We have to put the Word.Application name inside double quotes as plain text.
That annoying comma …
Unfortunately, the comma in front of the application name but inside the parentheses is required. We left it out because were letting the script decide the location of the application object. We don’t know it, and we don’t need to know it to interface with Word (although ignorance is not always bliss).
I don’t like how it makes the command look messy and unfinished, but it is easier to just leave the first argument out since the main point is really just telling Dragon what type of object we’re using.
Declaring the Object
If you happen to leave Option Explicit on above as I usually do, there are two ways to be more specific about the type of variable you’re using:
This is only slightly better. It feels kind of like cheating because we’re just saying that the WordApp variable is an “Object.” That’s not saying much other than it’s not a number or something else simple. You almost expect the script editor to balk and make you be more specific, but in fancier terms, this is called “late binding.” We’re letting the program decide what kind of object it is when it eventually knows. Like many other things, this approach has pros and cons. Here it makes the script easier to write which is good for us.
As a quick refresher if you're rusty, we use Dim to tell VBA we're about to declare a new variable with a type. There are many different variable types like integers, string (plain text), ranges, etc.
I definitely prefer to be more specific but check out the extended content if want to know more since this case requires a special library which isn’t available by default.
Gotchas
If Word is not open, we’ll get an error message. We could instead use the CreateObject(…) function instead.
Untortunately, this will open a new instance of Word which probably isn't what we want most of the time. We could add a condition to handle this case, but I don’t want to stretch out this script or article since the point is to give a simple introduction to running a custom Word macro using a Dragon Professional voice command.
Think about this …
Think about what we have now.
We can use this WordApp variable to refer to the open Word application and perform many of the commands we would use in VBA directly … which we can then invoke using a voice command in Dragon Professional.
That’s powerful.
And it’s also why I like this script more than trying to use send key commands to manually control Word via voice commands.
Run the macro …
Now we get to run our Word macro.
It’s actually embarrassingly simple at this point. We use the Run method (an action associated with the variable object) of the WordApp variable. Assuming our Word macro is called MyMacroName, the command is:
MyMacroName should be in double quotes if it is the actual name of your macro in Word, but I tend to use a string variable to store the name.
This version is more convenient if you make a function to contain all this stuff. It makes it easier to use in other scripts and to handle any potential errors that pop up, and they will.
The simplicity and power this simple command provides is amazing to me. We can run almost any macro we create in Word with a voice command.
Final Macro
Putting the above steps together, our simple final script is:
In fact, this script is a little better than even a native VBA macro in Word since any macro we want to use with a keyboard shortcut in Word cannot have any parameters. This leaves us creating repetitive macros for “move up” or “move down” and the like. In Dragon Professional advanced scripting, we can specify the parameter arguments in the script which allows us more freedom when defining our voice commands.
If your macro has a parameter, see the extended content below.
What more can we do?
We’ll get into more detail in later articles, but we’ll create scripts that allow different word combinations via list variables, such as varied document elements or directions, when invoking them. It's not rocket science, but it will significantly improve our capabilities when using Dragon Professional and Word together.
Improvements
We have two improvements below. The first is cosmetic most of the time (unless you encounter errors), but the second is a major upgrade to our Dragon Professional scripting capabilities.
More specific variable names
I prefer to be specific than using “As Object” when defining our WordApp application variable.
It’s less confusing if you or someone else ever comes back to the macro, and for objects like the Word application, the editor will give you hints via context menus about the commands as you work (called IntelliSense in Microsoft apps). It’s not a dramatic improvement when creating scripts and macros, but it’s nice when you need it.
How can we identify the word application object specifically?
Enable Word scripting library
First, we need to enable the library that gives us access to such things. Press Alt+Enter when inside script editor and click the checkbox for Microsoft Word 16.0 Object Library.
Previous versions of Dragon Professional (or equivalent in earlier versions) allowed access via the right-click context menu, but that menu option no longer seems to be present in v16.0. You’ll have to scroll down the long alphabetical list to somewhere in the middle.
As you peruse the list, your brain might start sparking with all the possibilities of interacting with so many different things. We are focused on Microsoft Word, of course.
Declare Word application variable
Once that library is enabled, we can directly refer to the Word.Application variable type.
This is called early (or static) binding since we’re telling the script interpreter ahead of time what type we’re using for the WordApp variable.
Connect to Word
Now we just set up the connection to the open Word application just like in the first version above.
Run the macro
We run the macro as before also.
What about macro parameters?
What if your macro has a parameter like the number of paragraphs to move?
In Word, we could create functions and subroutines with parameters to make them easier to apply to general document elements. We would then use these in other macros to make them easier to create. Can we make use of these here in Dragon Professional advanced scripting?
If you’ve come this far, it’s actually easy. Simply add a comma and your parameter value after it.
If the parameter (called an argument when you give it to the function) is plain text, it needs to be in double quotes. If it is a number, then just the number will work. You can also add more arguments as needed up to 30, but I rarely need more than four.
Number of parameters must match the Word macro
The number of arguments given in the Run method after the macro name must match the number of parameters in the Word macro. A missing or an extra, unnecessary argument will both cause an error. The exception is you can still rely on Optional parameters that have default values in your Word functions and subroutines which is handy at times. These you can omit if desired, but they must be omitted from the last parameter and backwards if so.
Argument and macro parameter types must match
If a macro argument is given to the Run method, the data type must match the expected parameter type in the Word macro exactly. Even two number types, such as Long and Integer, which are very similar in principle (both are "counting number" types) will cause the script to crash. We can detect such errors using error handling like we do in this improved function version, but I once lost a day's work tracking down a bug until I finally realized I had repeated this simple error, so be careful.
Set WordApp to Nothing
To finish, we should reset the WordApp application object variable to Nothing.
Technically, this isn't required, but it's nicer to the program to tell it you're done with the object variable.
Improved Final Macro
The improved final (still simple) macro isn’t much different, but I prefer this version.
See an upcoming member article for a better way to handle this. Although in full disclosure, Dragon Professional advanced scripting doesn’t let us encapsulate the Word macro functionality as well as it should for a professional application (in name and price), but I’ll explain more about that in the other article.
