CColorDialog 类

项目
10/17/2023

允许将颜色选择对话框合并到应用程序。

语法

class CColorDialog : public CCommonDialog

成员

公共构造函数

名称	描述
CColorDialog::CColorDialog	构造 `CColorDialog` 对象。

公共方法

名称	描述
CColorDialog::DoModal	显示颜色对话框并允许用户做出选择。
CColorDialog::GetColor	返回包含所选颜色的值的 `COLORREF` 结构。
CColorDialog::GetSavedCustomColors	检索用户创建的自定义颜色。
CColorDialog::SetCurrentColor	将当前颜色选择强制为指定的颜色。

受保护方法

名称	描述
CColorDialog::OnColorOK	重写以验证对话框中输入的颜色。

公共数据成员

“属性”	描述
CColorDialog::m_cc	用于自定义对话框设置的结构。

注解

CColorDialog 对象是一个对话框，其中包含针对显示系统定义的颜色列表。用户可以从列表中选择或创建特定颜色，然后在对话框退出时将此颜色报告给应用程序。

若要构造 CColorDialog 对象，请使用提供的构造函数或派生新类，并使用你自己的自定义构造函数。

构造对话框后，可以设置或修改 m_cc 结构中的任何值来初始化对话框的控件的值。 m_cc 结构的类型为 CHOOSECOLOR。

初始化对话框的控件后，调用 DoModal 成员函数以显示对话框，并允许用户选择颜色。 DoModal 返回用户在对话框中选择“确定”(IDOK) 或“取消”(IDCANCEL) 按钮的操作。

如果 DoModal 返回 IDOK，可使用 CColorDialog 的成员函数之一来检索用户输入的信息。

可以使用 Windows CommDlgExtendedError 函数来确定对话框初始化期间是否发生了错误，并了解有关错误的详细信息。

CColorDialog 依赖于 Windows 3.1 和更高版本随附的 COMMDLG.DLL 文件。

若要自定义对话框，请从 CColorDialog 派生类，提供自定义对话框模板，并添加消息映射以处理来自扩展控件的通知消息。任何未处理的消息都应传递给基类。

不需要自定义挂钩函数。

注意

在某些安装中，如果你使用框架来使其他 CDialog 对象变成灰色，则 CColorDialog 对象不会以灰色背景显示。

有关如何使用 CColorDialog 的详细信息，请参阅通用对话框类

继承层次结构

CColorDialog

要求

标头：afxdlgs.h

CColorDialog::CColorDialog

构造 CColorDialog 对象。

CColorDialog(
    COLORREF clrInit = 0,
    DWORD dwFlags = 0,
    CWnd* pParentWnd = NULL);

参数

clrInit
默认颜色选择。如果未指定任何值，则默认值为 RGB(0,0,0)（黑色）。

dwFlags
一组标志，用于自定义对话框的功能和外观。有关详细信息，请参阅 Windows SDK 中的 CHOOSECOLOR 结构。

pParentWnd
指向对话框的父窗口或所有者窗口的指针。

示例

// 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

调用此函数可显示 Windows 通用颜色对话框并允许用户选择颜色。

virtual INT_PTR DoModal();

返回值

IDOK 或 IDCANCEL。如果返回 IDCANCEL，请调用 Windows CommDlgExtendedError 函数以确定是否发生了错误。

IDOK 和 IDCANCEL 是常量，指示用户选择的是“确定”还是“取消”按钮。

备注

如果你要通过设置 m_cc 结构的成员来初始化各种颜色对话框选项，则应在调用 DoModal 之前但在构造对话框对象之后执行此操作。

在调用 DoModal 之后，可以调用其他成员函数来检索用户在对话框中输入的设置或信息。

示例

请参阅 CColorDialog::CColorDialog 的示例。

CColorDialog::GetColor

在调用 DoModal 后调用此函数可以检索有关用户选择的颜色的信息。

COLORREF GetColor() const;

返回值

一个 COLORREF 值，该值包含颜色对话框中所选颜色的 RGB 信息。

示例

// 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 对象除了允许用户选择颜色外，还允许定义最多 16 种自定义颜色。

static COLORREF* PASCAL GetSavedCustomColors();

返回值

指向由 16 个 RGB 颜色值构成的数组的指针，该数组存储用户创建的自定义颜色。

注解

GetSavedCustomColors 成员函数提供对这些颜色的访问。在 DoModal 返回 IDOK 后可以检索这些颜色。

返回的数组中 16 个“RGB”值的每一个将初始化为 RGB(255,255,255)（白色）。用户选择的自定义颜色仅在应用程序内的对话框调用之间保存。如果你希望在应用程序的调用之间保存这些颜色，则必须以其他某种方式保存，例如在初始化 (.INI) 文件中保存。

示例

// 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

CHOOSECOLOR 类型的结构，其成员存储对话框的特征和值。

CHOOSECOLOR m_cc;

备注

构造 CColorDialog 对象后，可以在调用 DoModal 成员函数之前使用 m_cc 来设置对话框的各个方面。

示例

// 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

重写以验证对话框中输入的颜色。

virtual BOOL OnColorOK();

返回值

如果不应关闭对话框，则返回非零值；否则返回 0 以接受输入的颜色。

备注

仅当你要针对用户在颜色对话框中选择的颜色提供自定义验证时，才重写此函数。

用户可通过以下两种方法之一选择颜色：

单击调色板上的颜色。然后，所选颜色的“RGB”值会反映在相应的 RGB 编辑框中。
在 RGB 编辑框中输入值

重写 OnColorOK 可以出于任何特定于应用程序的原因而拒绝用户在通用颜色对话框中输入的颜色。

通常无需使用此函数，因为框架会提供对颜色的默认验证，并会在输入无效颜色时显示消息框。

可以从 OnColorOK 内部调用 SetCurrentColor 来强制进行颜色选择。触发 OnColorOK（即用户单击“确定”接受颜色更改）后，可以调用 GetColor 来获取新颜色的“RGB”值。

示例

// 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

在调用 DoModal 后调用此函数可将当前颜色选择强制为 clr 中指定的颜色值。

void SetCurrentColor(COLORREF clr);

参数

clr
RGB 颜色值。

备注

从消息处理程序或 OnColorOK 内部调用此函数。对话框将根据 clr 参数的值自动更新用户的选择。

示例

请参阅 CColorDialog::OnColorOK 的示例。

另请参阅

MFC 示例 MDI
MFC 示例 DRAWCLI
CCommonDialog 类
 层次结构图

通过