Visual Basic Concepts

Using the AmbientProperties Object to Stay Consistent with the Container

Containers provide ambient properties to give controls hints about how they can best display themselves in the container. For example, the ambient BackColor property tells a control what color to set its own BackColor property to in order to blend in with the container.

Visual Basic makes ambient properties available to your ActiveX control through an AmbientProperties object. The Ambient property of the UserControl object returns a reference to the AmbientProperties object.

The AmbientProperties object provided by Visual Basic contains all of the standard ambient properties defined by the ActiveX Controls Standard, whether or not they are actually provided by the container your control instance was placed on.

This means that you can safely access any of the properties of the AmbientProperties object visible in the Object Browser. If you access an ambient property not provided by the container, the AmbientProperties object returns a default value, as listed in the topics for the AmbientProperties object properties.

Containers That Provide Additional Ambient Properties

Control containers may define their own ambient properties. These container-specific ambient properties are not visible in the Object Browser, because they are not in Visual Basic's type library. You can learn about such properties in the documentation for a container, and access them as if they were properties of the AmbientProperties object.

Because these properties are not in the type library, Visual Basic cannot verify their existence at compile time. Therefore you should always use error handling when working with Ambient properties.

Another consequence of the lack of type library information is that calls to container-specific ambient properties are always late-bound. By contrast, calls to standard ambient properties are early-bound.

Important Ambient Properties

You can ignore many of the standard ambient properties. In a Visual Basic ActiveX control, you can ignore the MessageReflect, ScaleUnits, ShowGrabHandles, ShowHatching, SupportsMnemonics, and UIDead properties of the AmbientProperties object.

Ambient properties you should be aware of are listed below.

UserMode

The most important property of the AmbientProperties object is UserMode, which allows an instance of your control to determine whether it's executing at design time (UserMode = False) or at run time. Use of this property is discussed in "Creating Design-Time-Only or Run-Time-Only Properties," later in this chapter.

Tip   To remember the meaning of UserMode, recall that at design time the person working with your control is a developer, rather than an end user. Thus the control is not in "user" mode, so UserMode = False.

LocaleID

If you're developing a control for international consumption, you can use the LocaleID ambient property to determine the locale. Use of this property is discussed in "Localizing Your Control," later in this chapter.

DisplayName

Include the value of the DisplayName property in errors your control raises at design-time, so the developer using your control can identify the control instance that is the source of the error.

ForeColor, BackColor, Font, and TextAlign

These properties are hints your control can use to make its appearance match that of the container. For example, in the InitProperties event, which each instance of your UserControl receives when it is first placed on a container, you can set your control's ForeColor, BackColor, Font, and TextAlign to the values provided by the ambient properties. This is a highly recommended practice.

You could also give your control properties which the user could use to keep a control instance in sync with the container. For example, you might provide a MatchFormBackColor property; setting this property to True would cause your control's BackColor property always to match the value of the BackColor property of the AmbientProperties object. You can provide this kind of functionality using the AmbientChanged event, discussed below.

DisplayAsDefault

For user-drawn controls, this property tells you whether your control is the default button for the container, so you can supply the extra-heavy border that identifies the default button for the end user.

If you didn't set your control up to be a default button, you can ignore this property. See "Allowing Your Control to be a Default or Cancel Button," in this chapter.

For More Information   See "User-Drawn Controls," in this chapter. Also, a full list of the properties of the AmbientProperties object is available in the Language Reference.

The AmbientChanged Event

If your control's appearance or behavior is affected by changes to any of the properties of the AmbientProperties object, you can place code to handle the change in the UserControl_AmbientChanged event procedure.

The argument of the AmbientChanged event procedure is a string containing the name of the property that changed.

Important   If you're authoring controls for international use, you should always handle the AmbientChanged event for the LocaleID property. See "Localizing Controls," later in this chapter.

Note   If an instance of your control is placed on a Visual Basic form, and the FontTransparent property of the form is changed, the AmbientChanged event will not be raised.