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. You can programmatically add these controls to any open document or worksheet at run time in an application-level add-in for Excel or Word.
For more information, see How to: Add Windows Forms Controls to Office Documents.
Applies to: The information in this topic applies to document-level projects and application-level projects for the following applications: Excel 2007 and Excel 2010; Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.
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.
You can add Windows Forms controls to Word documents and Excel worksheets at run time. The Visual Studio Tools for Office runtime 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.
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. When you drag the control to your document, Visual Studio generates a wrapper class derived from the user control to extend it and support its use on the document. If the user control is sealed, Visual Studio cannot generate the wrapper class.
-
User controls must have the ComVisibleAttribute attribute set to true. User controls created inside an 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
Note
|
|---|
|
In Word projects, these buttons are enabled only if the selected controls are not in line with text. By default, controls that you add to the document at design time are in line with text. For more information, see Using Windows Forms Controls on Word Documents. |
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 provides a component tray for each document window. The component tray appears on the screen only if components exist on the document.
