Visual Basic Concepts

Understanding the Container’s Extender Object

When you view an instance of your control in the Properties window, you'll see a number of properties you didn't author. These extender properties are provided by the container your control is placed on, but they appear to be a seamless extension of your control, as shown in Figure 9.6.

Figure 9.6   Extender properties, methods, and events are provided by the container

A UserControl object can access extender properties through its Extender object. For example, the ShapeLabel control in "Creating an ActiveX Control" uses the following code to initialize its Caption property:

Private Sub UserControl_InitProperties()
   ' Let the starting value for the Caption
   '   property be the default Name of this
   '   instance of ShapeLabel.
   Caption = Extender.Name
End Sub

Extender properties are provided for the developer who uses your control. Generally speaking, the author of a control should not attempt to set them with code in the UserControl. For example, it's up to the developer to decide where a particular instance of your control should be located (Top and Left properties), or what icon it should use when dragged.

Extender Properties are Late Bound

When you compile your control component, Visual Basic has no way of knowing what kind of container it may be placed on. Therefore references to Extender properties will always be late bound.

Standard Extender Properties

The ActiveX control specification lists the following properties that all containers should provide:

Property	Type	Access	Meaning
Name	String	R	The name the user assigns to the control instance.
Visible	Boolean	RW	Indicates whether the control is visible.
Parent	Object	R	Returns the object which contains the control, such as a Visual Basic form.
Cancel	Boolean	R	True if the control is the cancel button for the container.
Default	Boolean	R	True if the control is the default button for the container.

Although it is highly recommended that containers implement these properties, containers do not have to do so. Thus you should always use error trapping when referring to properties of the Extender object in your code, even standard properties.

Many containers provide additional extender properties, such as Left, Top, Width, and Height properties.

Note   If you wish your control to be invisible at run time, set the UserControl object's InvisibleAtRuntime property to True, as discussed in "Making Your Control Invisible at Run Time," later in this chapter. Do not use the Extender object's Visible property for this purpose.

Container-Specific Controls

If you design your control so that it requires certain Extender properties, your control will not work in containers that don't provide those properties. There is nothing wrong with building such container-specific controls, except that the potential market for them is smaller.

If you are creating a control designed to address a limitation of a particular container, such considerations may not matter to you. However, conscientious use of error trapping will prevent your control from causing unfortunate accidents if it is placed on containers it was not specifically designed for.

Working with Container Limitations

Visual Basic provides a rich set of extender properties and events, listed in the topic for the Extender object. Many containers provide only a limited subset of these.

In general, Extender properties, methods, and events are not the concern of the control author. Many Extender properties, such as Top and Left, or WhatsThisHelpID, cannot be implemented by a control, because the container must provide the underpinnings these properties require.

Collisions Between Control and Extender Properties

If an instance of your control is placed on a container that has an extender property with the same name as a property of your control, the user will see the extender property.

For example, suppose you gave your control a Tag property. When an instance of your control is placed on a Visual Basic form, a Tag property is supplied by the form's Extender object. If your control is called ShapeLabel, the user might write the following code:

ShapeLabel1.Tag = "Triceratops"

The code above stores the string "Triceratops" in the Tag property provided by the Visual Basic form's Extender object. If an instance of your control is placed on a container whose Extender object doesn't supply a Tag property, the same code will store the string in the Tag property you implemented.

In order to access the Tag property of your control on a Visual Basic form, the user could employ another Extender object property, as shown in the following code fragment:

ShapeLabel1.Object.Tag = "Triceratops"

The Object property returns a reference to your control's interface just as you defined it, without any extender properties.