Standard Component Wrappers and ActiveX Control Subobjects

Standard Component Wrappers and ActiveX Control Subobjects

ActiveX controls that contain one or more subobjects have a split personality. The top-level set of control properties, methods, and events are wrapped and handled by an Ax wrapper. A simple component wrapper wraps all subobjects and other types defined by the control. A simple component wrapper is also applied to all standard ActiveX components that are not ActiveX controls. For example, if you reference ADO, a simple component wrapper is applied to expose the properties, methods, and events of all ADO objects. The objects are exposed using the .NET types that most closely represent the underlying type contained in the ActiveX component.

In the case of the TreeView control, the Ax wrapper is applied to the TreeView s top-level properties, methods, and events. Properties such as Appearance, Font, and Style are wrapped and handled by the Ax wrapper. The Ax wrapper exposes the Font property as a System.Drawing.Font, for example. If TreeView had a BackColor property, it would be exposed as a System.Drawing.Color property.

Now let s take a look at subobjects that the TreeView control exposes, such as Nodes and Node. The BackColor property of a Node gets exposed to you as a System.UInt32 type. But isn t BackColor type OLE_COLOR? Why UInt32 ? UInt32 is chosen for two reasons:

• The type most closely matches the type OLE_COLOR, which itself is a UInt32.

• Neither the simple component wrapper nor the Ax wrapper supports type aliases. In the original COM type library, OLE_COLOR is an alias for UInt32.

Consider the following Visual Basic 6 example, which sets the ForeColor property on both the ListView ActiveX control and one of its ListItem subobjects:

Dim li As ListItem Set li = ListView1.ListItems.Add(, "Item1Key", "Item1") ListView1.ForeColor = vbRed li.ForeColor = vbRed

After upgrade, the Visual Basic .NET code is as follows:

ListView1.ForeColor = System.Drawing.Color.Red li.ForeColor = _ System.Convert.ToUInt32(System.Drawing.ColorTranslator.ToOle( _ System.Drawing.Color.Red))

Although ForeColor is the same exact type for ListView and the ListItem object, the code needed to assign the value of Red is radically different. The ListView ForeColor property is exposed by the Ax wrapper as type System.Drawing.Color, so it s quite natural to assign a System.Drawing.Color.Red object to the property. The ListView Ax wrapper takes care of translating the System.Drawing.Color.Red object value to the equivalent UInt32 color value.

In the case of the ListItem.ForeColor property, the simple component wrapper exposes the type as System.UInt32, leaving it up to you to figure out how to convert a System.Drawing.Color.Red object value to a numeric UInt32 color value. To make this conversion, you first need to convert the color object to a numeric value by using System.Drawing.ColorTranslator.ToOle. The ToOle function returns a signed long integer or System.Int32. You then need to convert the Int32 value to a UInt32 value by using the System.Convert class.

Fortunately, the Upgrade Wizard handles most of these conversions for you. The downside is that you may end up with some rather unfamiliar-looking conversion code. Table 16-2 provides a list of conversion helper functions so that you ll understand how the conversion works when you see one of these in code. You can also use these functions when writing new code to help make assignments between ActiveX and .NET types.

Table 16-2 Useful Conversion Functions for Common ActiveX Object Types

Conversion Function(s)	Description
System.Convert methods	Allow you to convert from virtually any .NET type to another .NET type. Use System.Convert to convert 32-bit signed integers (System.Int32) to 32-bit unsigned integers (System.UInt32).
System.Drawing.ColorTranslator methods	Allow you to convert between OLE color, Windows color, and .NET color types.
FontToIFont, IFontToFont	Located in the Microsoft.Visual Basic.Compatibility.VB6.Support class. You use these functions to convert between .NET and ActiveX Font types. They are used primarily when you are trying to get or set an ActiveX component property that is exposed as Object, IFont, IFontDisp, or as a component-specific class that implements IFont.
CursorToIPicture, IconToIPicture	Allow you to convert a System.Windows.Forms.Cursor or System.Drawing.Icon type directly to an ActiveX IPicture.
ImageToIPicture, ImageToIPictureDisp, IPictureToImage, IPictureDispToImage	Allow you to convert between the .NET System.Drawing.Image and ActiveX IPicture types. These functions are intended for situations in which you are trying to get or set an ActiveX component Picture property that is defined as Object, IPicture, IPictureDisp, or as a component-specific class declaration that implements IPicture.

Common Exceptions That Require Type Conversions

Certain lines of your upgraded code may contain type mismatch assignments. For example, you may find code in which the MousePointer property of an ActiveX control is being assigned to a System.Windows.Forms.Cursors property. The problem is that an ActiveX MousePointer property is usually a MousePointerConstants enumeration type defined by the control in other words, a numeric type. Each System.Windows.Forms.Cursors property, such as IBeam, returns a Cursor object. Attempting to assign a Cursor object to a numeric type is a recipe for a compiler error. In this case, you receive a descriptive compiler error telling you that you cannot assign a Cursor to a numeric type.

Compiler errors are not the type of errors that you need to worry about. Although annoying at times, they are in-your-face error messages that point directly to a problem in your code. You can easily locate the problem and, in most cases, especially with the help of IntelliSense, find a quick fix. A more insidious problem that will give you fits is an exception that occurs at run time. The two most common exceptions that relate to the assignment of incompatible types at run time are InvalidCastException and COMException.

InvalidCastException

The InvalidCastException is a standard .NET exception that occurs when the .NET Framework is unable to cast one type to another at run time. This exception commonly occurs when you attempt to assign a .NET type to an ActiveX type. For example, if you attempt to assign a .NET collection to an ActiveX component method that returns a Visual Basic 6 Collection object, this exception will occur.

COMException

A COMException can occur any time a property or method of an ActiveX control or component is called. The exception generally occurs because the Visual Basic .NET code is passing a .NET object when it should be passing an ActiveX object. For example, if you attempt to assign an Ax wrapped ImageList control to the ImageList property of an Ax wrapped TreeView control, as in the following line of code, it will bark back at run time with a COMException.

AxTreeView1.ImageList = AxImageList1

The problem happens in this case because you need to assign the underlying ActiveX control object to the ImageList property. You can obtain the underlying ActiveX control object by calling GetOcx on the Ax wrapped control. The following code works and does not bark at you:

AxTreeView1.ImageList = AxImageList1.GetOcx()