Color Dialog Box

The Color dialog box returns the RGB value of a color selected by the user. The user can select from a set of basic colors determined by the display driver or from a set of custom colors. You must specify the initial set of custom colors, but you can allow users to create their own custom colors.

You create and display a Color dialog box by initializing a CHOOSECOLOR structure and passing the structure to the ChooseColor function.

You can partially open the Color dialog box to display the basic and custom colors from which the user can select, or you can completely open the dialog box to display additional controls that allow the user to create custom colors. The following illustration shows the fully opened Color dialog box.

If the user clicks the OK button, ChooseColor returns TRUE. The rgbResult member of the CHOOSECOLOR structure contains the RGB color value of the color selected by the user. The RGB color value specifies the intensities of the individual red, green, and blue colors that make up the selected color. The individual values range from 0 through 255. Use the GetRValue , GetGValue , and GetBValue macros to extract individual colors from an RGB color value.

If the user cancels the Color dialog box or an error occurs, ChooseColor returns FALSE and the rgbResult member is not defined. To determine the cause of the error, call the CommDlgExtendedError function to retrieve the extended error value.

The following subjects are covered in this section

• Basic and Extended Color Dialog Boxes
• Customizing the Color Dialog Box
• Color Models Used by the Color Dialog Box

Basic and Extended Color Dialog Boxes

The Color dialog box has a basic version and an extended version. The basic version has controls that display the basic and custom colors from which the user can select. The extended version includes the basic controls and has additional controls that allow the user to create custom colors.

The basic version of the Color dialog box includes a Define Custom Colors button. The user can click this button to display the extended version. You can direct the Color dialog box to always display this extension by setting the CC_FULLOPEN flag in the Flags member of the CHOOSECOLOR structure. To prevent the user from creating custom colors, you can set the CC_PREVENTFULLOPEN flag to disable the Define Custom Colors button.

The basic colors represent a selection of the colors available on the specified device. The actual number of colors displayed is determined by the display driver. For example, a VGA driver displays 48 colors, and a monochrome display driver displays only 16.

The custom colors are those that you specify or that the user creates. When you create a Color dialog box, you must use the lpCustColors member of the CHOOSECOLOR structure to specify the initial values for the 16 custom colors. If the extended version of the Color dialog box is open, the user can create a custom color by one the following methods:

• Moving the cursor in the color spectrum control and the luminosity slide control
• Typing RGB values in the Red, Green, and Blue edit controls
• Typing hue, saturation, luminosity (HSL) values in the Hue, Sat, and Lum edit controls

To add a new custom color to the custom colors display, the user can click the Add to Custom Colors button. This also causes the dialog box to copy the RGB value of the new color to the corresponding element in the array pointed to by the lpCustColors member. To preserve new custom colors between calls to ChooseColor, you should allocate static memory for the array. For more information about the RGB and HSL color models, see Color Models Used by the Color Dialog Box.

Customizing the Color Dialog Box

To customize a Color dialog box, you can use any of the following methods:

• Specify values in the CHOOSECOLOR structure when you create the dialog box
• Provide a custom template
• Provide a hook procedure

You can modify the appearance and behavior of the Color dialog box by setting flags in the Flags member of the CHOOSECOLOR structure. For example, you can set the CC_SOLIDCOLOR flag to direct the dialog box to display only solid colors. To cause the dialog box to initially select a color other than black, set the CC_RGBINIT flag and specify a color in the rgbResult member.

You can provide a custom template for the Color dialog box, for example, if you want to include additional controls that are unique to your application. The ChooseColor function uses your custom template in place of the default template.

To provide a custom template for the Color dialog box

1. Create the custom template by modifying the default template specified in the Color.dlg file. The control identifiers used in the default Color dialog template are defined in the Color.dlg file.
2. Use the CHOOSECOLOR structure to enable the template as follows:
   • If your custom template is a resource in an application or dynamic link library, set the CC_ENABLETEMPLATE flag in the Flags member. Use the hInstance and lpTemplateName members of the structure to identify the module and resource name.

     -Or-

   • If your custom template is already in memory, set the CC_ENABLETEMPLATEHANDLE flag. Use the hInstance member to identify the memory object that contains the template.

You can provide a CCHookProc hook procedure for the Color dialog box. The hook procedure can process messages sent to the dialog box. It can also use registered messages to control the behavior of the dialog box. If you use a custom template to define additional controls, you must provide a hook procedure to process input for your controls.

To enable a hook procedure for the Color dialog box

1. Set the CC_ENABLEHOOK flag in the Flags member of the CHOOSECOLOR structure.
2. Specify the address of the hook procedure in the lpfnHook member.

After processing its WM_INITDIALOG message, the dialog box procedure sends a WM_INITDIALOG message to the hook procedure. The lParam parameter of this message is a pointer to the CHOOSECOLOR structure used to initialize the dialog box.

The dialog box sends the COLOROKSTRING registered message to the hook procedure when the user clicks the OK button. The hook procedure can reject the selected color and force the dialog box to remain open by returning zero when it receives this message. The hook procedure can force the dialog box to select a particular color by sending the SETRGBSTRING registered message to the dialog box. To use these registered messages, you must pass the COLOROKSTRING and SETRGBSTRING constants to the RegisterWindowMessage function to get a message identifier. You can then use the identifier to detect and process messages sent from the dialog box, or to send messages to the dialog box.

Color Models Used by the Color Dialog Box

The custom colors extension of the Color dialog box allows the user to specify a color using RGB or HSL values. However, the CHOOSECOLOR structure uses only RGB values to report the colors created or selected by the user.

• RGB Color Model
• HSL Color Model
• Converting HSL Values to RGB Values

RGB Color Model

The RGB model is used to designate colors for displays and other devices that emit light. Valid red, green, and blue values range from 0 through 255, with 0 indicating minimum intensity and 255 indicating maximum intensity. The following illustration shows how the primary colors red, green, and blue can be combined to produce four additional colors. (For display devices, the color black results when the red, green, and blue values are set to 0. In display technology, black is the absence of all colors.)

Following are eight colors and their associated RGB values.

The system stores internal colors as 32-bit RGB values that have the following hexadecimal form:

    0x00bbggrr 

The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green; and the third byte contains a value for blue. The high-order byte must be zero.

You can use the RGB macro to get an RGB value based on specified intensities for the red, green, and blue components. Use the GetRValue, GetBValue, and GetGValue macros to extract individual colors from an RGB color value.

HSL Color Model

The Color dialog box provides controls for specifying HSL values. The following illustration shows the color spectrum control and the luminosity slide control that appear in the Color dialog box. The illustration also shows the ranges of values the user can specify with these controls.

In the Color dialog box, the saturation and luminosity values must be in the range 0 through 240, and the hue value must be in the range 0 through 239.

Converting HSL Values to RGB Values

The dialog box procedure provided in Comdlg32.dll for the Color dialog box contains code that converts HSL values to the corresponding RGB values. Following are several colors and their associated HSL and RGB values.

Choosing a Color

This topic describes sample code that displays a Color dialog box so a user can select a color. The sample code first initializes a CHOOSECOLOR structure, and then calls the ChooseColor function to display the dialog box. If the function returns TRUE, indicating that the user selected a color, the sample code uses the selected color to create a new solid brush.

This example uses the CHOOSECOLOR structure to initialize the dialog box as follows:

• Initializes the lpCustColors member with a pointer to a static array of values. The colors in the array are initially black, but the static array preserves custom colors created by the user for subsequent ChooseColor calls.
• Sets the CC_RGBINIT flag and initializes the rgbResult member to specify the color that is initially selected when the dialog box opens. If not specified, the initial selection is black. The example uses the rgbCurrent static variable to preserve the selected value between calls to ChooseColor.
• Sets the CC_FULLOPEN flag so the custom colors extension of the dialog box is always displayed.

CHOOSECOLOR cc;                 // common dialog box structure 
static COLORREF acrCustClr[16]; // array of custom colors 
HWND hwnd;                      // owner window
HBRUSH hbrush;                  // brush handle
static DWORD rgbCurrent;        // initial color selection

// Initialize CHOOSECOLOR 
ZeroMemory(&cc, sizeof(cc));
cc.lStructSize = sizeof(cc);
cc.hwndOwner = hwnd;
cc.lpCustColors = (LPDWORD) acrCustClr;
cc.rgbResult = rgbCurrent;
cc.Flags = CC_FULLOPEN | CC_RGBINIT;
 
if (ChooseColor(&cc)==TRUE) {
    hbrush = CreateSolidBrush(cc.rgbResult);
    rgbCurrent = cc.rgbResult; 
}