แก้ไข

แชร์ผ่าน

CCheckListBox Class

  • บทความ

Provides the functionality of a Windows checklist box.

Syntax

class CCheckListBox : public CListBox

Members

Public Constructors

Name Description
CCheckListBox::CCheckListBox Constructs a CCheckListBox object.

Public Methods

Name Description
CCheckListBox::Create Creates the Windows checklist box and attaches it to the CCheckListBox object.
CCheckListBox::DrawItem Called by the framework when a visual aspect of an owner-draw list box changes.
CCheckListBox::Enable Enables or disables a checklist box item.
CCheckListBox::GetCheck Gets the state of an item's check box.
CCheckListBox::GetCheckStyle Gets the style of the control's check boxes.
CCheckListBox::IsEnabled Determines whether an item is enabled.
CCheckListBox::MeasureItem Called by the framework when a list box with an owner-draw style is created.
CCheckListBox::OnGetCheckPosition Called by the framework to get the position of an item's check box.
CCheckListBox::SetCheck Sets the state of an item's check box.
CCheckListBox::SetCheckStyle Sets the style of the control's check boxes.

Remarks

A "checklist box" displays a list of items, such as filenames. Each item in the list has a check box next to it that the user can check or clear.

CCheckListBox is only for owner-drawn controls because the list contains more than text strings. At its simplest, a checklist box contains text strings and check boxes, but you don't need to have text at all. For example, you could have a list of small bitmaps with a check box next to each item.

To create your own checklist box, you must derive your own class from CCheckListBox. To derive your own class, write a constructor for the derived class, then call Create.

If you want to handle Windows notification messages sent by a list box to its parent (usually a class derived from CDialog), add a message-map entry and message-handler member function to the parent class for each message.

Each message-map entry takes the following form:

ON_Notification ( id, memberFxn )

where id specifies the child window ID of the control sending the notification and memberFxn is the name of the parent member function you've written to handle the notification.

The parent's function prototype is as follows:

afx_msg void memberFxn();

There's only one message-map entry that pertains specifically to CCheckListBox (but see also the message-map entries for CListBox):

  • ON_CLBN_CHKCHANGE The user has changed the state of an item's checkbox.

If your checklist box is a default checklist box (a list of strings with the default-sized checkboxes to the left of each), you can use the default CCheckListBox::DrawItem to draw the checklist box. Otherwise, you must override the CListBox::CompareItem function and the CCheckListBox::DrawItem and CCheckListBox::MeasureItem functions.

You can create a checklist box either from a dialog template or directly in your code.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CListBox

CCheckListBox

Requirements

Header: afxwin.h

CCheckListBox::CCheckListBox

Constructs a CCheckListBox object.

CCheckListBox();

Remarks

You construct a CCheckListBox object in two steps. First define a class derived from CCheckListBox, then call Create, which initializes the Windows checklist box and attaches it to the CCheckListBox object.

Example

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

CCheckListBox::Create

Creates the Windows checklist box and attaches it to the CCheckListBox object.

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

Parameters

dwStyle
Specifies the style of the checklist box. The style must be LBS_HASSTRINGS and either LBS_OWNERDRAWFIXED (all items in the list are the same height) or LBS_OWNERDRAWVARIABLE (items in the list are of varying heights). This style can be combined with other list-box styles except LBS_USETABSTOPS.

rect
Specifies the checklist-box size and position. Can be either a CRect object or a RECT structure.

pParentWnd
Specifies the checklist box's parent window (usually a CDialog object). It must not be NULL.

nID
Specifies the checklist box's control ID.

Return Value

Nonzero if successful; otherwise 0.

Remarks

You construct a CCheckListBox object in two steps. First, define a class derived from CcheckListBox and then call Create, which initializes the Windows checklist box and attaches it to the CCheckListBox. See CCheckListBox::CCheckListBox for a sample.

When Create executes, Windows sends the WM_NCCREATE, WM_CREATE, WM_NCCALCSIZE, and WM_GETMINMAXINFO messages to the checklist-box control.

These messages are handled by default by the OnNcCreate, OnCreate, OnNcCalcSize, and OnGetMinMaxInfo member functions in the CWnd base class. To extend the default message handling, add a message map to the derived class and override the preceding message-handler member functions. Override OnCreate, for example, to perform needed initialization for a new class.

Apply the following window styles to a checklist-box control:

  • WS_CHILD Always

  • WS_VISIBLE Usually

  • WS_DISABLED Rarely

  • WS_VSCROLL To add a vertical scroll bar

  • WS_HSCROLL To add a horizontal scroll bar

  • WS_GROUP To group controls

  • WS_TABSTOP To allow tabbing to this control

CCheckListBox::DrawItem

Called by the framework when a visual aspect of an owner-drawn checklist box changes.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parameters

lpDrawItemStruct
A long pointer to a DRAWITEMSTRUCT structure that contains information about the type of drawing required.

Remarks

The itemAction and itemState members of the DRAWITEMSTRUCT structure define the drawing action that is to be performed.

By default, this function draws a default checkbox list, consisting of a list of strings each with a default-sized checkbox to the left. The checkbox list size is the one specified in Create.

Override this member function to implement drawing of owner-draw checklist boxes that aren't the default, such as checklist boxes with lists that aren't strings, with variable-height items, or with checkboxes that aren't on the left. The application should restore all graphics device interface (GDI) objects selected for the display context supplied in lpDrawItemStruct before the termination of this member function.

If checklist box items aren't all the same height, the checklist box style (specified in Create) must be LBS_OWNERVARIABLE, and you must override the MeasureItem function.

CCheckListBox::Enable

Call this function to enable or disable a checklist box item.

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

Parameters

nIndex
Index of the checklist box item to be enabled.

bEnabled
Specifies whether the item is enabled or disabled.

CCheckListBox::GetCheck

Retrieves the state of the specified check box.

int GetCheck(int nIndex);

Parameters

nIndex
Zero-based index of a check box that is contained in the list box.

Return Value

The state of the specified check box. The following table lists possible values.

Value Description
BST_CHECKED The check box is checked.
BST_UNCHECKED The check box isn't checked.
BST_INDETERMINATE The check box state is indeterminate.

CCheckListBox::GetCheckStyle

Call this function to get the checklist box's style.

UINT GetCheckStyle();

Return Value

The style of the control's check boxes.

Remarks

For information on possible styles, see SetCheckStyle.

CCheckListBox::IsEnabled

Call this function to determine whether an item is enabled.

BOOL IsEnabled(int nIndex);

Parameters

nIndex
Index of the item.

Return Value

Nonzero if the item is enabled; otherwise 0.

CCheckListBox::MeasureItem

Called by the framework when a checklist box with a nondefault style is created.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Parameters

lpMeasureItemStruct
A long pointer to a MEASUREITEMSTRUCT structure.

Remarks

By default, this member function does nothing. Override this member function and fill in the MEASUREITEMSTRUCT structure to inform Windows of the dimensions of checklist-box items. If the checklist box is created with the LBS_OWNERDRAWVARIABLE style, the framework calls this member function for each item in the list box. Otherwise, this member is called only once.

CCheckListBox::OnGetCheckPosition

The framework calls this function to get the position and size of the check box in an item.

virtual CRect OnGetCheckPosition(
    CRect rectItem,
    CRect rectCheckBox);

Parameters

rectItem
The position and size of the list item.

rectCheckBox
The default position and size of an item's check box.

Return Value

The position and size of an item's check box.

Remarks

The default implementation only returns the default position and size of the check box (rectCheckBox). By default, a check box is aligned in the upper-left corner of an item and is the standard check box size. There may be cases where you want the check boxes on the right, or want a larger or smaller check box. In these cases, override OnGetCheckPosition to change the check box position and size within the item.

CCheckListBox::SetCheck

Sets the state of the specified check box.

void SetCheck(
    int nIndex,
    int nCheck);

Parameters

nIndex
Zero-based index of a check box that is contained in the list box.

nCheck
The button state for the specified check box. See the Remarks section for possible values.

Remarks

The following table lists possible values for the nCheck parameter.

Value Description
BST_CHECKED Select the specified check box.
BST_UNCHECKED Clear the specified check box.
BST_INDETERMINATE Set the specified check box state to indeterminate.

This state is only available if the check box style is BS_AUTO3STATE or BS_3STATE. For more information, see Button Styles.

CCheckListBox::SetCheckStyle

Call this function to set the style of check boxes in the checklist box.

void SetCheckStyle(UINT nStyle);

Parameters

nStyle
Determines the style of check boxes in the checklist box.

Remarks

Valid styles are:

  • BS_CHECKBOX

  • BS_AUTOCHECKBOX

  • BS_AUTO3STATE

  • BS_3STATE

For information on these styles, see Button Styles.

See also

MFC Sample TSTCON
CListBox Class
Hierarchy Chart