Windows Forms Controls on Office Documents Overview
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
Application-level projects
For more information, see Features Available by Application and Project Type. |
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
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 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
Limitations of Windows Forms Controls on Office Documents
Reference
Other Resources
Change History
Date |
History |
Reason |
|---|---|---|
July 2008 |
Added information about adding Windows Forms controls to documents by using application-level add-ins. |
SP1 feature change. |