CColorDialog 類別

發行項
08/04/2024

可讓您將色彩選取對話框併入您的應用程式。

語法

class CColorDialog : public CCommonDialog

成員

公用建構函式

名稱	描述
CColorDialog：：CColorDialog	建構 `CColorDialog` 物件。

公用方法

名稱	描述
CColorDialog：:D oModal	顯示色彩對話框，並允許用戶進行選取。
CColorDialog：：GetColor	傳 `COLORREF` 回結構，其中包含所選取色彩的值。
CColorDialog：：GetSavedCustomColors	擷取使用者所建立的自訂色彩。
CColorDialog：：SetCurrentColor	強制目前的色彩選取範圍設為指定的色彩。

受保護的方法

名稱	描述
CColorDialog：：OnColorOK	覆寫以驗證在對話框中輸入的色彩。

公用資料成員

名稱	描述
CColorDialog：：m_cc	用來自定義對話框設定的結構。

備註

對像是 CColorDialog 一個對話框，其中包含針對顯示系統定義的色彩清單。使用者可以從清單中選取或建立特定色彩，然後在對話框結束時回報回應用程式。

若要建構物件，請使用提供的建 CColorDialog 構函式或衍生新的類別，並使用您自己的自定義建構函式。

建構對話框之後，您可以設定或修改m_cc結構中的任何值，以初始化對話框控件的值。 m_cc結構的類型為 CHOOSECOLOR。

初始化對話框的控件之後，請呼叫 DoModal 成員函式來顯示對話框，並允許用戶選取色彩。 DoModal 會傳回使用者選取對話方塊的 [確定] 或 [取消] 或 [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：:D oModal

呼叫此函式以顯示 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 構物件之後，您可以使用 m_cc 來設定對話框的各個層面，再呼叫 DoModal 成員函式。

範例

// 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 類別
 階層架構圖表

共用方式為