Windows Forms Controls on Office Documents Overview

Windows Forms controls are objects that users can interact with to enter or manipulate data. In document-level projects for Microsoft Office Excel and Microsoft Office Word, you can add Windows Forms controls to the document or workbook in your project at design time, or you can programmatically add these controls at run time. Starting in Visual Studio 2008 Service Pack 1 (SP1), you can programmatically add these controls to any open document or worksheet at run time in an application-level add-in for Excel 2007 or Word 2007.

For more information, see How to: Add Windows Forms Controls to Office Documents.

Using Windows Forms Controls

You can add Windows Forms controls to documents and to customizable user interface (UI) elements, including actions panes, custom task panes, and Windows Forms. Windows Forms controls generally have the same behavior on documents as on these other UI elements, but some differences do exist. For information, see Limitations of Windows Forms Controls on Office Documents.

The decision whether to add Windows Forms controls to a document or some other UI element depends on several factors. When designing the UI of your solution, consider the uses of Windows Forms controls as described in the following table.

• On a document.

  • When you want to display the controls 100% of the time.

  • When you want users to enter data directly in the document, for example, in forms-based documents where the editing surface is locked.

  • When you want the controls to display in line with the data in the document. For example, if you are adding buttons to each row of a list object, you would want them in line with each list item.

• On the actions pane or a custom task pane.

  • When you want to provide contextual information to the user.

  • When you want only the results to appear in the document, and not the query controls and data.

  • When you want to ensure that the controls are not printed with the document.

  • When you want to ensure that controls do not interfere with the view of the document.

• On a Windows Form.

  • When you want to control the size of the UI.

  • When you want to prevent users from hiding or deleting the controls.

  • When you want to get input from the user, and prevent the user from doing anything in the document until the input is received.

Adding Windows Forms Controls Programmatically

You can add Windows Forms controls to Word documents and Excel worksheets at run time. Visual Studio Tools for Office provides helper methods for adding the most common Windows Forms controls. These helper methods enable you to quickly add controls to your Office document and access the combined Windows Forms control functionality and Office-related functionality of these controls.

For more information, see Adding Controls to Office Documents at Run Time.

Using Windows Forms Controls in Document-Level Projects

Some aspects of using Windows Forms controls on documents are unique to document-level projects, which enable you to design the UI of your document by using the Visual Studio designer.

Creating Custom User Controls

You can add a user control to your project and then add it to the Toolbox. You can then drag the user control directly to your document in the same way you would add a Windows Forms control to your document. There are some things to keep in mind when you create user controls:

• Do not create a sealed user control. Visual Studio Tools for Office generates a wrapper class derived from the user control to extend it and support its use on the document; Visual Studio Tools for Office cannot derive from a sealed class.

• User controls must have the ComVisibleAttribute attribute set to true. User controls created inside a Visual Studio Tools for Office project have this attribute set to true by default, but user controls that are part of outside projects might not have this attribute set to true.

• After you have added a user control to the document, do not rename or delete the UserControl class from the project. If you need to change the name of a user control you must first delete it from the document, and then add it again after the name has been changed.

Arranging Controls at Design Time

If you add multiple controls to your Word and Excel documents at design time, you can quickly set the alignment of all of the selected controls by using the Microsoft Office Word and Microsoft Office Excel toolbars in Visual Studio. These toolbars are available only when a document or worksheet is open in the designer.

When you select multiple controls in the designer, you can use the following buttons on these toolbars to arrange the controls:

• Align Lefts

• Align Centers

• Align Rights

• Align Tops

• Align Middles

• Align Bottoms

• Make Horizontal Spacing Equal

• Make Vertical Spacing Equal

Preventing Old Data from Appearing in Excel Workbooks During Loading

When you add Windows Forms controls to documents or worksheets at design time, the controls remain in the document when the user closes the document. Controls added at design time are also called static controls.

When an Excel workbook that contains static controls is opened, the workbook displays a bitmap of the control in an ActiveX control until the customization code runs and loads the actual control. Excel creates this bitmap and stores it in the workbook whenever the workbook is saved. The bitmap shows the control as it appeared the last time the workbook was saved, including any data that the control was displaying. For more information about the ActiveX control that contains Windows Forms controls and bitmaps, see Limitations of Windows Forms Controls on Office Documents.

In certain conditions, the code does not load and only the bitmap is displayed, such as when the user opens the workbook in design mode. Also, if the user opens the workbook on a computer that does not have the Visual Studio Tools for Office runtime installed, the customization cannot run to load the controls and therefore only the bitmap of the control is visible. You should always remove personal information from controls on workbooks before saving the workbook and sending it to another user to ensure that your personal information is not accidentally disclosed.

Adding Components at Design Time

Certain controls or components are not visible on the document and are instead displayed in a component tray. Visual Studio Tools for Office provides a component tray for each document window. The component tray appears on the screen only if components exist on the document.

See Also

Tasks

How to: Add Windows Forms Controls to Office Documents

How to: Resize Controls Within Worksheet Cells

How to: Hide Controls on Worksheets when Printing

Walkthrough: Changing Worksheet Formatting Using CheckBox Controls

Walkthrough: Changing Document Formatting Using CheckBox Controls

Walkthrough: Displaying Text in a Text Box in a Document Using a Button

Walkthrough: Displaying Text in a Text Box in a Worksheet Using a Button

Concepts

Using Windows Forms Controls on Word Documents

Using Windows Forms Controls on Excel Worksheets

Adding Controls to Office Documents at Run Time

Host Items and Host Controls Overview

Actions Pane Overview

Limitations of Windows Forms Controls on Office Documents

Reference

ControlCollection.Remove

ControlCollection.Remove

Other Resources

Controls on Office Documents

Windows Forms Controls

Change History