Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Limitations of Windows Forms Controls on Office Documents

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005

    -or-

    Visual Studio Team System

  • Microsoft Office 2003

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

When a Windows Forms control is added to a Microsoft Office Word or Microsoft Office Excel document, Microsoft Visual Studio 2005 Tools for the Microsoft Office System 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.

NoteNote

Adding controls to Word subdocuments is not supported.

Control Support

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 that appear in the Toolbox when the document has focus, and also enables third-party controls to be added to your document.

NoteNote

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

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

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.

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 would only affect the position of the Windows Forms 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 Word controls:

    • Hide

    • Show

    • Anchor

    • Dock

    • Location

    • TabIndex

    • TabStop

    • TopLevelControl

    • Visible

  • Unsupported methods and properties of Excel controls:

    • Anchor

    • Dock

    • Location

    • TabIndex

    • TabStop

    • TopLevelControl

When you add a Windows Forms control to a Word document at design time, the control is added in line with text. At run time, if you programmatically add a control and specify a range for the location, the control is added in line with text. You cannot set the Left or Top property of controls that are in line with text. For more information, see Adding Controls to Office Documents at Run Time.

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 or an actions pane, but some differences do exist. The following describes the differences that exist for Windows Forms controls on Office Documents:

Functionality Definition

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.

You cannot set the Left or Top property of a Word control that is inline with text.

Control events

When the control is selected, it raises events in the following order:

  1. Enter

  2. GotFocus

When the control is deselected, it raises events in the following order:

  1. Leave

  2. Validating

  3. Validated

  4. LostFocus

Control scaling

When you change the zoom setting of a document to anything other than 100%, controls are disabled even though 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 placement

If you add controls to a flow-based layout, such as a Word document, 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 inline 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 Word control that is inline with text.

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

You cannot use the New 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.

See Also

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft