Create the empty macro

A previous post covers creating an empty macro like the one shown below. When you’re done, you’ll have something like:

The single quote tells VBA the rest of the text on that line is a comment meant for human readers. We start our macro steps on the empty line.

Also create a second macro to search for parentheses forward in the document. I'll explain the reason for two of them later.

Since this article focuses on text-based punctuation, we’ll assume we’re dealing with text only in this document, so I won’t refer to shapes, frames, or whatever else that’s not important here.

Stand-alone

We’re revising a previous, simpler macro to automatically select parenthetical or dialog text.

This article stands alone, so there is significant overlap in the content if you’ve read the other article for the simpler version, but this version delves a little deeper into some of the specifics of how Word sees documents and how we can manipulate them in a macro.

Why a revision?

The earlier version of this macro was fully functional, but it experienced a small issue with spurious, strange selections if the desired punctuation didn’t exist in the direction of the search.

If you’re like me, it’s aggravating to have a gotcha stalking me, ready to pounce when I least expect it even if I know it’s innocuous. More like being attacked by a kitten than a mountain lion, but hey, those little claws can still scratch and make an owie!

The variation developed below makes the macro more robust to missing punctuation with cleaner, albeit a little more complicated, steps.

Selection versus Ranges

The original version of the macro used the Selection object for all commands for simplicity.

The Selection is basically an enhanced Range in the document with special methods and properties related to a real selection in the document. There are differences between them, but for this macro, they have nearly the same features. As a result, most of the core elements of the original macro are retained.

As you get used to writing your own macros from scratch, using Ranges is generally the better way to work.

See this article for more information about the Selection object in general or this article for a brief introduction to Ranges.

Define the working range

In this version, we use Ranges since they allow us to commit to the selection only after we know it is correct

We start by simply storing the initial Selection in a Range variable.

Recall we must “Set” a Range variable since it contains more information than regular number or text values.

When working with MyRange, we lose a few features specific to the Selection; but for this macro, the distinctions don’t matter.

Start and End with Ranges

Like the Selection, a Range also has Start and End positions. The difference is a Range is invisible to the user.

The initial Selection when the macro is run may span text or just be an insertion point (i.e., the blinking I-bar waiting for your new text in the document).

In the former case, MyRange’s Start and End values will be at different positions in the document. In the latter case, the Start and End positions will be the same.

Range manipulations are invisible

The nice thing about Ranges is any changes are invisible to the user unless a command inserts, deletes, or otherwise modifies text in the document. Thus, we can manipulate them independent of the Selection, and the user doesn’t see anything happening on the screen until we’re ready to commit to the changes in the document.

Assumptions, assumptions

Before we create the macro, we need to understand more about what we are looking for in the document.

Sounds obvious at first, but do we assume the user runs the macro when the insertion point (i.e., the blinking I-bar waiting for new text to be typed) is already between the parentheses? Or do we want our macro to find any nearby parentheses?

The differences are slight, but the specific steps to solve the problem matter in most cases.

Start between the parentheses?

If we assume the former, it simplifies the macro steps since you don’t have to worry about which direction to search in the document at the start of the macro. You know the open parenthesis is on the left, and the close parenthesis is on the right.

Start anywhere including outside the parentheses?

Personally, I like the latter approach since it can find the parentheses anywhere in the document. A macro is also more practical when the user doesn’t have to remember specifics about how it works to use it.

The trade-off is the steps change depending on whether we are looking forward or backward in the document. That's worth it for me since have a more productive macro to use. Both versions happen to work the same if the insertion point happens to already be between the open and close parentheses.

As we develop the macro below, we’ll work on the search left version and tweak it when we're done to search right when we’re done by changing the order of the search and move commands.

Find open parenthesis

We first want to find a set of parentheses before the current insertion point, so we start by searching backward in the document for a left parenthesis “(”. This step is quite general since it works regardless of whether the insertion point is already between the parentheses or not.

Move to open parenthesis

The basic command to move MyRange’s position to a specific character uses the MoveUntil command, so we could try

The command does just as its name implies. It moves MyRange’s position until it finds any one of the characters given in the Cset option. Here we are only looking for a left parenthesis, but you could in principle include any number of characters.

Most regular Cset characters are specified inside double quotes as shown, but some special characters have to be added separately using a few standard Word character constants or a character function for many other special characters.

The Count:=wdBackward option instructs the command to move backward in the document just as the name of the constant implies. The default is forward.

Does the open parenthesis exist?

What if the open parenthesis doesn’t exist in the document? We need a way to check first and avoid any issues if not.

Using function return values

We’ve essentially ignored any information “returned” by commands we’ve called. Most commands will return a value related to the action, of course, and we can use this information to make decisions in our macros.

Specifically for this macro, we try to move the Range’s location to the previous open parenthesis, and then check what the command says before we do anything else. The MoveUntil command returns the number of characters moved (plus or minus 1 depending on the direction) which we store for later use in a new number variable

Negative values indicate a move backward in the document and positive values a move forward. A zero value indicates no move was made because the command did not find (any of) the character(s) given in the Cset option.

Different function notation

As shown in the command above, when storing the returned value in a variable, you must include any options in parentheses. This makes the command look more like a formal function call in other languages.

Checking how many characters were moved

We only want to finish the rest of the macro if an open parenthesis was found. For MoveUntil, this corresponds to a non-zero return value, so we can check against that (we could also just check less than zero since we are moving backward in the document)

Recall the <> symbol is “not equal” (i.e., asking if it is less than or greater than the number on the right), so the If statement is checking whether the returned value is not zero before running the other steps inside the conditional statements.

All the following steps below are included inside the If statement.

Some details

It’s useful to understand some details about the Selection and the document before moving forward. This will also give us some practice understanding macros and how we can bridge the gap between specific macro steps and achieving the overall effect we wish in our document.

At an open parenthesis

If the open parenthesis is located, the Range position is moved just to the right of the newly located open parenthesis. Specifically, the Start and End properties of MyRange are both set to the same position in the document.

No selection yet

Since the Start and End positions are the same, there is no selection in the document yet.

MoveWhile and MoveUntil commands

Both MoveWhile and MoveUntil commands use a Cset option where you can specify move or stop characters, respectively. The catch is the commands move or stop when they encounter any of the characters. That is, Cset:="abcd" will move until it encounters an a or b or c or d not the word abcd.

These commands do not act like a Find operation in your document. You have to use a Range Find command (technically it's a property) to do that.

Include open parenthesis in the selection

Now we start creating the desired selection of parenthetical text. Most of the time, we’ll include the open parenthesis as part of the range using

MoveStart tells Word to move the Start position of MyRange by the given Unit type. We omitted the Unit since the default is to move by character (i.e., the command assumes a Unit:=wdCharacter option if it isn’t given).

The Count:=-1 option tells VBA to move backward (the negative) by 1 Unit to include the open parenthesis in MyRange.

The End position of MyRange is not changed with this command.

Since Start and End now have different positions in the document, we now have a real, albeit incomplete, MyRange spanning a grand total of one character in the document. Time to celebrate!

Include any spaces

If you want to include any spaces on the left side of the selection (not my preference), you could also add

This MoveStartWhile command acts like MoveStart except it keeps moving the Start position while it keeps finding any characters given in the Cset option which is just a space here.

Find close parenthesis

Now that we are somewhat confident our incomplete range is currently in between a pair of the open and close parentheses, we can proceed by moving the End position of MyRange to the close parenthesis.

Since we have already found and included the open parenthesis, we don’t want to disturb the Start side of MyRange for the rest of the macro.

Select to End position

The MoveEndUntil command moves MyRange’s End position to a specific character or any of a set of characters again given by a Cset option.

The Start position is unchanged by this command. Since we are moving the End of MyRange forward, we are extending the selection in the document.

But what if the close parenthesis doesn’t exist?

Check whether close parenthesis exists

To verify whether the close parenthesis exists, we need to store how many characters were moved when trying to reposition the End of MyRange to the next close parenthesis. We again store the value returns by the command

The MoveEndUntil command returns how many characters were moved (plus or minus 1 depending on the direction) just like the MoveUntil command.

We then add another check for whether the command found a close parenthesis exists before committing to any other changes (remember MyRange is still invisible to the user).

The rest of the steps below will be included inside this close parenthesis check.

Include the close parenthesis

Most of the time, we’ll include the close parenthesis as part of the range

The MoveEnd command moves the End of MyRange by a specific number of Units. We don’t need any options here because the default Unit is to move by characters, and the default Count option is to move by one Unit forward in the document.

Include any spaces

Including any spaces on the right side of the range mimics how Word usually works with new selections, so we add

The MoveEndWhile command keeps adding characters to MyRange as long as it keeps finding any character given in the Cset option. We’re just adding spaces. The default is to extend the End of MyRange forward in the document, which is what we need here, so we don’t need the Count option.

The Start position of MyRange is unchanged by this command.

Finally make the selection

Finally commit to the selection we’ve identified using MyRange

The Range Select command does what is says. Whatever text MyRange spans in the document is selected for the user to see in the actual document.

This command will be inside the last close parenthesis check, so no text will be selected unless both parentheses were found.