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 completely deletes the Range.

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

Figure 8-25. The Bookmark dialog.

VSTO provides some additional tools for creating bookmarks. For example, you can drag a bookmark control from the Visual Studio control toolbox to the Word document to create a bookmark. 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.

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

Figure 8-26. Result of checking the Bookmarks check box in the View page of Word's Options dialog.

To programmatically create and manage bookmarks, 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 bool value indicating whether the bookmark exists in the document. The get_Item method allows you to get to a bookmark given its name or 1-based index in the Bookmarks collection. The get_Item method 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 get_Item method.

Listing 8-40. A VSTO Customization That Works with Bookmarks

private void ThisDocument_Startup(object sender, EventArgs e)
{
 object collapseEnd = Word.WdCollapseDirection.wdCollapseEnd;
 Word.Range r = Range(ref missing, ref missing);
 r.Text = "The quick brown fox ";
 object range1 = r;
 this.Bookmarks.Add("FirstHalf", ref range1);

 r.Collapse(ref collapseEnd);
 r.Text = "jumped over the lazy dog.";
 object range2 = r;
 this.Bookmarks.Add("SecondHalf", ref range2);

 if (this.Bookmarks.Exists("FirstHalf") == true)
 {
 MessageBox.Show("FirstHalf exists");
 }

 object firstHalfName = "FirstHalf";
 Word.Bookmark b = this.Bookmarks.get_Item(ref firstHalfName);
 MessageBox.Show(String.Format(
 "FirstHalf starts at {0} and ends at {1}.",
 b.Range.Start, b.Range.End));
}

Bookmarks are easily deleted from the document. For example, setting the Text property of the Range associated with a bookmark replaces the Range and in the process deletes the bookmark associated with the Range. VSTO extends Bookmark and adds some additional 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.