I mentioned earlier that OLE Controls defines a taxonomy for the classification of methods, properties, and events. Not only that, but OLE Controls defines a large number of standard dispID values beyond those we saw in Chapter 14. In defining these standards, OLE Controls uses the term location to describe which piece of code implements a particular method or property. The term variety describes how rigid a contract is defined for the property, method, or event in question. Standard properties have a specified behavior that must be followed. Common properties are more lax, as they have only a suggested behavior. Other properties, as you might guess, have no specific behavior and are entirely implementation-dependent. OLE itself doesn't define any methods, properties, or events in the common and other groups.
There are no less than 14 standard control properties. The names of the most interesting ones are listed in Table 24-3 on the next page. In addition, there are three standard methods—Refresh, DoClick, and AboutBox—and eight standard events—Click, DblClick, KeyDown, KeyPress, KeyUp, MouseMove, MouseUp, and Error. All of these have negative dispID values, indicating their standard status. This also applies to the 15 or so standard ambient properties (the interesting ones are described in Table 24-4) and a handful of standard extended properties, as described in Table 24-5. To avoid conflicts in the programmatic symbols for these dispIDs, all ambient properties are given symbols in the form DISPID_AMBIENT_<property>, as in DISPID_AMBIENT_FORECOLOR. All other symbols use DISPID_<property> as usual.7
Control Property | Type and Description |
BackColor, ForeColor, FillColor, BorderColor | (OLE_COLOR) The control's color scheme. |
BackStyle, FillStyle, BorderStyle, BorderWidth, BorderVisible, DrawStyle, DrawWidth | (short or long) Bits that define a control's visual behavior—solid or transparent, thick or thin borders, line style, and so forth. |
Font | (IDispatch *) The font used in the control. This is an IDispatch pointer to a standard font object (see below). |
Caption, Text | (BSTR) Strings containing the control's label (the caption) or its textual contents (the text). The caption does not necessarily name the control in the container. (See the extended Name property in Table 24-5.) |
Enabled | (BOOL) Determines whether the control is enabled or disabled. (If disabled, the control is likely grayed.) |
Window | (HWND) The window handle of the control, if it has one. |
Table 24-3.
Standard control properties.
Ambient Property | Type and Description |
BackColor, ForeColor | (OLE_COLOR) Provides controls with the default background and foreground colors. Use by a control is optional. |
Font | (IDispatch *) A pointer to a standard font object (see below) that defines the default font for the form. Use by a control is optional. |
LocaleID | (LCID) The language used in the container. Use by a control is recommended. |
UserMode | (BOOL) Describes whether the container is in design mode (FALSE) or run mode (TRUE). A control must use this property to change its available functionality as necessary. |
UIDead | (BOOL) Describes whether the container is in a mode in which controls should ignore user input. This applies irrespective of UserMode. A container might always set UIDead to TRUE in design mode and can set it to TRUE when it hits a breakpoint or such during run mode. A control must pay attention to this property. |
MessageReflect | (BOOL) Specifies whether the container wants to receive Windows messages such as WM_CTLCOLOR, WM_DRAWITEM, WM_PARENTNOTIFY, and so on as events. |
SupportsMnemonics | (BOOL) Describes whether the container processes mnemonics or not. A control can do whatever it wants with this information: for example, it would not underline characters it would normally use as a mnemonic. |
ShowGrabHandles, ShowHatching | (BOOL) Describes whether a control should show a hatch border or grab handles (in the hatch border) when in-place active. Controls must obey these properties, giving the container ultimate control over whether the control or the container actually draws these bits of user interface. A control container might want to draw its own instead of relying on each control, in which case these ambients are always FALSE. |
DisplayAsDefault | (BOOL) Describes whether a button control should draw itself with a thicker default frame. This property is exposed to buttonlike controls only. |
Table 24-4
Standard ambient properties.
Extended Property | Type and Description |
Name | (BSTR) The container's name for the control. |
Visible | (BOOL) The control's visibility. |
Parent | (IDispatch *) The dispinterface of the form containing the control. |
Default, Cancel | (BOOL) Indicates whether this control is the default or cancel button as described later under "Default and Cancel Buttons." |
Table 24-5.
Standard extended control properties.
The OLE_COLOR type is used for any color-related properties in OLE Controls. Usually it holds a standard COLORREF type, but it can also hold an index to a palette, a palette-relative index, or even a system color index appropriate for GetSysColor. The OLE Controls run-time DLL, the same DLL that supplies the OleCreatePropertyFrame and OleCreatePropertyFrameIndirect functions, provides OleTranslateColor , a function that converts an OLE_COLOR type to a COLORREF given a palette.
The standard font object is also implemented as part of the OLE Controls DLL. A font object is created with the OLE API function OleCreateFontIndirect, which takes a FONTDESC structure describing the font metrics. This function returns a pointer to either an IFont interface or an IDispatch interface (also called IFontDisp) through which the client can manipulate the font's properties or retrieve the corresponding HFONT that is used to draw text with that font. The container's ambient Font property supplies a font of this type (VT_DISPATCH specifically). A control's Font property also uses this kind of font object.
In a similar vein, a standard picture object is created with the API function OleCreatePictureIndirect or loaded from disk using OleLoadPicture. For this object, you can get a pointer to an IPicture interface or to an IDispatch pointer called IPictureDisp. Through this pointer, you can also manipulate the picture's properties.
For more information about these types and their interfaces, please refer to the CDK documentation.
7 I could not find a header file that defined symbols for the standard extended properties. According to the OLE Controls specification, DISPID_X_NAME is 0x80010000, DISPID_X_VISIBLE is 0x80010007, DISPID_X_PARENT is 0x80010008, DISPID_X_CANCEL is 0x80010037, and DISPID_X_DEFAULT is 0x80010038. |