Office Space: Tips and Tricks for Scripting Microsoft Office Applications

Welcome to Office Space, the new column that offers tips and tricks for scripting Microsoft® Office applications. We’ll post new tips every Tuesday and Thursday; to see an archive of previous tips, visit the Office Space Archive. And if you have particular questions about Microsoft Office scripting, feel free to send them to scripter@microsoft.com (in English, if possible). We can’t promise to answer all the questions we receive, but we’ll do our best.

Changing the Background Color of a Paragraph

Last week we told you how you can change the background color of a cell in Microsoft Excel. (If you missed that column, you should be ashamed of yourself; you should also click here.) That was nice, but – in this day and age – we figured it would only be a matter of time before someone sued us, pointing out that we were being patently unfair by telling people how to change background colors in Excel yet not extending the same courtesy to Microsoft Word. So we decided to nip that lawsuit in the bud by – yes – explaining how you can change the background color of a paragraph in Microsoft Word.

Changing the background color of a single paragraph can be a little tricky, and for two reasons. First, you have to be able to identify the paragraph’s location in the document; after all, you can’t change the background color of a specific paragraph unless you can tell the script which paragraph you want changed. Second, it’s not exactly intuitive which property controls the background color of a paragraph. (If you can’t wait to find out, it’s Shading.BackgroundPatternColor. But we’ll talk about that in a bit more detail shortly.)

Oh: and you don’t set colors using names like red, blue, or green; instead you set colors using values like 16777215 or 65535. Thought we’d better mention that while we we’re at it, too.

But don’t despair: this doesn’t mean that you can’t change the background color of a paragraph. It just means you need to do a little planning before you start writing your script.

Let’s take a look at a script that creates a Word document and adds three little paragraphs. The first paragraph is shaded gray, the second shaded white, and the third shaded yellow. In other words, it produces something that looks like this:

Yes, we could sit here and stare at the picture all day, too. But we have work to do; in particular, we have to show you the script:

Const wdColorWhite = 16777215
Const wdColorGray10 = 15132390
Const wdColorYellow = 65535

Set objWord = CreateObject("Word.Application")
objWord.Visible = True
Set objDoc = objWord.Documents.Add()
Set objSelection = objWord.Selection

i = 1

objSelection.ParagraphFormat.Shading.BackgroundPatternColor = wdColorGray10
objSelection.TypeText "This is the first paragraph."
objSelection.TypeParagraph()
i = i + 1

objDoc.Paragraphs(i).Range.Select
objSelection.ParagraphFormat.Shading.BackgroundPatternColor = wdColorWhite
objSelection.TypeText "This is the second paragraph."
objSelection.TypeParagraph()
i = i + 1

objDoc.Paragraphs(i).Range.Select
objSelection.ParagraphFormat.Shading.BackgroundPatternColor = wdColorYellow 
objSelection.TypeText "This is the third paragraph."
objSelection.TypeParagraph()
i = i + 1

objDoc.Paragraphs(i).Range.Select
objSelection.ParagraphFormat.Shading.BackgroundPatternColor = wdColorWhite

You’re right: the code isn’t half as pretty as the screenshot. But let’s see if we can explain how it works.

We begin by creating three constants; these represent the background colors we plan on using in the script. How did we know that wdColorYellow represents the color yellow, and that it has a value of 65535? Hey, we just looked it up in the Microsoft Word VBA Language Reference (look at the values for WdColor).

Next we create an instance of the Word.Application object, make our instance of Word visible (by setting the Visible property to True), then add a new document and create an instance of the Selection object. All this just gives us a blank Word document to work with. As soon as we have that document, however, we’re ready to have some fun.

We begin having fun by setting the value of a counter variable named i to1. Why? Well, to shade individual paragraphs in a Word document we need to identify and select those individual paragraphs. One easy way to do that is simply to refer to the paragraphs by number (the first paragraph in a document is paragraph 1, the second is paragraph 2, etc.). Each time we type a new paragraph we’ll increment i by 1; that way, we’ll know exactly which paragraph we’re working with at any time.

Next we create – and shade – the first paragraph in our document, using this code:

objSelection.ParagraphFormat.Shading.BackgroundPatternColor = wdColorGray10
objSelection.TypeText "This is the first paragraph."
objSelection.TypeParagraph()
i = i + 1

All we’re doing here is setting the value of the ParagraphFormat object’s Shading.BackgroundPatternColor to wdColorGray10; wdColorGray10, of course, is one of the constants we set at the beginning of the script, and represents the 10% Gray color. We use the TypeText method to type some text in our paragraph, then use the TypeParagraph() method to add a carriage return-linefeed and mark the end of paragraph 1. (The TypeParagraph() method is equivalent to hitting ENTER on the keyboard.)

That’s it for paragraph 1. We increment the value of i by 1 (so that i is now equal to 2) and start working on paragraph 2:

objDoc.Paragraphs(i).Range.Select
objSelection.ParagraphFormat.Shading.BackgroundPatternColor = wdColorWhite
objSelection.TypeText "This is the second paragraph."
objSelection.TypeParagraph()
i = i + 1

The one substantial difference here (besides the fact that we set the BackgroundPatternColor to white) is this line of code:

objDoc.Paragraphs(i).Range.Select

This line sets the value of the Selection object to a range encompassing paragraph 2 in our document; remember, i is equal to 2, so objDoc.Paragraphs(i).Range is equivalent to saying, “Set the selection to paragraph 2.” With paragraph 2 selected we can change the background color, type in some text, press ENTER, then move on and start working with paragraph 3.

Incidentally, suppose you wanted all your paragraphs to have the same background color. In that case, you don’t need to go through this whole process of selecting paragraphs and changing background colors. As you’re probably aware, any time you hit ENTER in Word your new paragraph carries on with the same formatting applied to the previous paragraph. (Yes, there are some exceptions to this, but it’s true more often than not.) The same thing occurs with Word documents created using scripts. If we want all our paragraphs to have a gray background all we have to do is set the background color at the start and then just keep adding new paragraphs; by default, each new paragraph will have the same formatting as its predecessor. Run this script and you’ll see what we mean:

Const wdColorGray10 = 15132390

Set objWord = CreateObject("Word.Application")
objWord.Visible = True
Set objDoc = objWord.Documents.Add()
Set objSelection = objWord.Selection

objSelection.ParagraphFormat.Shading.BackgroundPatternColor = wdColorGray10
objSelection.TypeText "This is the first paragraph."
objSelection.TypeParagraph()

objSelection.TypeText "This is the second paragraph."
objSelection.TypeParagraph()

objSelection.TypeText "This is the third paragraph."
objSelection.TypeParagraph()