| title | ms.custom | ms.date | ms.reviewer | ms.suite | ms.technology | ms.tgt_pltfrm | ms.topic | f1_keywords | dev_langs | helpviewer_keywords | ms.assetid | caps.latest.revision | author | ms.author | manager | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
CColorDialog Class | Microsoft Docs |
11/04/2016 |
|
reference |
|
|
|
d013dc25-9290-4b5d-a97e-95ad7208e13b |
25 |
mikeblome |
mblome |
ghogen |
Allows you to incorporate a color-selection dialog box into your application.
class CColorDialog : public CCommonDialog
| Name | Description |
|---|---|
| CColorDialog::CColorDialog | Constructs a CColorDialog object. |
| 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. |
| Name | Description |
|---|---|
| CColorDialog::OnColorOK | Override to validate the color entered into the dialog box. |
| Name | Description |
|---|---|
| CColorDialog::m_cc | A structure used to customize the settings of the dialog box. |
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
CColorDialog
Header: afxdlgs.h
Constructs a CColorDialog object.
CColorDialog(
COLORREF clrInit = 0,
DWORD dwFlags = 0,
CWnd* pParentWnd = NULL);
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.
[!code-cppNVC_MFCDocView#49]
Call this function to display the Windows common color dialog box and allow the user to select a color.
virtual INT_PTR DoModal();
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.
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.
See the example for CColorDialog::CColorDialog.
Call this function after calling DoModal to retrieve the information about the color the user selected.
COLORREF GetColor() const;
A COLORREF value that contains the RGB information for the color selected in the color dialog box.
[!code-cppNVC_MFCDocView#50]
CColorDialog objects permit the user, in addition to choosing colors, to define up to 16 custom colors.
static COLORREF* PASCAL GetSavedCustomColors();
A pointer to an array of 16 RGB color values that stores custom colors created by the user.
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.
[!code-cppNVC_MFCDocView#51]
A structure of type CHOOSECOLOR, whose members store the characteristics and values of the dialog box.
CHOOSECOLOR m_cc;
After constructing a CColorDialog object, you can use m_cc to set various aspects of the dialog box before calling the DoModal member function.
[!code-cppNVC_MFCDocView#53]
Override to validate the color entered into the dialog box.
virtual BOOL OnColorOK();
Nonzero if the dialog box should not be dismissed; otherwise 0 to accept the color that was entered.
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.
[!code-cppNVC_MFCDocView#52]
Call this function after calling DoModal to force the current color selection to the color value specified in clr.
void SetCurrentColor(COLORREF clr);
clr
An RGB color value.
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.
See the example for CColorDialog::OnColorOK.
MFC Sample MDI
MFC Sample DRAWCLI
CCommonDialog Class
Hierarchy Chart