How to: Add Bookmark Controls to Word Documents

In document-level projects, you can add Bookmark controls to the document in your project at design time or at run time. In application-level projects, you can add Bookmark controls to any open document at run time.

Applies to: The information in this topic applies to document-level projects and application-level projects for Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.

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. 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 Microsoft.Office.Interop.Word.Bookmark).

Dynamically created Bookmark controls are not persisted in the document when the document is closed. However, a native Microsoft.Office.Interop.Word.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 Microsoft.Office.Interop.Word.Bookmark, use the AddBookmark method and pass in the existing Microsoft.Office.Interop.Word.Bookmark.

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

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 Microsoft.Office.Interop.Word.Bookmark).

Dynamically created Bookmark controls are not persisted in the document when the document is closed. However, a native Microsoft.Office.Interop.Word.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.

  ' Use the following line of code in projects that target the .NET Framework 4.
  Dim extendedDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
  
  ' In projects that target the .NET Framework 3.5, use the following line of code.
  ' Dim extendedDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
  
  Dim firstParagraph As Bookmark = extendedDocument.Controls.AddBookmark( _
      extendedDocument.Paragraphs(1).Range, "FirstParagraph")
  

  // Use the following line of code in projects that target the .NET Framework 4.
  Document extendedDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
  
  // In projects that target the .NET Framework 3.5, use the following line of code.
  // 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 Microsoft.Office.Interop.Word.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 Microsoft.Office.Interop.Word.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)
  
      ' Use the following line of code in projects that target the .NET Framework 4.
      Dim extendedDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
  
      ' In projects that target the .NET Framework 3.5, use the following line of code.
      ' 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);
  
      // Use the following line of code in projects that target the .NET Framework 4.
      Document extendedDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
  
      // In projects that target the .NET Framework 3.5, use the following line of code.
      // Document extendedDocument = this.Application.ActiveDocument.GetVstoObject();
  
      Bookmark vstoBookmark = extendedDocument.Controls.AddBookmark(
              firstBookmark, "VSTOBookmark");
  }
  

See Also

Tasks

How to: Resize Bookmark Controls

Concepts

Automating Word by Using Extended Objects

Host Items and Host Controls Overview

Adding Controls to Office Documents at Run Time

Programmatic Limitations of Host Items and Host Controls

Helper Methods for Host Controls

Other Resources

Programming Application-Level Add-Ins

Programming Document-Level Customizations