Share via

Using ActiveX Controls [Office 2003 SDK Documentation]

  • Article

You can insert into your smart documents ActiveX controls that are either developed by Microsoft or that you have created yourself. This allows you a great deal of flexibility with your smart documents. If one of the built-in controls doesn't meet your needs, you can always use an ActiveX control.

Important  The ISmartDocument interface was designed to use Component Object Model (COM)-based ActiveX controls. ActiveX controls written in .NET Framework-compatible languages are not explicitly supported. Although it is not impossible to connect a managed ActiveX control to a smart document, best practice is to use COM-based ActiveX controls.

Using the API

For ActiveX controls, the ControlCaptionFromID property specifies the GUID for the ActiveX control. This is how the ISmartDocument interface determines which control to display. To locate the GUID for the ActiveX control, you need to search the registry. For more information about how to do this, see the following list of tutorials.

The PopulateActiveXProps method specifies the appearance of the ActiveX controls whenever the host application draws the Document Actions task pane. You would use the Props parameter to define the built-in display properties for ActiveX controls. To define properties that are native to the ActiveX control, you would use the ActiveXPropBag parameter. These two parameters provide access to the ISmartDocProperties interface, and you use them in basically the same way whether you are setting built-in display properties for the ActiveX control or setting native properties.

Setting built-in display properties

The following Microsoft® Visual Basic® code shows how you would use the Props parameter to specify a built-in property.

Props.Write Key:="W", value:="250"
Props.Write Key:="H", value:="200"

This example uses the Write method of the ISmartDocProperties interface to set the built-in "H" (height) and "W" (width) display properties for the control. The Key parameter of the Write property specifies the name of the property, in this case, "H" and "W." The Value parameter specifies the value of the property. In this case, the height of the control is set to 250 pixels, and the width of the control is set to 200 pixels.

Note  By default, the width (W) and height (H) for an ActiveX control are zero, so you should be sure to set these properties in order to make the ActiveX control visible.

Setting native properties

To set native properties, you need to know two things: the internal name of the property and the possible values. The following Visual Basic code shows how to set the background color for the Calendar control.

ActiveXPropBag.Write Key:="BackColor", value:=vbBlue

This example uses the Write method to set the native ActiveX BackColor property for the Calendar control to the enumerated color value of vbBlue. For managed components, in this case, you would need to pass in a string that represents the RGB color value.

Note  You cannot set all the properties through the ISmartDocProperties interface. For example, an ActiveX control may expose a property named Font that is actually an accessor property that returns an object that has additional properties. You would be unable to access the child properties of this object from the ISmartDocProperties interface.

Returning values

To return values from an ActiveX control, you need to add a reference to the ActiveX control.

Important  Make certain that you add a reference to the control rather than add the control to the Toolbox. Adding a control to the Toolbox will not enable the control to function properly within the Document Actions task pane.

Next, you need to create a global variable to work with the control's events. In Visual Basic 6.0 and Visual Basic .NET, you use the WithEvents keyword when declaring the global variable. In C#, you add an event handler to the object variable.

Finally, you need to connect the global variable to the instance of the control in the task pane. To do this, you use the OnPaneUpdateComplete method to assign the global object variable to the resulting smart document action, or in this case to the ActiveX control. You can do this by using the ActiveXControl property of the host application's Visual Basic for Applications object model.

However, to connect the global variable to the ActiveX control, you need to access the currently active element. The Document parameter of the OnPaneUpdateComplete method provides access to the smart document. From this object, you need to locate the currently active element, and then the SmartTagActions collection for the element.

  • In Microsoft Office Word 2003, you can locate the currently active element by using the ActiveWindow property and then using the Selection object and the XMLParentNode property. You can also locate the currently active element by specifying an XPath query for the SelectNodes and SelectSingleNode methods of the Document object.
  • In Microsoft Office Excel 2003, you can locate the currently active element by specifying an XPath query for the XmlMapQuery and XmlDataQuery methods.

Then, you need to determine whether the ActiveX control is displayed in the task pane. To do this, you use the PresentInPane property of the SmartTagAction object. Because elements can potentially have multiple actions, you may need to loop through each action for an element, or you can use the friendly name that you specified in the ControlNameFromID property.

Understanding the code

For code examples that show how to work with ActiveX controls, see the ActiveX Controls topic in one of the following tutorials:

A note about working with managed code

When a managed smart document contains ActiveX controls, the host application can stop responding as the task pane is updated, for example, when the user moves through the tags that have ActiveX actions associated with them.

To avoid causing the host application to stop responding, you need to force a garbage collection within the PopulateActiveXProps method. For more information about how to do this, see Forcing a Garbage Collection.

Known issues with using ActiveX controls in smart documents

The following known issues can occur when working with ActiveX controls inside a smart document. This list is by no means comprehensive and may include additional related issues that are not covered here.

  • Users may not be able to type text in text boxes that exist inside an ActiveX control.
  • When users press the TAB key, text in text boxes is not deselected, and users are unable to use the TAB key to move through check boxes or radio buttons.