How to: Add Bookmark Controls to Word Documents

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 2007 Word 2003 Application-level projects Word 2007 For more information, see Features Available by Application and Project Type.

In document-level projects, you can add Bookmark controls to the document in your project 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.

This topic describes the following tasks:

• Adding Bookmark controls at design time

• Adding Bookmark controls at run time in a document-level project

• Adding Bookmark controls at run time in an application-level project

For more information about Bookmark controls, see Bookmark Control.

Adding Bookmark Controls at Design Time

There are several ways to add Bookmark controls to the document in a document-level project at design time:

• From the Visual Studio Toolbox.

  You can drag the Bookmark control from the Toolbox to your document. You might want to choose this way if you are already using the Toolbox to add Windows Forms controls to your document.

• From within Word.

  You can add the Bookmark control to your document in the same manner you would add the native bookmark. The advantage of adding it this way is that you can name your control at the time you create it.

• From the Data Sources window.

  You can drag the Bookmark control to your document from the Data Sources window. This is useful when you want to bind the control to data at the same time. You can add the host control in the same way you would add a Windows Form control from the Data Sources window. For more information, see Data Binding and Windows Forms.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

To add a Bookmark control to a document from the Toolbox

1. Open the Toolbox and click the Word Controls tab.

2. Drag a Bookmark control to the document.

   The Add Bookmark dialog box appears.

3. Select the text or other items you want to include in the bookmark.

4. Click OK.

   If you do not want to keep the default bookmark name, you can change the name in the Properties window.

To add a Bookmark control to a document in Word

1. In the document that is hosted in the Visual Studio designer, put the cursor where you want to add the bookmark, or select the text that you want the bookmark to enclose.

2. Perform one of the following operations:

   • For Word 2003: On the Insert menu, click Bookmark.

   • For Word 2007: On the Insert tab of the Ribbon, in the Links group, click the Bookmark button.

3. In the Bookmark dialog box, type the name of the new bookmark, and click Add.

Adding Bookmark Controls at Run Time in a Document-Level Project

You can add Bookmark controls programmatically to your document at run time by using methods of the Controls property of the ThisDocument class in your project. There are two method overloads that you can use to add a Bookmark control in the following ways:

• Add a Bookmark at a specified range.

• Add a Bookmark that is based on a native bookmark in the document (that is, a Bookmark).

Dynamically created Bookmark controls are not persisted in the document when the document is closed. However, a native Bookmark remains in the document. You can recreate a Bookmark that is based on a native bookmark the next time the document is opened. For more information, see Adding Controls to Office Documents at Run Time.

To add a Bookmark control to a document programmatically

• In the ThisDocument_Startup event handler in your project, insert the following code to add the Bookmark control to the first paragraph in the document.

  Dim firstParagraph As Microsoft.Office.Tools.Word.Bookmark
  firstParagraph = Me.Controls.AddBookmark(Me.Paragraphs(1).Range, "FirstParagraph")
  

  Microsoft.Office.Tools.Word.Bookmark firstParagraph;
  firstParagraph = this.Controls.AddBookmark(this.Paragraphs[1].Range,
      "FirstParagraph");
  

  Note

  If you want create a Microsoft.Office.Tools.Word.Bookmark control from an existing Bookmark, use the AddBookmark method and pass in the existing Bookmark.

Adding Bookmark Controls at Run Time in an Application-Level Project

Starting in SP1, you can add Bookmark controls programmatically to any open document at run time by using an application-level add-in. To do this, generate a Document host item that is based on an open document, and then use methods of the Controls property of this host item. There are two method overloads that you can use to add a Bookmark control in the following ways:

• Add a Bookmark at a specified range.

• Add a Bookmark that is based on a native bookmark in the document (that is, a Bookmark).

Dynamically created Bookmark controls are not persisted in the document when the document is closed. However, a native Bookmark remains in the document. You can recreate a Bookmark that is based on a native bookmark the next time the document is opened. For more information, see Persisting Dynamic Controls in Office Documents.

For more information about generating host items in application-level projects, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

To add a Bookmark control at a specified range

• Use the ControlCollection.AddBookmark(Range, String) method, and pass in the Range where you want to add the Bookmark.

  The following code example adds a new Bookmark to the beginning of the active document. To use this example, run the code from the ThisAddIn_Startup event handler in a Word add-in project.

  Dim extendedDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
  Dim firstParagraph As Bookmark = extendedDocument.Controls.AddBookmark( _
      extendedDocument.Paragraphs(1).Range, "FirstParagraph")
  

  Document extendedDocument = this.Application.ActiveDocument.GetVstoObject();
  Bookmark firstParagraph = extendedDocument.Controls.AddBookmark(
      extendedDocument.Paragraphs[1].Range, "FirstParagraph");
  

To add a Bookmark control that is based on a native Bookmark control

• Use the ControlCollection.AddBookmark(Bookmark, String) method, and pass in the existing Bookmark that you want to use as the basis for the new Bookmark.

  The following code example creates a new Bookmark that is based on the first Bookmark in the active document. To use this example, run the code from the ThisAddIn_Startup event handler in a Word add-in project.

  If Me.Application.ActiveDocument.Bookmarks.Count > 0 Then 
      Dim firstBookmark As Word.Bookmark = Me.Application.ActiveDocument.Bookmarks(1)
      Dim extendedDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
  
      Dim vstoBookmark As Bookmark = extendedDocument.Controls.AddBookmark( _
          firstBookmark, "VSTOBookmark")
  End If
  

  if (this.Application.ActiveDocument.Bookmarks.Count > 0)
  {
      object index = 1;
      Word.Bookmark firstBookmark = this.Application.ActiveDocument.Bookmarks.get_Item(ref index);
      Document extendedDocument = this.Application.ActiveDocument.GetVstoObject();
  
      Bookmark vstoBookmark = extendedDocument.Controls.AddBookmark(
              firstBookmark, "VSTOBookmark");
  }
  

See Also

Tasks

How to: Resize Bookmark Controls

Concepts

Host Items and Host Controls Overview

Adding Controls to Office Documents at Run Time

Programmatic Limitations of Host Items and Host Controls

Programming Application-Level Add-Ins

Programming Document-Level Customizations

Helper Methods for Host Controls

Other Resources

Word Host Controls

Change History

Date	History	Reason
July 2008	Added new procedures for application-level add-ins.	SP1 feature change.