What is the Selection?
If you’ve been following along with the newsletter or blog articles, we’ve used the Selection object dozens of times in various macros. It’s mostly intuitive, which is one of the benefits of using VBA for macros in Word, but what is the Selection really?
Thanks for your interest
This content is part of a paid plan.
For the user ...
The selection is what you see in the document as you type and edit. It may span text, other document elements, or just be an insertion point (i.e., the blinking I-bar waiting for you to type some new text).
For Word ...
The Selection is Word’s internal representation of the actual, visible selection seen by the user in a document. It consists of various commands (called “methods” which are actions we can perform using the Selection like moving, deleting, etc.) and properties (data about the Selection like the Start and End positions).
Using the Selection
This article is not an exhaustive discussion of the Selection object nor of its comparison to Ranges, but it does get you started understanding more of the under the hood details, so you can write more informed macros in Word.
In VBA we access the Selection using the keyword
Often, we indent the command as shown, but that’s only for us humans to organize our macro steps. The VBA editor doesn’t care. See this article for a quick introduction to creating an empty macro.
Accessing commands or properties
We access methods or properties of the Selection (or any other VBA object) simply by using a dot after the name and then give the name of the property or method we want to use. For example, this statement represents the beginning position of the Selection in the document.
Command options
Some methods allow for options (called arguments) to give more control over what happens. We can specify options on many commands like
This command moves the insertion point down in the document by three lines (see more on several move methods below).
This article is not an in-depth commentary on using arguments with commands, but many of the newsletters or blog articles take tiny steps when introducing these concepts for the first few times.
Selection is visible on screen
Any direct manipulation of the Selection is usually visible to the user while the macro runs. For short macros, this works well.
Connection to Ranges
The Selection and Ranges are similar objects in VBA and share many features, so many commands and properties in a macro will often be similar if you use either object type as the basis for your macro steps. For simplicity as we move forward, when I refer to “ranges,” I mean range variables that allow us to access their various methods and properties.
Similarity to Ranges
In fact, the Selection is essentially a special, unique document Range (it has a Range property). Important similarities between the Selection and Ranges are:
- Ranges share many of the same methods with the Selection such as moving text, copying, pasting, deleting, inserting text, etc.
- Ranges have Start and End positions which act almost exactly the same as with the Selection (except the Selection has an “active” side, but ranges do not).
- Ranges and the Selection can both access collections of document elements like sentences, characters, paragraphs, hyperlinks, etc.
And more ...
Differences with Ranges
However, there are differences between the Ranges and the Selection object.
And there a quite a few more differences of varying importance. Some of the more common distinctions are highlighted in a little more detail below.
Lean toward using Ranges
There are exceptions, but it is generally preferable to use Range variables to manipulate a Word document.
Slow and flickery updates
Why might we avoid using the Selection in a particular macro?
- Changing the Selection immediately and visibly updates the screen as the macro runs. For longer macros these screen updates can make the macro run much more slowly.
- Real time changes to the Selection can be distracting when the screen flickers as the macro updates the document.
- Since the Selection is part of the document, if your macro stops mid run due to some (hopefully small) error, the previous changes are still made in the document. The user sees some intermediate state of your macro which is probably not good. Using Ranges guards a little better against potential errors in your macro.
While we can turn off screen updates within a macro, using the Selection directly for the bulk of the macro should probably be reserved for only the simplest macros where the user already expects to immediately see the change represented on the screen. For these cases, the macro runs so fast the change looks immediate anyhow.
Insertion point is unchanged with Ranges
A side benefit of using Ranges is the user’s selection or insertion point is unchanged. This feature is often my main purpose for using them. The macro can update the document, and the user can immediately go back to what she was doing in the same location.
What are the exceptions?
Why might we choose or be forced to use the Selection in a macro? A few cases include
- When the macro is super simple, it’s just more convenient, with no downside, to use the Selection. The changes are essentially immediate from the user’s perspective anyhow.
- Some hidden document bookmarks are not available to a Range variable.
- Only the Selection can access line breaks on the screen (see below). Ranges cannot access screen lines.
Common Selection features
One of the reasons we might use the Selection is just because it’s easier sometimes. Here are some of the more common features.
Selection move methods
One of the most convenient features of the Selection are the specialized move methods: MoveRight, MoveLeft, MoveUp, MoveDown that do exactly what the names imply.
Some standard move units mimic how a user would normally move around in a document.
Several intuitive move Units are available corresponding to common cases.
- Up and down movement: wdLine, wdParagraph, wdScreen (works something like PageUp or PageDown on your keyboard), or wdWindow (top or bottom of the active window).
- Left and right movement: wdCharacter, wdWord, and wdSentence
Various newsletters or articles on this blog introduce other more specific move commands which come in handy for targeted tasks such as moving to specific characters or manipulating the Start or End of the Selection.
Lines and the Selection
With the Selection move commands, you can use an additional move Unit (compared to Ranges) for lines
But wdLine happens to be the default move Unit, so you can accomplish the same thing in the document with just
Most of the time, a move command collapses the Selection to an insertion point, but all these particular methods also have an Extend option that provides another way of creating or extending selections in the document.
Selection Start and End
The Selection has a Start position and an End position in the document. These two positions indicate what text or other document content is selected in the document.
Start is toward the beginning of the document and End is toward the end. If the Start position is less than the End, then any text or contents in between are part of the document selection, If the Start and End positions are the same, there is no selection. There is only an insertion point in the document (i.e., the blinking I-bar waiting for you to type text).
With the Selection, one side is considered “active,” but the distinction usually doesn't matter in practice.
A Range also shares Start and End properties except a Range doesn’t have an active side, and the Range is invisible to the user.
Cannot control block and non-contiguous selections
While the user can create and manipulate block and non-contiguous selections, a macro has no way to control them. As of the date of this article (February 6th, 2024), they are restricted to user-only interactions.
Collapsing the Selection
A common task inside a macro is to get rid of the Selection by collapsing it.
This helps us guard against unforeseen conditions when the user runs the macro. As the name implies, this command collapses a selection previously spanning some document content into an insertion point. Moreover, it has no effect on an insertion point, so after using it, we can be confident we are working with an insertion point in the document.
If you prefer, you can collapse toward the end of the Selection using the Direction option
This variation comes in handy sometimes. wdCollapseEnd is one of the two direction constants. The default option is wdCollapseStart which is why we didn’t need to specify it in the first Collapse command.
Storing the current Selection as a Range
Often we want to access the initial Selection to manipulate something relevant to the user’s current work in a document. Using a Range allows us to do much of the work invisibly before revealing the final result, so storing the initial Selection in a Range variable is frequently one of the early steps in a macro.
Since a Range isn’t quite the same thing as a Selection, we instead store the Selection’s Range.
Now our Range variable MyRange matches the Selection at this moment in the macro. As with the Selection, MyRange may span text or just be equivalent to an insertion point (i.e., the blinking I-bar). In Range terms, if it spans text, the Start position is less than the End position. If the initial Selection was an insertion point, MyRange’s Start and End positions are also the same.
Since a Range contains more information than just a value like a number or plain text, we have to use “Set” when assigning it a Range variable. See this article for a brief introduction to Ranges.
For simple macros, I will often use an abbreviated variable name as just r
just to keep the typing down as I create a macro.
Accessing document elements
Another common task is to access and modify parts of the document. For example, if we want to modify a specific paragraph contained in the Selection, we can start by accessing the collection of paragraphs within the Selection using
The Paragraphs property contains a collection of all paragraphs in the Selection.
First or Last paragraphs
Conveniently, we can access the first one using
Even if there is only an insertion point in the document, the current paragraph is still the “First” paragraph. Similarly, we could access the last paragraph with
Often these two are all you need. Then we take an action on that paragraph using the various Paragraph methods or properties. For example, we could modify the paragraph style with
Accessing other paragraphs
If you need a paragraph from somewhere in the middle of the Selection, you can use parentheses with the paragraph number inside it like
This command accesses the fourth paragraph in the Selection assuming it exists. We could also use a number variable inside the parentheses, but more often than not, we usually don't need to directly access other paragraphs in the middle of the Selection.
If the Selection is large, we would probably instead do something too all paragraphs in the Selection ....
Iterating over collections
Another common task would be to do something to all paragraphs (or whatever collection) in the Selection. The specifics of this requires loops, but there are several types depending on what you need. We’ll leave the details to another article, but a quick and dirty example might be
The CurrentParagraph will change as Word switches to each successive paragraph in the Selection, and you can do whatever you wish to it inside the loop.
Collection caveats
Is it a Range or an object?
Paragraphs and some other collections (Hyperlinks, Shapes, etc.) contain actual objects themselves as VBA sees them, so they have their own methods and properties.
Other collections like Sentences, Words, or Characters just indicate ranges in the document. For example, this would be invalid
This fails because a sentence does not have a style property like a paragraph does. Since a Sentence in the Sentences collection is essentially a Range, we could instead do something like
This command copies the first sentence of the Selection to the clipboard since all Ranges have a Copy method.
Selection Types
For many macros, we want to take different actions depending on whether there is an initial selection or not in the document when the macro is run. Sometimes we take an extra step in one of the cases (such as selecting the whole starting paragraph if no user selection exists), or we might just do different steps in either case.
For this blog, we usually focus on Selection types that involve text in one way or another. See a previous article for a brief introduction to Selection types and how to detect and make decisions in a macro based on it.
