# Bookmark Control

Visual Studio 2008

Updated: July 2008

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Document-level projects

• Word 2003

• Word 2007

Application-level projects

• Word 2007

For more information, see Features Available by Application and Project Type.

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. When you add a bookmark to a document, Visual Studio Tools for Office creates a bookmark object that you can program against directly without having to traverse the Word object model.

In document-level projects, you can add Bookmark controls to your document at design time or at run time. Starting in Visual Studio 2008 Service Pack 1 (SP1), you can also add Bookmark controls to any open document at run time by using an application-level add-in for Word 2007. For more information, see How to: Add Bookmark Controls to Word Documents.

## Binding 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 reflects 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 includes fonts, indents, spacing, numbering, and styles.

## Assigning Text to the Bookmark

An additional difference between a Bookmark object and a Bookmark control is how it behaves when text is assigned to the bookmark. If you assign text to a zero-length 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 Bookmark, the text is inserted into the bookmark and the bookmark's length expands to the total number of characters inserted.

Additionally, Visual Studio Tools for Office adds a Bookmark.Text property to the Bookmark control. This is different from the RangeText property that is available on the Range of the bookmark.

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.

RangeText

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.

## Renaming the Control at Design Time

In document-level projects, when you drag a Bookmark control from the Toolbox to your document, Visual Studio Tools for Office 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; that is, the same text can be shared by more than one bookmark. When you assign new text to one of the overlapping bookmarks, it will contain only the new text and the bookmarks will no longer overlap. The other bookmark will now contain only the text that was not 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 are no longer overlapping and Bookmark2 retains only the text that was not originally part of Bookmark1.

Bookmark

Text

Two separate bookmarks

[this is replacement]{ text.}

Bookmark1

This is replacement

Bookmark2

text.

If one bookmark is fully contained within another bookmark and you change the text of the outer bookmark, the inner bookmark is not deleted. However, the inner bookmark becomes an empty bookmark that is moved to the end of the outer bookmark. The following table shows how the sentence "This is sample text." is shared by a bookmark that is 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:

## Change History

Date

History

Reason

July 2008

Added information about using bookmark controls in application-level projects.

SP1 feature change.