7.2 OLE Controls

7.2.2 Ambient properties

OLE control containers typically make property information available to the controls they contain. Ambient properties allow a control to know about and adapt itself to the environment in which it is running.

Some properties are used directly by the OLE-Control-Framework library and you do not need to be concerned about them. (This includes $DISPID-AMBIENT-SHOWHATCHING.) Others are cached by OLE-Control-Framework so that you can access them easily by calling the following functions:

The current value of any ambient property can be obtained like this:

let dispatch-interface = object.container-IDispatch;

unless ( null-pointer?(dispatch-interface) )
  let value = get-property(dispatch-interface, disp-id,
                           default: $unfound);
  unless ( value == $unfound )
    ... // use the value
  end unless;
end unless;

The function get-property is from the OLE-Automation library; see page 218. A default: value must be supplied because containers are not required to support all properties. The particular property is identified by a Dispatch ID, which is one of the following constants:

$DISPID-AMBIENT-AUTOCLIP
: True if container automatically clips the control display area.
$DISPID-AMBIENT-APPEARANCE
: Control appearance:
: 0 => flat
: 1 => 3D
$DISPID-AMBIENT-BACKCOLOR
: Background color. Convert the value with OLE-util-translate-color, page 347.
$DISPID-AMBIENT-FORECOLOR
: Foreground color. Convert the value with OLE-util-translate-color, page 347.
$DISPID-AMBIENT-FONT
: Font, as an IDispatch interface.
$DISPID-AMBIENT-DISPLAYNAME
: Name of control for use in error messages.
$DISPID-AMBIENT-LOCALEID
: Locale.
$DISPID-AMBIENT-MESSAGEREFLECT
: Boolean value indicating whether the container wants to receive Windows messages such as $WM-CTLCOLOR, $WM-DRAWITEM, or $WM-PARENTNOTIFY.
$DISPID-AMBIENT-SCALEUNITS
: A string (actually an instance of <ole-array>, page 198) naming the coordinate unit used by the container.
$DISPID-AMBIENT-TEXTALIGN
: Text alignment:
: 0 => numbers to the right and text to the left
: 1 => left
: 2 => center
: 3 => right
: 4 => fill justify
$DISPID-AMBIENT-USERMODE
: True if user mode, false if design mode.
$DISPID-AMBIENT-UIDEAD
: True if user input should be ignored.
$DISPID-AMBIENT-SHOWGRABHANDLES
: True to enable resize handles.
$DISPID-AMBIENT-DISPLAYASDEFAULT
: True if control is the default button.
$DISPID-AMBIENT-SUPPORTSMNEMONICS
: True if container supports mnemonics.

Alternatively, a control can ask to be notified whenever the value of an ambient property changes. This is done by defining a method on the function OLE-part-ambient-properties, page 345, to specify which properties are of interest, and defining one or more methods on OLE-part-set-ambient-property, page 346, to receive the values. The following functions are also related to ambient property support: