Working with Bookmarks

Bookmarks provide you a way to name and keep track of a particular Range. The user can even edit the Range, and the modified Range will still be accessible by its name unless the user deletes the Range.

To create and manage bookmarks, you can use Word's Bookmark dialog box. You can select some text in the document, choose Bookmark from the Insert menu, give the range of text a name, and then click the Add button to add a bookmark, as shown in Figure 8.23. Existing bookmarks can be selected and navigated to using the Go To button. They can also be removed using the Delete button.

Figure 8.23. The Bookmark dialog box.

VSTO provides some additional tools for creating bookmarks. You can drag a bookmark control from the Visual Studio control toolbox to the Word document to create a bookmark, for example. VSTO also adds any bookmarks in the document as named class member variables of the ThisDocument class. VSTO support for bookmarks is described in more detail in Chapter 13, "The VSTO Programming Model."

If you check the Bookmarks check box in the View tab of Word's Options dialog box, Word shows gray brackets around any bookmarks defined in your document. Figure 8.24 shows the brackets Word displays. Here, we have created a bookmark that includes the word brown and the space after brown.

Figure 8.24. Result of checking the Bookmarks check box in the View tab of Word's Options dialog box.

To create and manage bookmarks programmatically, you can use the Document object's Bookmarks property or the Range object's Bookmarks property. Both return a Bookmarks collection. The former returns all the bookmarks defined in the document; the latter returns just the bookmarks defined within the Range you are working with.

The Bookmarks collection's Add method adds a bookmark. It takes a required Name parameter to which you pass a String representing the name you want to use for the bookmark. The Name parameter must be one word. The Add method also takes by reference an optional Object parameter to which you pass the Range you want to create a bookmark for. The method returns the newly added Bookmark object.

The Bookmarks collection's Exists method takes a String representing the name of a bookmark and returns a Boolean value indicating whether the bookmark exists in the document. The Item property allows you to get to a bookmark given its name or 1-based index in the Bookmarks collection. The Item property takes by reference an Object parameter that can be set to a String representing the name of the bookmark or the 1-based index. Given a Bookmark object, you can get the Range it refers to by using the Bookmark object's Range property.

Listing 8.40 shows an example of working with bookmarks. It first creates several bookmarks and then gets them again using the Item property.

Listing 8.40. A VSTO Customization That Works with Bookmarks

Public Class ThisDocument   Private Sub ThisDocument_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Dim r As Word.Range = Range()     r.Text = "The quick brown fox "     Me.Bookmarks.Add("FirstHalf", r)     r.Collapse(Word.WdCollapseDirection.wdCollapseEnd)     r.Text = "jumps over the lazy dog."     Me.Bookmarks.Add("SecondHalf", r)     If Me.Bookmarks.Exists("FirstHalf") = True Then       MsgBox("FirstHalf exists")     End If     Dim b As Word.Bookmark = Me.Bookmarks.Item("FirstHalf")     MsgBox(String.Format( _       "FirstHalf starts at {0} and ends at {1}.", _       b.Range.Start, b.Range.End))   End Sub End Class 

Bookmarks are easily deleted from the document. Setting the Text property of the Range associated with a bookmark, for example, replaces the Range and in the process deletes the bookmark associated with the Range. VSTO extends Bookmark and adds some functionality to preserve the bookmark even when you set the Text property. For more information on VSTO's support for bookmarks and the Bookmark control, see Chapter 13, "The VSTO Programming Model."