Bookmark control
The Bookmark control is a bookmark that has a unique name, exposes events, and can be bound to data. The bookmark can be used as a placeholder to mark an item or location in a Microsoft Office Word document. The Bookmark control is a combination of a Bookmark object and a Range object.
Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for Word. For more information, see Features available by Office application and project type.
In document-level projects, you can add Bookmark controls to your document at design time or at run time. In VSTO Add-in projects, you can add Bookmark controls to any open document at run time. For more information, see How to: Add Bookmark controls to Word documents.
Bind data to the control
A Bookmark control supports simple data binding. The bookmark should be bound to a data source using the DataBindings property. The default data binding property of the bookmark is the Text property.
If the data in the bound dataset is updated, the Bookmark control shows the changes.
In document-level projects, you can also bind data to bookmarks by using the Data Sources window. For more information, see How to: Populate documents with data from objects.
Formatting
Formatting that can be applied to a Bookmark can be applied to a Bookmark control. This formatting includes fonts, indents, spacing, numbering, and styles.
Assign text to the bookmark
An additional difference between a Microsoft.Office.Interop.Word.Bookmark object and a Microsoft.Office.Tools.Word.Bookmark control is how it behaves when text is assigned to the bookmark. If you assign text to a zero-length Microsoft.Office.Interop.Word.Bookmark, the text is appended to the right of the bookmark and the bookmark remains zero-length. However, if you assign text to a zero-length Microsoft.Office.Tools.Word.Bookmark, the text is inserted into the bookmark and the bookmark's length expands to the total number of characters inserted.
The Microsoft.Office.Tools.Word.Bookmark control also has the Bookmark.Text property. This property is different from the Range.Text property that is available on the Bookmark.Range property of a Microsoft.Office.Tools.Word.Bookmark control, or the Bookmark.Range property of a Microsoft.Office.Interop.Word.Bookmark object.
| Text Property | Description |
|---|---|
| Bookmark.Text | Use this property to display text within the bookmark and leave the bookmark on the document. Assigning text to the bookmark expands the bookmark range and does not delete the bookmark. For example, Bookmark1.Text = "Hello world" inserts the text into the bookmark and leaves the bookmark intact. |
| Range.Text | Use this property to display text at the bookmark location and automatically delete the bookmark. For example, Bookmark1.Range.Text = "Hello world" inserts the text into the bookmark and deletes the bookmark. |
Rename the control at design time
In document-level projects, when you drag a Bookmark control from the Toolbox to your document, Visual Studio automatically generates a name for the control. You can change the name of the control in the Properties window.
Overlapping controls
Bookmark controls can overlap each other. The same text can be shared by more than one bookmark. When you assign new text to one of the overlapping bookmarks, it contains only the new text and the bookmarks no longer overlap. The other bookmark now contains only the text that wasn't shared between the original overlapping bookmarks.
The following table shows how the sentence "This is sample text." is shared by two overlapping bookmarks:
| Bookmark | Text |
|---|---|
| Overlapping bookmarks | [this is {sample] text.} |
| Bookmark1 | This is sample |
| Bookmark2 | sample text. |
If you assign the new text "This is replacement." to Bookmark1, the bookmarks don't overlap, and Bookmark2 retains only the text that wasn't originally part of Bookmark1.
| Bookmark | Text |
|---|---|
| Two separate bookmarks | [this is replacement]{ text.} |
| Bookmark1 | This is replacement |
| Bookmark2 | text. |
If you change the text of a bookmark that contains another bookmark, the inner bookmark isn't deleted. However, the inner bookmark becomes an empty bookmark, and moves to the end of the outer bookmark.
The following table shows how the sentence "This is sample text." is shared by a bookmark that's contained within another bookmark:
| Bookmark | Text |
|---|---|
| Overlapping bookmarks | [this is {sample} text.] |
| Bookmark1 | This is sample text. |
| Bookmark2 | sample |
If you assign the new text "This is replacement." to Bookmark1, the bookmarks are no longer overlapping and Bookmark2 becomes an empty bookmark that is located at the end of Bookmark1.
| Bookmark | Text |
|---|---|
| Two separate bookmarks | [this is replacement.]{} |
| Bookmark1 | This is replacement. |
| Bookmark2 | <empty> |
Events
The following events are available for the Bookmark control: