Programmer's Reference

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.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]