Microsoft Office 2000/Visual Basic Programmer's Guide

Working with Bookmarks

In many ways, a Bookmark object is similar to a Selection or Range object in that it represents a contiguous area in a document. It has a starting position and an ending position and it can be as small as the insertion point or as large as the entire document. However, a Bookmark object differs from a Selection or Range object because you can give the Bookmark object a name and it does not go away when your code stops running or when the document is closed. In addition, although bookmarks are normally hidden, you can make them visible by setting the View object's ShowBookmarks property to True.

You use bookmarks to mark a location in a document or as a container for text in a document. The following examples illustrate these uses:

• You could use bookmarks to mark areas in a document that will contain data supplied by the user or obtained from an outside data source. For example, a business letter template may have bookmarks marking the locations for name and address information. Your VBA code could obtain the data from the user or from a database and then insert it in the correct locations marked by bookmarks. Once a location is marked, navigating to that location is as simple as navigating to the bookmark. You can determine if a document contains a specific bookmark by using the Bookmarks collection's Exists method. You display a location marked by a bookmark by using the Bookmark object's Select method. Once a bookmark is selected, the Selection object and the Bookmark object represent the same location in the document.
  
  
• If you have a document that contains boilerplate text that you need to modify in certain circumstances, you could use VBA code to insert different text in these specified locations depending on whether certain conditions were met. You can use a Bookmark object's Range property to create a Range object, and then use the Range object's InsertBefore method, InsertAfter method, or Text property to add or modify the text within a bookmark.

Once you understand the subtleties associated with adding or changing text through VBA code, working with bookmarks can be a powerful way to enhance your custom solutions created in Word.

You add a bookmark by using the Bookmarks collection's Add method. You specify where you want the bookmark to be located by specifying a Range or Selection object in the Add method's Range argument. When you use the InsertBefore method, the InsertAfter method, or the Text property, a Range object automatically expands to incorporate the new text. As you will see in the next few examples, a bookmark does not adjust itself as easily, but making a bookmark as dynamic as a range is a simple exercise.

When you use the Range object's InsertBefore method to add text to a bookmark, the text is added to the start of the bookmark and the bookmark expands to include the new text. For example, if you had a bookmark named CustomerAddress on the following text (the brackets appear when the ShowBookmarks property is set to True)

[Seattle, WA 12345]

you could add the street address to this bookmark by using the following VBA code:

Dim rngRange As Word.Range

Set rngRange = ActiveDocument.Bookmarks("CustomerAddress").Range
rngRange.InsertBefore "1234 Elm Drive #233" & vbCrLf

As you might expect, the bookmark expands to include the additional address information:

[1234 Elm Drive #233
Seattle, WA 12345]

Now suppose you want to use the InsertAfter method to add text to the end of a bookmark that contains the street address, and you want to add the city, state, and zip code information by using this code:

Dim rngRange As Word.Range

Set rngRange = ActiveDocument.Bookmarks("CustomerAddress").Range
rngRange.InsertAfter vbCrLf & "Seattle, WA 12345"

Note that when you use the InsertAfter method to add text to the end of a bookmark, the bookmark does not automatically expand to include the new text:

[1234 Elm Drive #233]
Seattle, WA 12345

This behavior could create problems if you were unaware of it. But now you are aware of it, and the solution is quite easy. The first part of the solution results from the benefits achieved when you use the Selection and Range objects together. The second part results from another aspect of bookmarks that you need to know: When you add a bookmark to a document in which the bookmark already exists, the original bookmark is deleted (but not the text it contained) when the new bookmark is created.

The following sample code uses the InsertAfter method to add text to the end of the CustomerAddress bookmark. It then uses the Range object's Select method to create a Selection object covering all the text you want to bookmark. Finally, it uses the Bookmarks collection's Add method to add a new bookmark that has the same name as the original bookmark and then uses the Selection object's Range property to specify the location of the bookmark:

Dim rngRange As Word.Range

Set rngRange = ActiveDocument.Bookmarks("CustomerAddress").Range
With rngRange
   .InsertAfter vbCrLf & "Seattle, WA 12345"
   .Select
End With
ActiveDocument.Bookmarks.Add "CustomerAddress", Selection.Range

If you use the Range object's Text property to replace the entire contents of a bookmark, you run into a similar problem: The text in the bookmark is replaced, but in the process, the bookmark itself is deleted. The solution to this problem is the same solution we used for the InsertAfter method in the preceding example. You insert the new text, use the Range object's Select method to select the text, and then create a new bookmark that has the same name as the original bookmark.

To see complete examples showing a custom class that handles adding text to bookmarks, see the modBookmarkCode module in WordSamples.doc in the ODETools\V9\Samples\OPG\Samples\CH05 subfolder on the Office 2000 Developer CD-ROM. You can also open the WordSamples.doc file and use the bookmark examples from the Working with Word Objects toolbar.