Share via


CListBox Class

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

See Also

Reference

CWnd Class

Hierarchy Chart

CWnd Class

CButton Class

CComboBox Class

CEdit Class

CScrollBar Class

CStatic Class

Concepts

MFC Sample CTRLTEST