Implementing an ambient-property handler

Ambient properties are used by a container to give an OCX information about its surroundings, such as the background color of a form, the current font, or the locale ID of the container's user interface.

Each ambient property is identified by a unique DISPID, which an OCX uses to specify which ambient property it wants from its container. To support the integration of OCXs with containers, OLE defines a set of standard ambient-property DISPIDs. This set is encoded into the Smalltalk pool dictionary PlatformConstants as follows:

Ambient Property DISPID	Class	Specifies
DispidAmbientBackcolor	Integer	The color of the interior of an OCX (in RGB values)
DispidAmbientDisplayname	String	the name the OCX should display for itself in error messages
DispidAmbientDisplayasdefault	Boolean	Whether a button OCX should draw itself with a thicker frame (for button-like OCXs only)
DispidAmbientForecolor	Integer	The color of the display of text and graphics in an OCX (in RGB values)
DispidAmbientLocaleid	Integer	The ID of the UI locale
DispidAmbientMessagereflect	Boolean	Whether the container wants to receive MS Windows messages
DispidAmbientSupportsmnemonics	Boolean	Whether the container processes mnemonics
DispidAmbientShowgrabhandles	Boolean	Whether the OCX should show grab handles when in-place activated
DispidAmbientShowhatching	Boolean	Whether an OCX should show a hatch border when in-place activated
DispidAmbientScaleunits	String	The name of the units by the container
DispidAmbientTextalign	Integer	How text should be aligned in an OCX: 0 General (numbers to the right, text to the left) 1 Left 2 Center 3 Right 4 Fully justified
DispidAmbientUsermode	Boolean	Whether the container is in design mode (false) or run mode (true)
DispidAmbientUidead	Boolean	Whether the container is in a mode in which OCXs should ignore user input

Ambient-property handlers are implemented as methods that take a single parameter, which is the DISPID of the ambient property being requested by the OCX. OCXs may not request all possible ambient properties but only those they are interested in. Likewise, a container may not necessarily be able to respond to all ambient property requests. The ambient property handler answers the value of the requested property if it can; otherwise, it answers a nil value to inform the OCX that the property is not available. For example, the ambient-property-handler method dispidAmbientPropertyAt: in the above example might be implemented as follows:

dispidAmbientPropertyAt: dispid

"Private - Handle ambient properties."

DispidAmbientShowgrabhandles == dispid ifTrue: ^false].

DispidAmbientShowhatching == dispid ifTrue: ^false].

DispidAmbientLocaleid == dispid ifTrue: ^LocaleUserDefault].

DispidAmbientUidead == dispid ifTrue: ^false].

DispidAmbientUsermode == dispid ifTrue: ^false].

^nil

Here, the constant LocaleUserDefault comes from the pool dictionary PlatformConstants.

Note:

A class that implements OLE-container behavior should declare PlatformConstants as pool dictionaries.