`CCheckListBox` 類別

發行項
07/05/2024

提供 Windows 檢查清單方塊的功能。

語法

class CCheckListBox : public CListBox

成員

公用建構函式

名稱	描述
`CCheckListBox::CCheckListBox`	建構 `CCheckListBox` 物件。

公用方法

名稱	描述
`CCheckListBox::Create`	建立 Windows 檢查清單方塊，並將它附加至 `CCheckListBox` 物件。
`CCheckListBox::DrawItem`	當擁有者繪製清單框的視覺層面變更時，由架構呼叫。
`CCheckListBox::Enable`	啟用或停用檢查清單方塊專案。
`CCheckListBox::GetCheck`	取得項目複選框的狀態。
`CCheckListBox::GetCheckStyle`	取得控件複選框的樣式。
`CCheckListBox::IsEnabled`	判斷是否啟用專案。
`CCheckListBox::MeasureItem`	建立具有擁有者繪製樣式的清單框時，由架構呼叫。
`CCheckListBox::OnGetCheckPosition`	由架構呼叫以取得專案複選框的位置。
`CCheckListBox::SetCheck`	設定項目複選框的狀態。
`CCheckListBox::SetCheckStyle`	設定控件複選框的樣式。

備註

[檢查清單] 方塊會顯示項目清單，例如檔名。清單中的每個專案旁邊都有一個複選框，用戶可以加以檢查或清除。

CCheckListBox 僅適用於擁有者繪製的控件，因為清單包含的文字字串多。最簡單的是，檢查清單方塊包含文字字串和複選框，但您完全不需要有文字。例如，您可以在每個項目旁邊有一個複選框的小位圖清單。

若要建立您自己的檢查清單方塊，您必須從 CCheckListBox衍生自己的類別。若要衍生您自己的類別，請撰寫衍生類別的建構函式，然後呼叫 Create。

如果您想要處理清單框傳送至其父系的 Windows 通知訊息（通常是衍生自 CDialog的類別），請將訊息對應專案和訊息處理程式成員函式新增至每個訊息的父類別。

每個訊息對應項目採用下列格式：

ON_Notification （ id， memberFxn ）

其中 id 指定傳送通知之控件的子視窗標識碼，而 memberFxn 是您寫入以處理通知的父成員函式名稱。

父系的函式原型如下所示：

afx_msg void memberFxn();

只有一個特別 CCheckListBox 相關的訊息對應專案（但另請參閱的 CListBox訊息對應專案）：

ON_CLBN_CHKCHANGE 用戶已變更項目複選框的狀態。

如果您的檢查清單方塊是預設的檢查清單方塊（每個清單左邊有預設大小的複選框的字串清單），您可以使用預設值 CCheckListBox::DrawItem 來繪製檢查清單方塊。否則，您必須覆寫函 CListBox::CompareItem 式和和 CCheckListBox::DrawItem CCheckListBox::MeasureItem 函式。

您可以從對話框範本或直接在程式碼中建立檢查清單方塊。

繼承階層架構

CCheckListBox

需求

標頭： afxwin.h

`CCheckListBox::CCheckListBox`

建構 CCheckListBox 物件。

CCheckListBox();

備註

您會在兩個步驟中建構 CCheckListBox 物件。首先定義衍生自 CCheckListBox的類別，然後呼叫 Create，以初始化 Windows 檢查清單方塊並將它附加至 CCheckListBox 物件。

範例

CCheckListBox myCheckListBox;
myCheckListBox.Create(LBS_HASSTRINGS | LBS_OWNERDRAWFIXED,
                      CRect(10, 10, 100, 100), this, IDC_MYCHECKLISTBOX);

`CCheckListBox::Create`

建立 Windows 檢查清單方塊，並將它附加至 CCheckListBox 物件。

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

參數

dwStyle
指定檢查清單方塊的樣式。樣式必須是 LBS_HASSTRINGS 和 LBS_OWNERDRAWFIXED （清單中的所有專案高度相同）或 LBS_OWNERDRAWVARIABLE （清單中的專案是不同高度的專案）。此樣式可以與其他清單框樣式結合，但除外 LBS_USETABSTOPS。

rect
指定檢查清單方塊的大小和位置。可以是 CRect 對象或 RECT 結構。

pParentWnd
指定檢查清單方塊的父視窗（通常是 CDialog 物件）。它不得為 NULL。

nID
指定檢查清單方塊的控件識別碼。

傳回值

如果成功則為非零；否則為 0。

備註

您會在兩個步驟中建構 CCheckListBox 物件。首先，定義衍生自 CcheckListBox 的類別，然後呼叫 Create，以初始化 Windows 檢查清單方塊，並將它附加至 CCheckListBox。如需範例，請參閱 CCheckListBox::CCheckListBox 。

執行時 Create ，Windows 會將 WM_NCCREATE、 WM_CREATE、 WM_NCCALCSIZE和 WM_GETMINMAXINFO 訊息傳送至檢查清單框控件。

基類中的 CWnd 、 OnNcCalcSizeOnCreate和 OnGetMinMaxInfo 成員函式預設OnNcCreate會處理這些訊息。若要擴充預設訊息處理，請將訊息對應新增至衍生類別，並覆寫上述訊息處理程式成員函式。例如，覆寫 OnCreate，以執行新類別所需的初始化。

將下列視窗樣式套用至檢查清單框控制項：

WS_CHILD 總是
WS_VISIBLE 通常
WS_DISABLED 很少
WS_VSCROLL 若要新增垂直滾動條
WS_HSCROLL 若要新增水準滾動條
WS_GROUP 將控件分組
WS_TABSTOP 允許索引標籤至此控制件

`CCheckListBox::DrawItem`

當擁有者繪製檢查清單方塊的視覺層面變更時，由架構呼叫。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

參數

lpDrawItemStruct
結構的長指標 DRAWITEMSTRUCT ，其中包含所需繪圖類型的相關信息。

備註

結構的 itemAction 和 itemState 成員 DRAWITEMSTRUCT 會定義要執行的繪圖動作。

根據預設，此函式會繪製預設複選框清單，其中包含每個字串清單，左邊都有預設大小的複選框。選取框清單大小是中指定的 Create。

覆寫此成員函式來實作非預設值的擁有者繪製檢查清單方塊，例如具有非字串清單的檢查清單方塊、具有變數高度專案，或具有不在左邊的複選框。應用程式應該在終止此成員函式之前，還原針對所提供 lpDrawItemStruct 顯示內容選取的所有圖形裝置介面（GDI）物件。

如果檢查清單方塊專案的高度不相同，檢查清單方塊樣式（在 Create中指定）必須是 LBS_OWNERVARIABLE，而且您必須覆寫函 MeasureItem 式。

`CCheckListBox::Enable`

呼叫此函式以啟用或停用檢查清單方塊專案。

void Enable(
    int nIndex,
    BOOL bEnabled = TRUE);

參數

nIndex
要啟用的檢查清單方塊專案的索引。

bEnabled
指定專案是啟用還是停用。

`CCheckListBox::GetCheck`

擷取指定複選框的狀態。

int GetCheck(int nIndex);

參數

nIndex
清單框中包含之複選框的以零起始的索引。

傳回值

指定複選框的狀態。下表列出可能的值。

值	Description
`BST_CHECKED`	核取複選框。
`BST_UNCHECKED`	未核取此複選框。
`BST_INDETERMINATE`	複選框狀態不確定。

`CCheckListBox::GetCheckStyle`

呼叫此函式以取得檢查清單方塊的樣式。

UINT GetCheckStyle();

傳回值

控件複選框的樣式。

備註

如需可能樣式的資訊，請參閱 SetCheckStyle。

`CCheckListBox::IsEnabled`

呼叫此函式以判斷專案是否已啟用。

BOOL IsEnabled(int nIndex);

參數

nIndex
專案的索引。

傳回值

如果專案已啟用，則為非零;否則為 0。

`CCheckListBox::MeasureItem`

建立具有非預設樣式的檢查清單方塊時，由架構呼叫。

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

參數

lpMeasureItemStruct
結構的長指標 MEASUREITEMSTRUCT 。

備註

根據預設，此成員函式不會執行任何動作。覆寫此成員函式並 MEASUREITEMSTRUCT 填入結構，以通知 Windows 檢查清單方塊項目的維度。如果以樣式建立 LBS_OWNERDRAWVARIABLE 檢查清單方塊，架構會針對清單框中的每個專案呼叫這個成員函式。否則，這個成員只會呼叫一次。

`CCheckListBox::OnGetCheckPosition`

架構會呼叫此函式，以取得專案中複選框的位置和大小。

virtual CRect OnGetCheckPosition(
    CRect rectItem,
    CRect rectCheckBox);

參數

rectItem
清單專案的位置和大小。

rectCheckBox
項目複選框的預設位置和大小。

傳回值

項目複選框的位置和大小。

備註

默認實作只會傳回復選框的預設位置和大小（rectCheckBox）。根據預設，複選框會對齊專案左上角，而且是標準複選框大小。在某些情況下，您想要右側的複選框，或想要較大的或較小的複選框。在這些情況下，請覆寫 OnGetCheckPosition 以變更專案內的複選框位置和大小。

`CCheckListBox::SetCheck`

設定指定複選框的狀態。

void SetCheck(
    int nIndex,
    int nCheck);

參數

nIndex
清單框中包含之複選框的以零起始的索引。

nCheck
指定複選框的按鈕狀態。如需可能的值，請參閱一節。

備註

下表列出參數的 nCheck 可能值。

值	Description
`BST_CHECKED`	選取指定的複選框。
`BST_UNCHECKED`	清除指定的複選框。
`BST_INDETERMINATE`	將指定的複選框狀態設定為不確定。只有在複選框樣式為 `BS_AUTO3STATE` 或 `BS_3STATE`時，才能使用此狀態。如需詳細資訊，請參閱按鈕樣式。

`CCheckListBox::SetCheckStyle`

呼叫此函式以在檢查清單方塊中設定複選框的樣式。

void SetCheckStyle(UINT nStyle);

參數

nStyle
決定檢查清單方塊中的複選框樣式。

備註

有效的樣式如下：

BS_CHECKBOX
BS_AUTOCHECKBOX
BS_AUTO3STATE
BS_3STATE

如需這些樣式的相關信息，請參閱按鈕樣式。

另請參閱

MFC 範例 TSTCON
CListBox 類
 階層架構圖表

共用方式為

CCheckListBox 類別

語法

成員

公用建構函式

公用方法

備註

繼承階層架構

需求

CCheckListBox::CCheckListBox

備註

範例

CCheckListBox::Create

參數

傳回值

備註

CCheckListBox::DrawItem

參數

備註

CCheckListBox::Enable

參數

CCheckListBox::GetCheck

參數

傳回值

CCheckListBox::GetCheckStyle

傳回值

備註

CCheckListBox::IsEnabled

參數

傳回值

CCheckListBox::MeasureItem

參數

備註

CCheckListBox::OnGetCheckPosition

參數

傳回值

備註

CCheckListBox::SetCheck

參數

備註

CCheckListBox::SetCheckStyle

參數

備註