Limitations of Windows Forms Controls on 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.

There are some differences between Windows Forms controls that are added to Microsoft Office Word documents or Microsoft Office Excel worksheets, and Windows Forms controls that are added to Windows Forms. For example, when you add a Button control to a document, properties such as Dock, Anchor, and TabIndex do not behave as you might expect.

Many of these differences are caused by the way that Windows Forms controls are hosted on documents. When a Windows Forms control is added to a document, Visual Studio Tools for Office embeds an ActiveX control that then hosts the Windows Forms control in the document. The Windows Forms control is not embedded directly in the document.

Limitations of Methods and Properties of Windows Forms Controls

There are a number of methods and properties of Windows Forms controls that do not work the same way on a document as they would on a Windows Form and, therefore, it is recommended that they not be used. For example, setting properties such as Dock and Anchor only affects the position of the control with respect to the container ActiveX control, rather than the document. The following is a list of unsupported methods and properties of Windows Forms controls for Word and Excel:

• Unsupported methods and properties of Excel controls:

  • Anchor

  • Dock

  • Location

  • TabIndex

  • TabStop

  • TopLevelControl

• Unsupported methods and properties of Word controls:

  • Hide

  • Show

  • Anchor

  • Dock

  • Location

  • TabIndex

  • TabStop

  • TopLevelControl

  • Visible

You also cannot set the Left or Top property of Windows Forms controls that are in line with text on a Word document. Windows Forms controls are added in line with text in the following cases:

• You programmatically add a control to a Word document and use a method that specifies a range for the location. For more information, see Helper Methods for Windows Forms Controls.

• You add a Windows Forms control to a Word document at design time. You can change this by modifying the control in the designer. For more information, see Using Windows Forms Controls on Word Documents.

Differences in Windows Forms Controls on Office Documents

Windows Forms controls generally have the same behavior on an Office document as they do on a Windows Form, but some differences do exist. The following table describes the differences that exist for Windows Forms controls on Office documents.

Functionality	Difference
Control tab order	You cannot tab through controls placed on an Excel worksheet or Word document.
Control grouping	You cannot use a GroupBox control to contain other controls on an Office document. When you add multiple radio buttons directly to the document, the radio buttons are not mutually exclusive. You can write code to make the radio buttons mutually exclusive; however, the preferred approach is to add the radio buttons to a user control and then add the user control to the document. For more information, see Word Controls Sample or Excel Controls Sample.
Control type	Windows Forms controls used on documents are wrapped in a class provided by Visual Studio Tools for Office that gives the controls additional functionality specific to the Excel worksheet or Word document. For example, if you have a Button control on an Excel worksheet, be sure to specify the type as Microsoft.Office.Tools.Excel.Controls.Button rather than System.Windows.Forms.Button when referencing or casting the object.
Control position and size	The size and position of the control is determined by properties that are part of the container ActiveX control. The ActiveX control properties take different values than the equivalent properties of a Windows Forms control. When you set the Top, Left, Height, or Width properties of a control, it is measured in points, rather than pixels.
Control position on Word documents	If you add controls to a flow-based layout, keep in mind that the controls will flow with the content as the content changes. You cannot anchor the control to a paragraph when you drag it from the Toolbox because the control is added to the Word document in line with text. If you use another method to add the control, such as double-clicking the control, the control is inserted according to the Word option you have set for inserting pictures. You cannot set the Left or Top property of a control that is inline with text. You cannot place controls in a header or footer, or within a subdocument.
Control events	When the control is selected, it raises events in the following order: Enter GotFocus When the control is deselected, it raises events in the following order: Leave Validating Validated LostFocus
Control scaling	When you change the zoom setting of a document to anything other than 100%, controls are disabled, although they appear to scale with the document. For example, if you click a button when your document is at 130% zoom, it will show a message that the control has been disabled until zoom is set to 100%. The controls will function correctly when you change the zoom to 100%.
Control property values	Although the properties of controls on a Windows Form are set to an integer value, they are set to a single for controls on a Word document. In Excel, the property values of controls are set to a double. If the Height and Width property of a control on a worksheet exceeds the size of the worksheet or screen, the value is truncated.
Control resizing	If you resize a control on the document using one of the eight sizing handles, the new control dimensions are not reflected in the Properties window until the control is reselected.
Control behavior	Controls on an Excel worksheet might behave unpredictably when the worksheet window is split. For example, access to a TextBox on the worksheet might only be available in one of the windows.
Control naming	You cannot use reserved words to name controls. For example, if you add a Button to a worksheet and change the name to System, errors occur when you build the project.
Programmatically adding controls	Do not use the control's constructor to add a control to your document at run time. Instead, use the helper methods provided by Visual Studio Tools for Office. For example, use the AddButton method to add a button to a worksheet. If you want to add a control that is not supported by these helper methods, you can use the AddControl method. For more information, see Adding Controls to Office Documents at Run Time.
Copying controls	If you copy a Windows Forms control and paste it into a document at run time, an empty container ActiveX control is pasted into the document. The Windows Forms control does not appear in the new location, and code behind the original control is not copied to the container ActiveX control.

Limitations in Document-Level Projects

Some limitations of using Windows Forms controls on documents are unique to document-level projects.

Control Support at Design Time

Certain Windows Forms controls are removed from the Toolbox when an Excel worksheet or Word document is open in the Visual Studio designer. This is because of technical limitations or because the functionality is already available within Word or Excel. Visual Studio Tools for Office supports all of the Windows Forms controls and other components that appear in the Toolbox when the document has focus, and also enables third-party controls to be added to your document.

Note

All controls are removed from the Toolbox when a document is protected. For information about document protection, see Document Protection in Document-Level Solutions.

Note

Third-party controls must have the ComVisibleAttribute attribute set to true in order to be used in a Visual Studio Tools for Office solution.

The following controls and components are not available in the Toolbox:

• BindingNavigator

• ContextMenuStrip

• CrystalReportViewer

• DataGrid

• DirectoryEntry

• DirectorySearcher

• ErrorProvider

• EventLog

• FileSystemWatcher

• FlowLayoutPanel

• GroupBox

• MainMenu

• MenuStrip

• MessageQueue

• NotifyIcon

• PageSetupDialog

• Panel

• PerformanceCounter

• PrintDialog

• PrintDocument

• PrintPreviewControl

• Process

• RichTextBox

• SerialPort

• ServiceController

• SplitContainer

• Splitter

• StatusBar

• StatusStrip

• TabControl

• TableLayoutPanel

• System.Timers.Timer

• System.Windows.Forms.Timer

• ToolBar

• ToolStrip

• ToolStripContainer

• ToolStripDropDown

• ToolStripDropDownMenu

• ToolStripPanel

Support for Legacy ActiveX Controls

If you create a Visual Studio Tools for Office project using an existing Word document or Excel workbook that contains ActiveX controls, the functionality of the ActiveX controls is not lost; however, there is no support for adding new ActiveX controls to your documents from within Visual Studio Tools for Office. For example, if your Word document has a button from the Control toolbox that runs a Visual Basic for Applications (VBA) macro, it will continue to run the macro after the document has been used in a Visual Studio Tools for Office project. However, it is recommended that you remove ActiveX controls and VBA macros and replace them with Windows Forms controls and managed code.

See Also

Tasks

How to: Add Windows Forms Controls to Office Documents

Concepts

Windows Forms Controls on Office Documents Overview

Adding Controls to Office Documents at Run Time

Other Resources

Controls on Office Documents

Change History

Date	History	Reason
July 2008	Added information to differentiate between general limitations, and limitations specific to document-level customizations.	SP1 feature change.