CListBox Class

Article
01/08/2013

Provides the functionality of a Windows list box.

class CListBox : public CWnd

Members

Public Constructors

Name	Description
CListBox::CListBox	Constructs a CListBox object.

Public Methods

Name	Description
CListBox::AddString	Adds a string to a list box.
CListBox::CharToItem	Override to provide custom WM_CHAR handling for owner-draw list boxes which don't have strings.
CListBox::CompareItem	Called by the framework to determine the position of a new item in a sorted owner-draw list box.
CListBox::Create	Creates the Windows list box and attaches it to the CListBox object.
CListBox::DeleteItem	Called by the framework when the user deletes an item from an owner-draw list box.
CListBox::DeleteString	Deletes a string from a list box.
CListBox::Dir	Adds filenames, drives, or both from the current directory to a list box.
CListBox::DrawItem	Called by the framework when a visual aspect of an owner-draw list box changes.
CListBox::FindString	Searches for a string in a list box.
CListBox::FindStringExact	Finds the first list-box string that matches a specified string.
CListBox::GetAnchorIndex	Retrieves the zero-based index of the current anchor item in a list box.
CListBox::GetCaretIndex	Determines the index of the item that has the focus rectangle in a multiple-selection list box.
CListBox::GetCount	Returns the number of strings in a list box.
CListBox::GetCurSel	Returns the zero-based index of the currently selected string in a list box.
CListBox::GetHorizontalExtent	Returns the width in pixels that a list box can be scrolled horizontally.
CListBox::GetItemData	Returns the 32-bit value associated with the list-box item.
CListBox::GetItemDataPtr	Returns a pointer to a list-box item.
CListBox::GetItemHeight	Determines the height of items in a list box.
CListBox::GetItemRect	Returns the bounding rectangle of the list-box item as it is currently displayed.
CListBox::GetListBoxInfo	Retrieves the number of items per column.
CListBox::GetLocale	Retrieves the locale identifier for a list box.
CListBox::GetSel	Returns the selection state of a list-box item.
CListBox::GetSelCount	Returns the number of strings currently selected in a multiple-selection list box.
CListBox::GetSelItems	Returns the indices of the strings currently selected in a list box.
CListBox::GetText	Copies a list-box item into a buffer.
CListBox::GetTextLen	Returns the length in bytes of a list-box item.
CListBox::GetTopIndex	Returns the index of the first visible string in a list box.
CListBox::InitStorage	Preallocates blocks of memory for list box items and strings.
CListBox::InsertString	Inserts a string at a specific location in a list box.
CListBox::ItemFromPoint	Returns the index of the list-box item nearest a point.
CListBox::MeasureItem	Called by the framework when an owner-draw list box is created to determine list-box dimensions.
CListBox::ResetContent	Clears all the entries from a list box.
CListBox::SelectString	Searches for and selects a string in a single-selection list box.
CListBox::SelItemRange	Selects or deselects a range of strings in a multiple-selection list box.
CListBox::SetAnchorIndex	Sets the anchor in a multiple-selection list box to begin an extended selection.
CListBox::SetCaretIndex	Sets the focus rectangle to the item at the specified index in a multiple-selection list box.
CListBox::SetColumnWidth	Sets the column width of a multicolumn list box.
CListBox::SetCurSel	Selects a list-box string.
CListBox::SetHorizontalExtent	Sets the width in pixels that a list box can be scrolled horizontally.
CListBox::SetItemData	Sets the 32-bit value associated with the list-box item.
CListBox::SetItemDataPtr	Sets a pointer to the list-box item.
CListBox::SetItemHeight	Sets the height of items in a list box.
CListBox::SetLocale	Sets the locale identifier for a list box.
CListBox::SetSel	Selects or deselects a list-box item in a multiple-selection list box.
CListBox::SetTabStops	Sets the tab-stop positions in a list box.
CListBox::SetTopIndex	Sets the zero-based index of the first visible string in a list box.
CListBox::VKeyToItem	Override to provide custom WM_KEYDOWN handling for list boxes with the LBS_WANTKEYBOARDINPUT style set.

Remarks

A list box displays a list of items, such as filenames, that the user can view and select.

In a single-selection list box, the user can select only one item. In a multiple-selection list box, a range of items can be selected. When the user selects an item, it is highlighted and the list box sends a notification message to the parent window.

You can create a list box either from a dialog template or directly in your code. To create it directly, construct the CListBox object, then call the Create member function to create the Windows list-box control and attach it to the CListBox object. To use a list box in a dialog template, declare a list-box variable in your dialog box class, then use DDX_Control in your dialog box class's DoDataExchange function to connect the member variable to the control. (this is done for you automatically when you add a control variable to your dialog box class.)

Construction can be a one-step process in a class derived from CListBox. Write a constructor for the derived class and call Create from within the constructor.

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 list-box control sending the notification and memberFxn is the name of the parent member function you have written to handle the notification.

The parent's function prototype is as follows:

afx_msg void memberFxn( );

Following is a list of potential message-map entries and a description of the cases in which they would be sent to the parent:

ON_LBN_DBLCLK The user double-clicks a string in a list box. Only a list box that has the LBS_NOTIFY style will send this notification message.
ON_LBN_ERRSPACE The list box cannot allocate enough memory to meet the request.
ON_LBN_KILLFOCUS The list box is losing the input focus.
ON_LBN_SELCANCEL The current list-box selection is canceled. This message is only sent when a list box has the LBS_NOTIFY style.
ON_LBN_SELCHANGE The selection in the list box has changed. This notification is not sent if the selection is changed by the CListBox::SetCurSel member function. This notification applies only to a list box that has the LBS_NOTIFY style. The LBN_SELCHANGE notification message is sent for a multiple-selection list box whenever the user presses an arrow key, even if the selection does not change.
ON_LBN_SETFOCUS The list box is receiving the input focus.
ON_WM_CHARTOITEM An owner-draw list box that has no strings receives a WM_CHAR message.
ON_WM_VKEYTOITEM A list box with the LBS_WANTKEYBOARDINPUT style receives a WM_KEYDOWN message.

If you create a CListBox object within a dialog box (through a dialog resource), the CListBox object is automatically destroyed when the user closes the dialog box.

If you create a CListBox object within a window, you may need to destroy the CListBox object. If you create the CListBox object on the stack, it is destroyed automatically. If you create the CListBox object on the heap by using the new function, you must call delete on the object to destroy it when the user closes the parent window.

If you allocate any memory in the CListBox object, override the CListBox destructor to dispose of the allocation.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CListBox

Requirements

Header: afxwin.h

Share via

CListBox Class

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

See Also

Reference

Concepts

Additional resources