How to: Protect Parts of Documents by Using Content Controls

Applies to
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type Document-level projects Application-level projects Microsoft Office version Word 2007 For more information, see Features Available by Application and Project Type.

When you protect part of a document, you prevent users from changing or deleting the content in that part of the document. There are several ways you can protect parts of a Microsoft Office Word 2007 document by using content controls:

• You can protect a content control.

• You can protect a part of a document that is not in a content control.

Protecting a Content Control

You can prevent users from editing or deleting a content control by setting properties of the control in a document-level project at design time or at run time.

Starting in Visual Studio 2008 Service Pack 1 (SP1), you can also protect content controls that you add to a document at run time by using an application-level project. For more information, see How to: Add Content Controls to Word Documents.

To protect a content control at design time

1. In the document that is hosted in the Visual Studio designer, select the content control that you want to protect.

2. In the Properties window, set one or both of the following properties:

   • To prevent users from editing the control, set LockContents to True.

   • To prevent users from deleting the control, set LockContentControl to True.

3. Click OK.

To protect a content control at run time in a document-level project

• Set the LockContents property of the content control to true to prevent users from editing the control, and set the LockContentControl property to true to prevent users from deleting the control.

  The following code example demonstrates using the LockContents and LockContentControl properties of two different RichTextContentControl objects in a document-level project. To run this code, add the code to the ThisDocument class in your project, and call the AddProtectedContentControls method from the ThisDocument_Startup event handler.

  Dim deletableControl As Microsoft.Office.Tools.Word.RichTextContentControl
  Dim editableControl As Microsoft.Office.Tools.Word.RichTextContentControl
  
  Private Sub AddProtectedContentControls()
      Me.Paragraphs(1).Range.InsertParagraphBefore()
      Dim range1 As Word.Range = Me.Paragraphs(1).Range
  
      deletableControl = Me.Controls.AddRichTextContentControl(range1, _
          "deletableControl")
      deletableControl.PlaceholderText = "You can delete this control, " & _
          "but you cannot edit it"
      deletableControl.LockContents = True
  
      range1.InsertParagraphAfter()
      Dim range2 As Word.Range = Me.Paragraphs(2).Range
  
      editableControl = Me.Controls.AddRichTextContentControl(range2, _
          "editableControl")
      editableControl.PlaceholderText = "You can edit this control, " & _
          "but you cannot delete it"
      editableControl.LockContentControl = True 
  End Sub
  

  private Microsoft.Office.Tools.Word.RichTextContentControl deletableControl;
  private Microsoft.Office.Tools.Word.RichTextContentControl editableControl;
  
  private void AddProtectedContentControls()
  {
      this.Paragraphs[1].Range.InsertParagraphBefore();
      Word.Range range1 = this.Paragraphs[1].Range;
  
      deletableControl = this.Controls.AddRichTextContentControl(range1,
          "deletableControl");
      deletableControl.PlaceholderText = "You can delete this control, " +
          "but you cannot edit it";
      deletableControl.LockContents = true;
  
      range1.InsertParagraphAfter();
      Word.Range range2 = this.Paragraphs[2].Range;
  
      editableControl = this.Controls.AddRichTextContentControl(range2,
          "editableControl");
      editableControl.PlaceholderText = "You can edit this control, " +
          "but you cannot delete it";
      editableControl.LockContentControl = true;
  }
  

To protect a content control at run time in an application-level project

• Set the LockContents property of the content control to true to prevent users from editing the control, and set the LockContentControl property to true to prevent users from deleting the control.

  The following code example demonstrates using the LockContents and LockContentControl properties of two different RichTextContentControl objects in an application-level project. To run this code, add the code to the ThisAddIn class in your project, and call the AddProtectedContentControls method from the ThisAddIn_Startup event handler.

  Dim deletableControl As Microsoft.Office.Tools.Word.RichTextContentControl
  Dim editableControl As Microsoft.Office.Tools.Word.RichTextContentControl
  
  Private Sub AddProtectedContentControls()
      Dim vstoDocument As Microsoft.Office.Tools.Word.Document = _
          Me.Application.ActiveDocument.GetVstoObject()
      vstoDocument.Paragraphs(1).Range.InsertParagraphBefore()
      Dim range1 As Word.Range = vstoDocument.Paragraphs(1).Range
  
      deletableControl = vstoDocument.Controls.AddRichTextContentControl(range1, _
          "deletableControl")
      deletableControl.PlaceholderText = "You can delete this control, " & _
          "but you cannot edit it"
      deletableControl.LockContents = True
  
      range1.InsertParagraphAfter()
      Dim range2 As Word.Range = vstoDocument.Paragraphs(2).Range
  
      editableControl = vstoDocument.Controls.AddRichTextContentControl(range2, _
          "editableControl")
      editableControl.PlaceholderText = "You can edit this control, " & _
          "but you cannot delete it"
      editableControl.LockContentControl = True 
  End Sub
  

  private Microsoft.Office.Tools.Word.RichTextContentControl deletableControl;
  private Microsoft.Office.Tools.Word.RichTextContentControl editableControl;
  
  private void AddProtectedContentControls()
  {
      Microsoft.Office.Tools.Word.Document vstoDocument = 
          this.Application.ActiveDocument.GetVstoObject();
      vstoDocument.Paragraphs[1].Range.InsertParagraphBefore();
      Word.Range range1 = vstoDocument.Paragraphs[1].Range;
  
      deletableControl = vstoDocument.Controls.AddRichTextContentControl(range1,
          "deletableControl");
      deletableControl.PlaceholderText = "You can delete this control, " +
          "but you cannot edit it";
      deletableControl.LockContents = true;
  
      range1.InsertParagraphAfter();
      Word.Range range2 = vstoDocument.Paragraphs[2].Range;
  
      editableControl = vstoDocument.Controls.AddRichTextContentControl(range2,
          "editableControl");
      editableControl.PlaceholderText = "You can edit this control, " +
          "but you cannot delete it.";
      editableControl.LockContentControl = true;
  }
  

Protecting a Part of a Document That Is Not in a Content Control

You can prevent users from changing an area of a document by putting the area in a GroupContentControl. This is useful in the following scenarios:

• You want to protect an area that does not contain content controls.

• You want to protect an area that already contains content controls, but the text or other items that you want to protect are not in the content controls.

Note

If you create a GroupContentControl that contains embedded content controls, the embedded content controls are not automatically protected. To prevent users from editing an embedded content control, use the LockContents property of the control.

To protect an area of a document at design time

1. In the document that is hosted in the Visual Studio designer, select the area that you want to protect.

2. On the Ribbon, click the Developer tab.

   Note

   If the Developer tab is not visible, you must first show it. For more information, see How to: Show the Developer Tab on the Ribbon.

3. In the Controls group, click the Group drop-down button, and then click Group.

   A GroupContentControl that contains the protected region is automatically generated in the ThisDocument class in your project. A border that represents the group control is visible at design time, but there is no visible border at run time.

To protect an area of a document at run time in a document-level project

• Programmatically select the area that you want to protect, and then call the AddGroupContentControl method to create a GroupContentControl.

  The following code example adds text to the first paragraph in the document, selects the first paragraph, and then instantiates a GroupContentControl. To run this code, add the code to the ThisDocument class in your project, and call the ProtectFirstParagraph method from the ThisDocument_Startup event handler.

  Dim groupControl1 As Microsoft.Office.Tools.Word.GroupContentControl
  
  Private Sub ProtectFirstParagraph()
      Me.Paragraphs(1).Range.InsertParagraphBefore()
      Dim range1 As Word.Range = Me.Paragraphs(1).Range
      range1.Text = "You cannot edit or change the formatting of text " & _
              "in this paragraph, because this paragraph is in a GroupContentControl."
      range1.Select()
  
      groupControl1 = Me.Controls.AddGroupContentControl("groupControl1")
  End Sub
  

  private Microsoft.Office.Tools.Word.GroupContentControl groupControl1;
  
  private void ProtectFirstParagraph()
  {
      this.Paragraphs[1].Range.InsertParagraphBefore();
      Word.Range range1 = this.Paragraphs[1].Range;
  
      range1.Text = "You cannot edit or change the formatting of text " +
          "in this sentence, because this sentence is in a GroupContentControl.";
      range1.Select();
      groupControl1 = this.Controls.AddGroupContentControl("groupControl1");
  }
  

To protect an area of a document at run time in an application-level project

• Programmatically select the area that you want to protect, and then call the AddGroupContentControl method to create a GroupContentControl.

  The following code example adds text to the first paragraph in the active document, selects the first paragraph, and then instantiates a GroupContentControl. To run this code, add the code to the ThisAddIn class in your project, and call the ProtectFirstParagraph method from the ThisAddIn_Startup event handler.

  Dim groupControl1 As Microsoft.Office.Tools.Word.GroupContentControl
  
  Private Sub ProtectFirstParagraph()
      Dim vstoDocument As Microsoft.Office.Tools.Word.Document = _
          Me.Application.ActiveDocument.GetVstoObject()
      vstoDocument.Paragraphs(1).Range.InsertParagraphBefore()
  
      Dim range1 As Word.Range = vstoDocument.Paragraphs(1).Range
      range1.Text = "You cannot edit or change the formatting of text " & _
              "in this paragraph, because this paragraph is in a GroupContentControl."
      range1.Select()
  
      groupControl1 = vstoDocument.Controls.AddGroupContentControl("groupControl1")
  End Sub
  

  private Microsoft.Office.Tools.Word.GroupContentControl groupControl1;
  
  private void ProtectFirstParagraph()
  {
      Microsoft.Office.Tools.Word.Document vstoDocument =
          this.Application.ActiveDocument.GetVstoObject();
      vstoDocument.Paragraphs[1].Range.InsertParagraphBefore();
  
      Word.Range range1 = vstoDocument.Paragraphs[1].Range;
      range1.Text = "You cannot edit or change the formatting of text " +
          "in this sentence, because this sentence is in a GroupContentControl.";
      range1.Select();
  
      groupControl1 = vstoDocument.Controls.AddGroupContentControl("groupControl1");
  }
  

See Also

Tasks

How to: Add Content Controls to Word Documents

Concepts

Content Controls

Host Items and Host Controls Overview

Programmatic Limitations of Host Items and Host Controls

Adding Controls to Office Documents at Run Time

Helper Methods for Host Controls

Other Resources

Word Host Controls

Change History

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