Visual Basic Reference

  • Article

AmbientProperties Object

See Also    Example    Properties    Methods    Events

An AmbientProperties object holds ambient information from a container to suggest behavior to controls contained within the container.

Remarks

Containers provide ambient properties in order to suggest behavior to controls. As an example, BackColor is one of the standard ambient properties; the container is suggesting what the well-behaved control should set its BackColor property to.

The AmbientProperties objects properties are the ambient properties of the container. These properties are read-only.

Some ambient properties are standard, while others are specific to certain containers. A control may access non-standard ambient properties, but this will make the control container-specific. The control should handle the case where an ambient property is not present in the current container.

When the control is compiled, Visual Basic has no way of knowing what container-specific ambient properties may be available when the control is run; therefore references to container-specific ambient properties will always be late bound.

The AmbientProperties object is not available when the Initialize event is raised; but is available when the InitProperties event or ReadProperties event is raised.

The AmbientProperties object has several standard properties:

  • The BackColor property, a Color that contains the suggested interior color of the contained control. The Visual Basic supplied default if the container does not support this property is 0x80000005: the system color for a window background.

  • The DisplayAsDefault property, a Boolean that specifies if the control is the default control. The Visual Basic supplied default if the container does not support this property is False.

  • The DisplayName property, a String containing the name that the control should display for itself. The Visual Basic supplied default if the container does not support this property is an empty string: "".

  • The Font property, a Font object that contains the suggested font information of the contained control. The Visual Basic supplied default if the container does not support this property is MS Sans Serif 8.

  • The ForeColor property, a Color that contains the suggested foreground color of the contained control. The Visual Basic supplied default if the container does not support this property is 0x80000008: the system color for window text.

  • The LocaleID property, a Long that specifies the language and country of the user. The Visual Basic supplied default if the container does not support this property is the current system locale ID.

  • The MessageReflect property, a Boolean that specifies if the container supports message reflection. The Visual Basic supplied default if the container does not support this property is False.

  • The Palette property, a Picture object whose palette specifies the suggested palette for the contained control.

  • The RightToLeft property, a Boolean that indicates the text display direction and control visual appearance on a bidirectional system. The Visual Basic supplied default if the container does not support this property is False.

  • The ScaleUnits property, a String containing the name of the coordinate units being used by the container. The Visual Basic supplied default if the container does not support this property is an empty string: "".

  • The ShowGrabHandles property, a Boolean that specifies if the container handles the showing of grab handles. The Visual Basic supplied default if the container does not support this property is True.

  • The ShowHatching property, a Boolean that specifies if the container handles the showing of hatching. The Visual Basic supplied default if the container does not support this property is True.

  • The SupportsMnemonics property, a Boolean that specifies if the container handles access keys for the control. The Visual Basic supplied default if the container does not support this property is False.

  • The TextAlign property, an enumeration that specifies how text is to be aligned. The Visual Basic supplied default if the container does not support this property is 0 - General Align.

  • The UserMode property, a Boolean that specifies if the environment is in design mode or end user mode. The Visual Basic supplied default if the container does not support this property is True.

  • The UIDead property, a Boolean that specifies if the User Interface is unresponsive. The Visual Basic supplied default if the container does not support this property is False.

Note   When you access the Font property of the AmbientProperties object, you do not get a reference to the container's font. Rather, you get a copy (clone) of the font.

The reason for this is that AmbientProperties.Font is commonly used to initialize a control's font whenever an instance of the control is added to a container. If a reference to the font itself were supplied, then changing the control's font would change the container's font as well.

If for some reason your control requires a reference to the container's font, you can obtain it by accessing the container through the Parent property of the UserControl object.