How to: Add Windows Forms Controls to Office 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

  • Excel 2003

  • Excel 2007

  • Word 2003

  • Word 2007

Application-level projects

  • Excel 2007

  • Word 2007

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

You can add Windows Forms controls to Microsoft Office Excel and Microsoft Office Word documents at design time in document-level projects. At run time, you can add controls in document-level customizations and in application-level add-ins. For example, you can add a ComboBox control to your worksheet so that users can select from a list of options.

This topic describes the following tasks:

  • Adding controls at design time

  • Adding controls at run time in document-level projects

  • Adding controls at run time in application-level add-ins

You can also add host controls, such as Bookmark controls and NamedRange controls, to Office documents. For more information, see Word Host Controls and Excel Host Controls.

link to video For a related video demonstration, see How Do I: Add Controls to a Document Surface at Runtime?.

Adding Controls at Design Time

There are several ways to add Windows Forms controls to the document in a document-level project at design time.

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 drag a Windows Forms control to the document

  1. Create or open an Excel Workbook project or Word Document project in Visual Studio so that the document is visible in the designer. For information on creating projects, see How to: Create Visual Studio Tools for Office Projects.

  2. In the Common Controls tab of the Toolbox, click the control you want to add, and drag it to the document.

    Note

    When you select a control in Excel, you will see =EMBED("WinForms.Control.Host","") in the Formula Bar. This text is necessary and should not be deleted.

To draw a Windows Forms control on the document

  1. Create or open an Excel Workbook project or Word Document project in Visual Studio so that the document is visible in the designer. For information on creating projects, see How to: Create Visual Studio Tools for Office Projects.

  2. In the Common Controls tab of the Toolbox, click the control you want to add.

  3. On the document, click where you want the upper-left corner of the control to be located, and drag to where you want the lower-right corner of the control to be located.

    The control is added to the document with the specified location and size.

    Note

    When you select a control in Excel, you will see =EMBED("WinForms.Control.Host","") in the Formula Bar. This text is necessary and should not be deleted.

To add a Windows Forms control to the document by single-clicking the control

  1. Create or open an Excel Workbook project or Word Document project in Visual Studio so that the document is visible in the designer. For information on creating projects, see How to: Create Visual Studio Tools for Office Projects.

  2. In the Common Controls tab of the Toolbox, click the control you want to add

  3. One the document, click where you want the control to be added.

    The control is added to the document with the default size.

    Note

    When you select a control in Excel, you will see =EMBED("WinForms.Control.Host","") in the Formula Bar. This text is necessary and should not be deleted.

To add a Windows Forms control to the document by double-clicking the control

  1. Create or open an Excel Workbook project or Word Document project in Visual Studio so that the document is visible in the designer. For information on creating projects, see How to: Create Visual Studio Tools for Office Projects.

  2. In the Common Controls tab of the Toolbox, double-click the control you want to add.

    The control is added to the document at the center of the document or active pane.

    Note

    When you select a control in Excel, you will see =EMBED("WinForms.Control.Host","") in the Formula Bar. This text is necessary and should not be deleted.

To add a Windows Forms control to the document by pressing the ENTER key

  1. Create or open an Excel Workbook project or Word Document project in Visual Studio so that the document is visible in the designer. For information on creating projects, see How to: Create Visual Studio Tools for Office Projects.

  2. In the Common Controls tab of the Toolbox, click the control you want to add, and press the ENTER key.

    The control is added to the document at the center of the document or active pane.

    Note

    When you select a control in Excel, you will see =EMBED("WinForms.Control.Host","") in the Formula Bar. This text is necessary and should not be deleted.

Adding Controls at Run Time in Document-Level Projects

You can programmatically add Windows Forms controls to a document at run time. In Word, use methods of the Controls property of the ThisDocument class. In Excel, use methods of the Controls property of a Sheetn class. Each method has several overloads that enable you to specify the location of the control in different ways. For more information, see Helper Methods for Windows Forms Controls.

When you add a Windows Forms control to a document at run time, the control is not persisted in the document when the document is closed. You can recreate the control the next time the document is opened. For more information, see Adding Controls to Office Documents at Run Time.

To add a Windows Forms control at run time

  • Use a Microsoft.Office.Tools.Word.ControlCollection method (for Word projects) or Microsoft.Office.Tools.Excel.ControlCollection method (for Excel projects) that has the name Add<control class> (where control class is the class name of the Windows Forms control that you want to add, such as AddButton).

    The following code example demonstrates how to add a Button to cell C5 of Sheet1 in a document-level project for Excel.

    Private Sub Sheet1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
        Handles Me.Startup
    
        Dim salesButton As Microsoft.Office.Tools.Excel.Controls.Button
        salesButton = Me.Controls.AddButton(Me.Range("C5"), "salesButton")
        salesButton.Text = "Calculate Total Sales" 
    End Sub
    
    private void Sheet1_Startup(object sender, System.EventArgs e)
    {
        Microsoft.Office.Tools.Excel.Controls.Button salesButton;
        salesButton = this.Controls.AddButton(this.get_Range("C5", missing), "salesButton");
        salesButton.Text = "Calculate Total Sales";
    }
    

Adding Controls at Run Time in Application-Level Add-Ins

You can add Windows Forms controls programmatically to any open document at run time. First, generate a host item that is based on an open document or worksheet. Then, in Word, use methods of the Document.Controls property of the new host item. In Excel, use methods of the Worksheet.Controls property of the new host item. Each method has several overloads that enable you to specify the location of the control in different ways. For more information, see Helper Methods for Windows Forms Controls.

When you add a Windows Forms control to a document at run time, the control is not persisted in the document when the document is closed. You can recreate the control the next time the document is opened. For more information, see Adding Controls to Office Documents at Run Time.

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 Windows Forms control at run time

  • Use a Microsoft.Office.Tools.Word.ControlCollection method (for Word projects) or Microsoft.Office.Tools.Excel.ControlCollection method (for Excel projects) that has the name Add<control class> (where control class is the class name of the Windows Forms control that you want to add, such as AddButton).

    The following code example demonstrates how to add a Button to the first paragraph of the active document by using a Word add-in.

    Dim salesButton As Microsoft.Office.Tools.Word.Controls.Button
    Dim extendedDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
    
    extendedDocument.Paragraphs(1).Range.InsertParagraphBefore()
    salesButton = extendedDocument.Controls.AddButton( _
        extendedDocument.Paragraphs(1).Range, 75, 18, "salesButton")
    salesButton.Text = "Calculate Sales"
    
    Microsoft.Office.Tools.Word.Controls.Button salesButton;
    Document extendedDocument = this.Application.ActiveDocument.GetVstoObject();
    
    extendedDocument.Paragraphs[1].Range.InsertParagraphBefore();
    salesButton = extendedDocument.Controls.AddButton(
        extendedDocument.Paragraphs[1].Range, 75, 18, "salesButton");
    salesButton.Text = "Calculate Sales";
    

See Also

Tasks

How to: Resize Controls Within Worksheet Cells

Concepts

Windows Forms Controls on Office Documents Overview

Adding Controls to Office Documents at Run Time

Host Items and Host Controls Overview

The Variable missing and Optional Parameters in Office Solutions

Change History

Date

History

Reason

July 2008

Added procedure for adding controls to documents in an application-level add-in.

SP1 feature change.