Capitalize the current sentence

We create another macro in a series aimed at tackling menial editing tasks. This macro is simple and yet practical where the goal is to let the computer do what it does best, so we can keep our fingers engaged with the human part of the editing process. While it may not be the most productive macro in the automated editing world, it’s nice to capitalize the first word of the sentence from anywhere inside it and just continue working.

What are the manual steps?

What steps are required to manually capitalize the first word of the current sentence?

1. Use the mouse (slow) or keyboard to move to the beginning of the sentence with extra key taps if double quotes or parentheses are present
2. Delete the first character
3. Type the new capitalized first character

We've done this thousands of times, but let's trim the steps down to one shortcut.

We can cycle the capitalization of a word or a selection using a standard keyboard shortcut Shift+F3, but we still need to move to or select the word before we can change its capitalization. A previous article covered assigning shortcuts to a couple Word commands to help with sentence navigation in Word, but some tasks occur often enough that it's more efficient to create a specific macro to handle it.

Mimicking the above manual steps in VBA is clumsy and unnecessary, so we'll focus on solving the problem a little more like VBA intended.

What about VBA thingies (objects)?

VBA represents various document elements as virtual "objects" which encapsulate the data (called "properties") and actions (called "methods") related to its function in the document. These properties and methods allow us to manipulate the object and the associated document content. We can further declare variables to represent specific elements in the document to complete the necessary macro task(s).

What is the Selection?

The Selection (with a capital "S") is VBAs representation of the visible selection or insertion point on the screen. It's like a specialized Range (see below) with some extra properties and methods, but only one Selection exists per document. We can move it around, collapse it, delete the text, etc. Since it controls the actual selection on the screen, any changes are immediately visible unless other precautions have been implemented. See our brief introduction to the Selection for more information.

The Selection contains several collections (essentially fancy VBA lists) of any partially or fully spanned document elements including Words, Sentences, Paragraphs, Bookmarks, and more. We will use the Sentences collection in this macro.

What is a Range?

Conceptually a range is a contiguous region of document content. VBA includes a generalization of this concept called a Range (with a capital "R"). It is literally tracked using Start and End character positions in the document; but it also includes other properties and methods that allow us to control its extent, modify related document content, change capitalization, and more. See our brief introduction to Ranges in Word VBA for more information.

Many document elements are treated as ranges such as characters, words, sentences, headings and their content, etc. Like the Selection, a valid range contains collections of any partially or fully spanned document elements. We will use the Words collection of a range for this macro.

Create the empty macro

Open the VBA editor (Alt+F11 in Windows or Option+F11 on a Mac) and create the following empty macro. If you prefer, a previous post covers creating an empty macro using the application interface.

The single quote tells VBA the rest of the text on that line is a comment meant for human readers. Most macros include a brief description at the top that explains the purpose of the macro as well as any special considerations or capabilities. We start our macro steps on the empty line.

Capitalize the first word of the sentence

To carry out the capitalization, we will need the Case property of a valid VBA Range. Most of the work in this macro is spent identifying the intended range of the first word of the current sentence.

What are the macro steps?

The manual steps usually serve more as a guide for relevant document elements than providing the desired sequence of macro steps. Until we get used to VBA concepts, the differences between VBA and the manual approach can be a brain twister.

In practice, we identify the relevant document elements we need to modify and then isolate them using the corresponding VBA objects. If you plan to write more than a few macros, learning to think more like VBA is worth the effort since it sees the document internals, and it can do some tasks with ease that we can’t replicate as easily with a keyboard and mouse.

What steps provide a good VBA solution to our current capitalization task?

1. Get the first sentence range
2. Exclude any double quotes or left parentheses (not obvious at this step)
3. Identify the first word range of the sentence range
4. Set the Case property of the word's range to capitalize it

As a bonus, these steps do not modify the extent of the current Selection, so they leave the insertion point in place or the initial selection intact. We can just keep working.

The order of steps 1 through 3 require a little testing or foreknowledge (or more substantive Word VBA experience), but we'll explain more below.

Identify the first word range

The task is easy, but it takes several range modifications to get the intended first word of the current sentence.

Declare working range variables

It is convenient to declare two working range variables, so we can tweak them based on the nearby punctuation.

We declare most variables in VBA with the Dim keyword, and "As Range" tells VBA what type of data the variable stores. I usually precede range variables with a lowercase "r" to remind myself what type of data it stores. Multiple variables may be declared on the same line if they are separated by commas, but each should have its own type (any missing a type will be assigned a generic type by default).

Just using a single range would be okay in this macro (I would probably just call it r for brevity), but the variables are called rSentence and rWord for an extra bit of clarity. VBA doesn't require variables to be declared by default, but it's a good habit as your macros become more complex. Being more specific is clearer, and it helps prevent any unintended consequences.

Get the first sentence Range

We begin by identifying the current sentence using the Sentences collection of the Selection.

We need the range of the first sentence, so we use the collection's First property.

The Sentences collection stores the ranges of the sentences (unlike Paragraphs or some other collections which store objects with that specific type), so the First property refers to the actual sentence range. If the initial Selection spans multiple sentences, this identifies just the first one. Even partial sentences are included in the collection, so this reference works even if the macro starts with an insertion point or if only part of the first sentence is selected in the document.

Set the first sentence range

Now, we can assign the sentence range to our rSentence variable.

We need the Set keyword because a range is a VBA object not just a value, but then the variable name name is followed by an equals = sign just like in other assignments. This range assignment works because the First sentence reference returns a range (not its document text), so we can assign it to a range variable. Both types agree.

Trim beginning of sentence punctuation

As a writer, I prefer my editing macros work as naturally with double quotes in dialog as they do with regular text. In fact, the Case property assignment (see below) will fail in Word for Windows if the current sentence begins with a double quote. Upper and lowercase have no meaning for punctuation marks, so nothing happens when the case is applied.

If we're already excluding a double quote, it's a simple task include a left parenthesis or a left square bracket at the same time. The latter are sometimes convenient in notes or other work-related documents.

The easiest method to trim characters from the Start of a range variable uses the MoveStartWhile method.

MoveStartWhile requires a set of characters to trim from the range which are assigned as plain text to an option named Cset. As the name implies, the method moves the Start position of the range variable while it keeps finding any characters in the set at the Start position. The command stops as soon as any other character is found. The default direction is forward by any number of matched characters which is what we need for this macro, so we can omit the Count option.

Trim grouping symbols

The left parenthesis and left square bracket are "([" as plain text, so we assign this string to the Cset option using a colon equals := symbol.

This command now removes any left parentheses or a left square brackets from the beginning of the range.

Trim double quotes

Similarly, we need to remove a left double quote or a straight double quote. Unfortunately, a straight double quote character is also used to define plain text strings like "abc" on Mac and Windows systems, and keyboards insert straight double quotes by default (Word automatically converts them to "curly" left or right double quotes based on the context).

The easiest way to handle double quotes is to refer to the character number through a character function ChrW(…). Each character has a special number from a particular Unicode character table. We "pass" this number to the function to get the equivalent text character seen on the screen.

• Left double quote “ → ChrW(8220)
• Straight double quote " → ChrW(34)

We allow both left and straight double quotes since Word sometimes does not catch or properly convert the keyboard straight double quote to a left double quote (or sometimes we unintentionally undo the change). Include these characters with the Cset option:

We used a plus + sign to add the plain text characters together (called concatenation). This just smooshes them together into one string which is what the Cset option needs. An ampersand & also works (slightly differently) for concatenation, but I prefer the plus notation since it looks better (less programmy). Fortunately, the numbers used with ChrW(…) are the same between Word for Windows or Mac.

Why use the sentence range?

Why did we take the time to exclude the punctuation now?

We need to the remove the punctuation mark using the sentence range, not the upcoming first word range, since punctuation is counted as a separate "word." Thus, a punctuation mark would mess up our later identification of the proper first word (Word for Mac is a little smarter about it when applying the Case property, but it's not without its own idiosyncrasy). Counting punctuation as separate words is a strange choice in my opinion based on its everyday meaning, but we need to work around the feature. Using the first sentence range is the easiest way to exclude punctuation without needing to add extra steps to tweak the intended first word range later.

Get the first word range of the sentence

In order to avoid a mid-sentence capitalization issue (see the gotcha below), we identify the first word range. We've already identified and possibly trimmed any punctuation marks from the first sentence range above, so we need to reference its Words collection.

The Words collection contains all words either fully or partially contained in the range. We just want first word, so we use the First property of the collection.

Like a sentence, a word reference is just a document range, so this refers to the range of the first word of the first sentence based on the initial selection or insertion point position when the macro is run.

Assign the first word range

Now, we can assign the working range for the first word of the current sentence:

We don't actually need two different working ranges, but we use separate names for extra clarity.

Do we need both collection references?

We cannot just refer to the Words collection of the Selection directly.

Referring only to the Words collection does not work for this macro because it would return the first word of the Selection not the first word of the first sentence.

In this text, the insertion point precedes the word "document". We want a range reference to "This" for the first word of the sentence, but directly referring to Selection.Words.First would instead return the range for the word "document" since it is the first word at the current Selection position.

That's not what we want.

Better understanding how VBA works will help us writer better macros faster. By identifying the first sentence, we ensure we're getting the intended first word of that sentence range regardless of where the Selection is initially located. A similar argument applies if the macro is run with an initial selection.

Change the case

Every valid range has a Case property that controls the case of the word(s) in the range (it acts more like a method than a property), so we refer to the Case property of the first word range.

The Case property is stored as a numerical value, so we assign the word title case wdTitleWord from the case constants table to capitalize the word in the document.

We assigned the Case property using an equals = sign since it is stored as a numerical value. The property just changes the current case of the target text based on the assigned case constant. It does not store the case in any way.

Using a case value wdTitleSentence as a sentence title constant would also seem natural in this macro, but it will not work the same in Windows as wdTitleWord if the sentence begins with a punctuation mark (Word for Mac and Windows differ some in this aspect). The Case assignment with the sentence title constant analyses the placement of the text in the sentence when deciding on the proper case.

Cycle capitalization?

We could instead cycle the capitalization of the first word of the sentence similar to how the standard Word keyboard shortcut Shift+F3 acts, but I rarely want to do that. If that behavior sounds interesting to you, change the Case constant assignment to wdNextCase.