ActiveX controls have property sheets that enable the user to set properties without any change to the container application. You set these up as dialog boxes, taking advantage of prewritten pages for font, color, and other common properties. For this control, the obvious properties to add are the following:

It’s a simple enough matter to allow the user to choose whether to display the current value as a digit or a dot pattern. Simply add a property that indicates this preference and then use the property in OnDraw(). The user can set the property, using the property page.

First, add the property using ClassWizard. Here’s how: Bring up ClassWizard and select the Automation tab. Make sure that the CDierollCtrl class is selected and then click Add Property. On the Add Property dialog box, provide the external name Dots and the internal name m_dots. The type should be BOOL because Dots can be either TRUE or FALSE. Implement this new property as a member variable (direct-access) property. Click OK to complete the Add Property dialog box and click OK to close ClassWizard. The member variable is added to the class, the dispatch map is updated, and a stub is added for the notification function, OnDotsChanged().

To initialize Dots and arrange for it to be saved with a document, add the following line to DoPropExchange() after the call to PX_Short():

Initializing the Dots property to TRUE ensures that the control’s default behavior is to display the dot pattern.

In OnDraw(), uncomment those lines that displayed the digit. Wrap an if around them so that the digit is displayed if m_dots is FALSE and dots are displayed if it is TRUE. The code looks like Listing 11.12.

To give the user a way to set Dots, you build a property page by following these steps:

FIG. 11.10 AppWizard generates an empty property page.

FIG. 11.11 You build the property page for the die-roll control like any other dialog box.

When the user brings up the property page and clicks to set or unset the check box, that doesn’t directly affect the value of m_dots or the Dots property. To connect the dialog box to member variables, use ClassWizard and follow these steps:

FIG. 11.12 You connect the property page to the properties of the control with ClassWizard.

The path that data follows can be a little twisty. When the user brings up the property sheet, the value of TRUE or FALSE is in a temporary variable. Clicking the check box toggles the value of that temporary variable. When the user clicks OK, that value goes into CDierollPropPage::m_dots and also to the Automation property Dots. That property has already been connected to CDierollCtrl::m_dots, so the dispatch map in CDierollCtrl will make sure that the other m_dots is changed. Because the OnDraw() function uses CDierollCtrl::m_dots, the control’s appearance changes in response to the change made by the user on the property page. Having the same name for the two member variables makes things more confusing to first-time control builders but less confusing in the long run.

This works now. Build the control and insert it into the test container. To change the properties, choose Edit, Dieroll Control Object, and Properties; your own property page will appear, as shown in Figure 11.13. (The Extended tab is provided for you, but as you can see, it doesn’t really do anything. Your General tab is the important one at the moment.) Prove to yourself that the control displays dots or a digit, depending on the page’s setting, by changing the setting, clicking OK, and then watching the control redraw.

When the control is displaying the value as a number, you might want to display that number in a font that’s more in proportion with the control’s current width and height and centered within the control. That’s a relatively simple modification to OnDraw(), which you can investigate on your own.

FIG. 11.13 The control test container displays your own property page.

The die you’ve created will always have black dots on a white background, but giving the user control to change this is remarkably simple. You need a property for the foreground color and another for the background color. These have already been implemented as stock properties: BackColor and ForeColor.

Stock Properties Here is the complete list of stock properties available to a control that you write:

Ambient Properties Controls can also access ambient properties, which are properties of the environment that surrounds the control—that is, properties of the container into which you place the control. You can’t change ambient properties, but the control can use them to adjust its own properties. For example, the control can set its background color to match that of the container.

The container provides all support for ambient properties. Any of your code that uses an ambient property should be prepared to use a default value if the container doesn’t support that property. Here’s how to use an ambient property called UserMode:

This code calls GetAmbientProperty() with the display ID (DISPID) and variable type (vartype) required. It also provides a pointer to a variable into which the value is placed. This variable’s type must match the vartype. If GetAmbientProperty() returns FALSE, bUserMode is set to a default value.

A number of useful DISPIDs are defined in olectl.h, including these:

• DISPID_AMBIENT_BACKCOLOR

• DISPID_AMBIENT_DISPLAYNAME

• DISPID_AMBIENT_FONT

• DISPID_AMBIENT_FORECOLOR

• DISPID_AMBIENT_LOCALEID

• DISPID_AMBIENT_MESSAGEREFLECT

• DISPID_AMBIENT_SCALEUNITS

• DISPID_AMBIENT_TEXTALIGN

• DISPID_AMBIENT_USERMODE

• DISPID_AMBIENT_UIDEAD

• DISPID_AMBIENT_SHOWGRABHANDLES

• DISPID_AMBIENT_SHOWHATCHING

• DISPID_AMBIENT_DISPLAYASDEFAULT

• DISPID_AMBIENT_SUPPORTSMNEMONICS

• DISPID_AMBIENT_AUTOCLIP

• DISPID_AMBIENT_APPEARANCE

Remember that not all containers support all these properties. Some might not support any, and still others might support properties not included in the preceding list.

The vartypes include those shown in Table 11.1.

Remembering which vartype goes with which DISPID and checking the return from GetAmbientProperty() are a bothersome process, so the framework provides member functions of COleControl to get the most popular ambient properties:

All these functions assign reasonable defaults if the container doesn’t support the requested property.

Implementing BackColor and ForeColor To add BackColor and ForeColor to the control, follow these steps:

FIG. 11.14 ClassWizard describes stock properties for you.

FIG. 11.15 An S precedes the stock properties in the OLE Automation list of properties and methods.

Setting up the property pages for these colors is almost as simple because there is a prewritten page that you can use. Look through DierollCtl.cpp for a block of code like Listing 11.13.

Remove the TODO reminder, change the count to 2, and add another PROPPAGEID so that the block looks like Listing 11.14.

CLSID_CColorPropPage is a class ID for a property page that is used to set colors. Now when the user brings up the property sheet, there will be two property pages: one to set colors and the general page that you already created. Both ForeColor and BackColor will be available on this page, so all that remains to be done is using the values set by the user. You will have a chance to see that very soon, but first, your code needs to use these colors.

Changes to OnDraw() In OnDraw(), your code can access the background color with GetBackColor(). Though you can’t see it, this function was added by ClassWizard when you added the stock property. The dispatch map for CDierollCtrl now looks like Listing 11.15.

The macro DISP_STOCKPROP_BACKCOLOR() expands to these lines:

This code is calling another macro, DISP_PROPERTY_STOCK, which ends up declaring the GetBackColor() function as a member of CDierollCtrl, which inherits from COleControl. Although you can’t see it, this function is available to you. It returns an OLE_COLOR, which you translate to a COLORREF with TranslateColor(). You can pass this COLORREF to CreateSolidBrush() and use that brush to paint the background. Access the foreground color with GetForeColor() and give it the same treatment. (Use SetTextColor() in the digit part of the code.) Listing 11.16 shows the completed OnDraw() (with most of the switch statement cropped out).

Build the control again, insert it into the test container, and again bring up the property sheet by choosing Edit, Dieroll Control Object, Properties. As Figure 11.16 shows, the new property page is just fine for setting colors. Change the foreground and background colors a few times and experiment with both dots and digit display to exercise all your new code.

FIG. 11.16 Stock property pages make short work of letting the user set colors.