CColorDialog Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CColorDialog Class.
Allows you to incorporate a color-selection dialog box into your application.
Syntax
class CColorDialog : public CCommonDialog
Members
Public Constructors
| Name | Description |
|---|---|
| CColorDialog::CColorDialog | Constructs a CColorDialog object. |
Public Methods
| Name | Description |
|---|---|
| CColorDialog::DoModal | Displays a color dialog box and allows the user to make a selection. |
| CColorDialog::GetColor | Returns a COLORREF structure containing the values of the selected color. |
| CColorDialog::GetSavedCustomColors | Retrieves custom colors created by the user. |
| CColorDialog::SetCurrentColor | Forces the current color selection to the specified color. |
Protected Methods
| Name | Description |
|---|---|
| CColorDialog::OnColorOK | Override to validate the color entered into the dialog box. |
Public Data Members
| Name | Description |
|---|---|
| CColorDialog::m_cc | A structure used to customize the settings of the dialog box. |
Remarks
A CColorDialog object is a dialog box with a list of colors that are defined for the display system. The user can select or create a particular color from the list, which is then reported back to the application when the dialog box exits.
To construct a CColorDialog object, use the provided constructor or derive a new class and use your own custom constructor.
Once the dialog box has been constructed, you can set or modify any values in the m_cc structure to initialize the values of the dialog box's controls. The m_cc structure is of type CHOOSECOLOR.
After initializing the dialog box's controls, call the DoModal member function to display the dialog box and allow the user to select a color. DoModal returns the user's selection of either the dialog box's OK ( IDOK) or Cancel ( IDCANCEL) button.
If DoModal returns IDOK, you can use one of CColorDialog's member functions to retrieve the information input by the user.
You can use the Windows CommDlgExtendedError function to determine whether an error occurred during initialization of the dialog box and to learn more about the error.
CColorDialog relies on the COMMDLG.DLL file that ships with Windows versions 3.1 and later.
To customize the dialog box, derive a class from CColorDialog, provide a custom dialog template, and add a message map to process the notification messages from the extended controls. Any unprocessed messages should be passed to the base class.
Customizing the hook function is not required.
Note
On some installations the CColorDialog object will not display with a gray background if you have used the framework to make other CDialog objects gray.
For more information on using CColorDialog, see Common Dialog Classes
Inheritance Hierarchy
CColorDialog
Requirements
Header: afxdlgs.h
CColorDialog::CColorDialog
Constructs a CColorDialog object.
CColorDialog(
COLORREF clrInit = 0,
DWORD dwFlags = 0,
CWnd* pParentWnd = NULL);
Parameters
clrInit
The default color selection. If no value is specified, the default is RGB(0,0,0) (black).
dwFlags
A set of flags that customize the function and appearance of the dialog box. For more information, see the CHOOSECOLOR structure in the Windows SDK.
pParentWnd
A pointer to the dialog box's parent or owner window.
Example
// Show the Color dialog with all the default settings.
CColorDialog dlg1;
dlg1.DoModal();
// Show the fully opened Color dialog with red as the selected color.
CColorDialog dlg2(RGB(255, 0, 0), CC_FULLOPEN);
dlg2.DoModal();
CColorDialog::DoModal
Call this function to display the Windows common color dialog box and allow the user to select a color.
virtual INT_PTR DoModal();
Return Value
IDOK or IDCANCEL. If IDCANCEL is returned, call the Windows CommDlgExtendedError function to determine whether an error occurred.
IDOK and IDCANCEL are constants that indicate whether the user selected the OK or Cancel button.
Remarks
If you want to initialize the various color dialog-box options by setting members of the m_cc structure, you should do this before calling DoModal but after the dialog-box object is constructed.
After calling DoModal, you can call other member functions to retrieve the settings or information input by the user into the dialog box.
Example
See the example for CColorDialog::CColorDialog.
CColorDialog::GetColor
Call this function after calling DoModal to retrieve the information about the color the user selected.
COLORREF GetColor() const;
Return Value
A COLORREF value that contains the RGB information for the color selected in the color dialog box.
Example
// Get the selected color from the CColorDialog.
CColorDialog dlg;
if (dlg.DoModal() == IDOK)
{
COLORREF color = dlg.GetColor();
TRACE(_T("RGB value of the selected color - red = %u, ")
_T("green = %u, blue = %u\n"),
GetRValue(color), GetGValue(color), GetBValue(color));
}
CColorDialog::GetSavedCustomColors
CColorDialog objects permit the user, in addition to choosing colors, to define up to 16 custom colors.
static COLORREF* PASCAL GetSavedCustomColors();
Return Value
A pointer to an array of 16 RGB color values that stores custom colors created by the user.
Remarks
The GetSavedCustomColors member function provides access to these colors. These colors can be retrieved after DoModal returns IDOK.
Each of the 16 RGB values in the returned array is initialized to RGB(255,255,255) (white). The custom colors chosen by the user are saved only between dialog box invocations within the application. If you wish to save these colors between invocations of the application, you must save them in some other manner, such as in an initialization (.INI) file.
Example
// Get a pointer to an array of 16 RGB color values that stores
// custom colors created by the user from CColorDialog.
CColorDialog dlg;
if (dlg.DoModal() == IDOK)
{
COLORREF* ccolor = dlg.GetSavedCustomColors();
for (int i=0; i < 16; i++)
{
TRACE(_T("RGB value of the selected color - red = %u, ")
_T("green = %u, blue = %u\n"),
GetRValue(ccolor[i]),
GetGValue(ccolor[i]),
GetBValue(ccolor[i]));
}
}
CColorDialog::m_cc
A structure of type CHOOSECOLOR, whose members store the characteristics and values of the dialog box.
CHOOSECOLOR m_cc;
Remarks
After constructing a CColorDialog object, you can use m_cc to set various aspects of the dialog box before calling the DoModal member function.
Example
// The code below uses CColorDialog::m_cc data member to
// customize the settings of CColorDialog. The CColorDialog will
// be shown as full open and with red as the selected color.
CColorDialog dlg;
dlg.m_cc.Flags |= CC_FULLOPEN | CC_RGBINIT;
dlg.m_cc.rgbResult = RGB(255, 0, 0);
dlg.DoModal();
CColorDialog::OnColorOK
Override to validate the color entered into the dialog box.
virtual BOOL OnColorOK();
Return Value
Nonzero if the dialog box should not be dismissed; otherwise 0 to accept the color that was entered.
Remarks
Override this function only if you want to provide custom validation of the color the user selects in the color dialog box.
The user can select a color by one of the following two methods:
Clicking a color on the color palette. The selected color's RGB values are then reflected in the appropriate RGB edit boxes.
Entering values in the RGB edit boxes
Overriding OnColorOK allows you to reject a color the user enters into a common color dialog box for any application-specific reason.
Normally, you do not need to use this function because the framework provides default validation of colors and displays a message box if an invalid color is entered.
You can call SetCurrentColor from within OnColorOK to force a color selection. Once OnColorOK has been fired (that is, the user clicks OK to accept the color change), you can call GetColor to get the RGB value of the new color.
Example
// Override OnColorOK to validate the color entered to the
// Red, Green, and Blue edit controls. If the color
// is BLACK (i.e. RGB(0, 0,0)), then force the current color
// selection to be the color initially selected when the
// dialog box is created. The color dialog won't close so
// user can enter a new color.
BOOL CMyColorDlg::OnColorOK()
{
// Value in Red edit control.
COLORREF clrref = GetColor();
if (RGB(0, 0, 0) == clrref)
{
AfxMessageBox(_T("BLACK is not an acceptable color. ")
_T("Please enter a color again"));
// GetColor() returns initially selected color.
SetCurrentColor(GetColor());
// Won't dismiss color dialog.
return TRUE;
}
// OK to dismiss color dialog.
return FALSE;
}
CColorDialog::SetCurrentColor
Call this function after calling DoModal to force the current color selection to the color value specified in clr.
void SetCurrentColor(COLORREF clr);
Parameters
clr
An RGB color value.
Remarks
This function is called from within a message handler or OnColorOK. The dialog box will automatically update the user's selection based on the value of the clr parameter.
Example
See the example for CColorDialog::OnColorOK.
See Also
MFC Sample MDI
MFC Sample DRAWCLI
CCommonDialog Class
Hierarchy Chart