`CCheckListBox` 类

项目
10/17/2023

提供 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。

如果想处理由列表框发送到其父级（通常是从 CDialog 派生的类）的 Windows 通知消息，请将消息映射条目和消息处理程序成员函数添加到每个消息的父类。

每个消息映射条目采用以下格式：

ON_Notification （id， memberFxn ）

其中 id 指定发送通知的控件的子窗口 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
指定清单框的控件 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

请分两步构造 CCheckListBox 对象。首先定义派生自 CcheckListBox 的类，然后调用 Create，这将初始化 Windows 清单框并将其附加到 CCheckListBox。请参阅 CCheckListBox::CCheckListBox 了解示例。

Create 执行时，Windows 会将 WM_NCCREATE、WM_CREATE、WM_NCCALCSIZE 和 WM_GETMINMAXINFO 消息发送到清单框控件。

默认情况下，这些消息由 CWnd 基类中的 OnNcCreate、OnCreate、OnNcCalcSize 和 OnGetMinMaxInfo 成员函数处理。若要扩展默认消息处理，请将消息映射添加到派生类，并替代前面的消息处理程序成员函数。例如，重写 OnCreate 以为新类执行所需的初始化。

将以下窗口样式应用于清单框控件：

WS_CHILD：始终
WS_VISIBLE：通常
WS_DISABLED 很少
WS_VSCROLL 添加垂直滚动条
WS_HSCROLL 添加水平滚动条
WS_GROUP 对控件进行分组
WS_TABSTOP 允许按 Tab 键导航到此控件

`CCheckListBox::DrawItem`

当所有者绘制清单框的可视方面发生变化时由框架调用。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

参数

lpDrawItemStruct
指向 DRAWITEMSTRUCT 结构的长指针，其中包含有关所需绘图类型的信息。

备注

DRAWITEMSTRUCT 结构的 itemAction 和 itemState 成员定义要执行的绘图操作。

默认情况下，此函数绘制一个默认复选框列表，其中包含一个字符串列表，每个字符串左侧都有一个采用默认大小的复选框。复选框列表大小是 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
列表框中包含的复选框的从零开始的索引。

返回值

指定复选框的状态。下表列出了可能的值。

值	说明
`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 参数可能的值。

值	说明
`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

参数

注解