Walkthrough: Adding Controls to a Document at Run Time in a VSTO Add-In
You can add controls to any open Microsoft Office Word document by using an VSTO Add-in. This walkthrough demonstrates how to use the Ribbon to enable users to add a Button or a RichTextContentControl to a document.
Applies to: The information in this topic applies to VSTO Add-in projects for Word 2010. For more information, see Features Available by Office Application and Project Type.
This walkthrough illustrates the following tasks:
Creating a new Word VSTO Add-in project.
Providing a user interface (UI) to add controls to the document.
Adding controls to the document at run time.
Removing controls from the document.
You need the following components to complete this walkthrough:
An edition of Visual Studio that includes the Microsoft Office developer tools. For more information, see Configuring a Computer to Develop Office Solutions.
Word 2013 or Word 2010.
Start by creating a Word VSTO Add-in project.
Create an VSTO Add-in project for Word with the name WordDynamicControls. For more information, see How to: Create Office Projects in Visual Studio.
Add a reference to the Microsoft.Office.Tools.Word.v4.0.Utilities.dll assembly. This reference is required to programmatically add a Windows Forms control to the document later in this walkthrough.
Add a custom tab to the Ribbon in Word. Users can select check boxes on the tab to add controls to a document.
On the Project menu, click Add New Item.
In the Add New Item dialog box, select Ribbon (Visual Designer).
Change the name of the new Ribbon to MyRibbon, and click Add.
The MyRibbon.cs or MyRibbon.vb file opens in the Ribbon Designer and displays a default tab and group.
In the Ribbon Designer, click the group1 group.
In the Properties window, change the Label property for group1 to Add Controls.
From the Office Ribbon Controls tab of the Toolbox, drag a CheckBox control onto group1.
Click CheckBox1 to select it.
In the Properties window, change the following properties.
Property Value Name addButtonCheckBox Label Add Button
Add a second check box to group1, and then change the following properties.
Property Value Name addRichTextCheckBox Label Add Rich Text Control
In the Ribbon Designer, double-click Add Button.
The Click event handler of the Add Button check box opens in the Code Editor.
Return to the Ribbon Designer, and double-click Add Rich Text Control.
The Click event handler of the Add Rich Text Control check box opens in the Code Editor.
Later in this walkthrough, you will add code to these event handlers to add and remove controls on the active document.
In the VSTO Add-in code, you must convert the active document into a Microsoft.Office.Tools.Word.Documenthost item before you can add a control. In Office solutions, managed controls can be added only to host items, which act as containers for the controls. In VSTO Add-in projects, host items can be created at run time by using the GetVstoObject method.
Add methods to the
ThisAddIn class that can be called to add or remove a Button or RichTextContentControl on the active document. Later in this walkthrough, you will call these methods from the Click event handlers of the check boxes on the Ribbon.
In Solution Explorer, double-click ThisAddIn.cs or ThisAddIn.vb to open the file in the Code Editor.
Add the following method to the
ThisAddInclass. When the user clicks the Add Button check box on the Ribbon, this method adds a Button to the current selection on the document if the check box is selected, or removes the Button if the check box is cleared.
Friend Sub ToggleButtonOnDocument() Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument) Dim name As String = "MyButton" If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then Dim selection = Me.Application.Selection If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then button = vstoDocument.Controls.AddButton( _ selection.Range, 100, 30, name) End If Else vstoDocument.Controls.Remove(name) End If End Sub
Add the following method to the
ThisAddInclass. When the user clicks the Add Rich Text Control check box on the Ribbon, this method adds a RichTextContentControl to the current selection on the document if the check box is selected, or removes the RichTextContentControl if the check box is cleared.
Friend Sub ToggleRichTextControlOnDocument() Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument) Dim name As String = "MyRichTextBoxControl" If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then Dim selection = Me.Application.Selection If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then richTextControl = vstoDocument.Controls.AddRichTextContentControl( _ selection.Range, name) End If Else vstoDocument.Controls.Remove(name) End If End Sub
Windows Forms controls are not persisted when the document is saved and then closed. However, an ActiveX wrapper for each control remains in the document, and the border of this wrapper can be seen by end users when the document is reopened. There are several ways to clean up dynamically created Windows Forms controls in VSTO Add-ins. In this walkthrough, you programmatically remove the Button control when the document is saved.
In the ThisAddIn.cs or ThisAddIn.vb code file, add the following method to the
ThisAddInclass. This method is an event handler for the E:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentBeforeSave event. If the saved document has a Document host item that is associated with it, the event handler gets the host item and removes the Button control, if it exists.
Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _ ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc) If isExtended Then Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc) If vstoDocument.Controls.Contains(button) Then vstoDocument.Controls.Remove(button) Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False End If End If End Sub
In C#, add the following code to the
ThisAddIn_Startupevent handler. This code is required in C# to connect the
Application_DocumentBeforeSaveevent handler with the E:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentBeforeSave event.
Finally, modify the Click event handlers of the check boxes you added to the Ribbon to add or remove controls on the document.
In the MyRibbon.cs or MyRibbon.vb code file, replace the generated
addRichTextCheckBox_Clickevent handlers with the following code. This code redefines these event handlers to call the
ToggleRichTextControlOnDocumentmethods that you added to the
ThisAddInclass earlier in this walkthrough.
Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _ ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click Globals.ThisAddIn.ToggleButtonOnDocument() End Sub Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _ ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click Globals.ThisAddIn.ToggleRichTextControlOnDocument() End Sub
Add controls to a document by selecting them from the custom tab on the Ribbon. When you save the document, the Button control is removed.
Press F5 to run your project.
In the active document, press ENTER several times to add new empty paragraphs to the document.
Select the first paragraph.
Click the Add-Ins tab.
In the Add Controls group, click Add Button.
A button appears in the first paragraph.
Select the last paragraph.
In the Add Controls group, click Add Rich Text Control.
A rich text content control is added to the last paragraph.
Save the document.
The button is removed from the document.
You can learn more about controls in VSTO Add-ins from these topics:
For a sample that demonstrates how to add many other types of controls to a document at run time and recreate the controls when the document is reopened, see the Word Add-In Dynamic Controls Sample at Office Development Samples and Walkthroughs.
For a walkthrough that demonstrates how to add controls to a worksheet by using an VSTO Add-in for Excel, see Walkthrough: Adding Controls to a Worksheet at Run Time in VSTO add-in Project.
Adding Controls to Office Documents at Run Time
Persisting Dynamic Controls in Office Documents
How to: Add Windows Forms Controls to Office Documents
How to: Add Content Controls to Word Documents
Extending Word Documents and Excel Workbooks in VSTO Add-ins at Run Time