This section contains information about the programming elements used with list boxes. A list box is a control window that contains a simple list of items from which the user can choose. For more complex lists, use the List View instead.

Overviews

About List Boxes

This section describes list box features.

Using List Boxes

This section explains how to perform tasks associated with list boxes.

Functions

DlgDirList

Replaces the contents of a list box with the names of the subdirectories and files in a specified directory. You can filter the list of names by specifying a set of file attributes. The list can optionally include mapped drives.

DlgDirSelectEx

Retrieves the current selection from a single-selection list box. It assumes that the list box has been filled by the DlgDirList function and that the selection is a drive letter, filename, or directory name.

GetListBoxInfo

Retrieves information about the specified list box.

Messages

LB_ADDFILE

Adds the specified filename to a list box that contains a directory listing.

LB_ADDSTRING

Adds a string to a list box. If the list box does not have the LBS_SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list and the list is sorted.

LB_DELETESTRING

Deletes a string in a list box.

LB_DIR

Adds names to the list displayed by a list box. The message adds the names of directories and files that match a specified string and set of file attributes. LB_DIR can also add mapped drive letters to the list box.

LB_FINDSTRING

Finds the first string in a list box that begins with the specified string.

LB_FINDSTRINGEXACT

Finds the first list box string that exactly matches the specified string, except that the search is not case sensitive.

LB_GETANCHORINDEX

Gets the index of the anchor item

LB_GETCARETINDEX

Retrieves the index of the item that has the focus rectangle in a multiple-selection list box. The item may or may not be selected.

LB_GETCOUNT

Gets the number of items in a list box.

LB_GETCURSEL

Gets the index of the currently selected item, if any, in a single-selection list box.

LB_GETHORIZONTALEXTENT

Gets the width, in pixels, that a list box can be scrolled horizontally (the scrollable width) if the list box has a horizontal scroll bar.

LB_GETITEMDATA

Gets the application-defined value associated with the specified list box item.

LB_GETITEMHEIGHT

Gets the height of items in a list box.

LB_GETITEMRECT

Gets the dimensions of the rectangle that bounds a list box item as it is currently displayed in the list box.

LB_GETLISTBOXINFO

Gets the number of items per column in a specified list box.

LB_GETLOCALE

Gets the current locale of the list box. You can use the locale to determine the correct sorting order of displayed text (for list boxes with the LBS_SORT style) and of text added by the LB_ADDSTRING message.

LB_GETSEL

Gets the selection state of an item.

LB_GETSELCOUNT

Gets the total number of selected items in a multiple-selection list box.

LB_GETSELITEMS

Fills a buffer with an array of integers that specify the item numbers of selected items in a multiple-selection list box.

LB_GETTEXT

Gets a string from a list box.

LB_GETTEXTLEN

Gets the length of a string in a list box.

LB_GETTOPINDEX

Gets the index of the first visible item in a list box. Initially the item with index 0 is at the top of the list box, but if the list box contents have been scrolled another item may be at the top.

LB_INITSTORAGE

Allocates memory for storing list box items. This message is used before an application adds a large number of items to a list box.

LB_INSERTSTRING

Inserts a string or item data into a list box. Unlike the LB_ADDSTRING message, the LB_INSERTSTRING message does not cause a list with the LBS_SORT style to be sorted.

LB_ITEMFROMPOINT

Gets the zero-based index of the item nearest the specified point in a list box.

LB_RESETCONTENT

Removes all items from a list box.

LB_SELECTSTRING

Searches a list box for an item that begins with the characters in a specified string. If a matching item is found, the item is selected.

LB_SELITEMRANGE

Selects or deselects one or more consecutive items in a multiple-selection list box.

LB_SELITEMRANGEEX

Selects one or more consecutive items in a multiple-selection list box.

LB_SETANCHORINDEX

Sets the anchor item

LB_SETCARETINDEX

Sets the focus rectangle to the item at the specified index in a multiple-selection list box. If the item is not visible, it is scrolled into view.

LB_SETCOLUMNWIDTH

Sets the width, in pixels, of all columns in a multiple-column list box.

LB_SETCOUNT

Sets the count of items in a list box created with the LBS_NODATA style and not created with the LBS_HASSTRINGS style.

LB_SETCURSEL

Selects a string and scrolls it into view, if necessary. When the new string is selected, the list box removes the highlight from the previously selected string.

LB_SETHORIZONTALEXTENT

Sets the width, in pixels, by which a list box can be scrolled horizontally (the scrollable width). If the width of the list box is smaller than this value, the horizontal scroll bar horizontally scrolls items in the list box. If the width of the list box is equal to or greater than this value, the horizontal scroll bar is hidden.

LB_SETITEMDATA

Sets a value associated with the specified item in a list box.

LB_SETITEMHEIGHT

Sets the height, in pixels, of items in a list box. If the list box has the LBS_OWNERDRAWVARIABLE style, this message sets the height of the item specified by the wParam parameter. Otherwise, this message sets the height of all items in the list box.

LB_SETLOCALE

Sets the current locale of the list box. You can use the locale to determine the correct sorting order of displayed text (for list boxes with the LBS_SORT style) and of text added by the LB_ADDSTRING message.

LB_SETSEL

Selects a string in a multiple-selection list box.

LB_SETTABSTOPS

Sets the tab-stop positions in a list box.

LB_SETTOPINDEX

Ensures that the specified item in a list box is visible.

Notifications

LBN_DBLCLK

Notifies the application that the user has double-clicked an item in a list box. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_ERRSPACE

Notifies the application that the list box cannot allocate enough memory to meet a specific request. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_KILLFOCUS

Notifies the application that the list box has lost the keyboard focus. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_SELCANCEL

Notifies the application that the user has canceled the selection in a list box. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_SELCHANGE

Notifies the application that the selection in a list box has changed. The parent window of the list box receives this notification message through the WM_COMMAND message.

LBN_SETFOCUS

Notifies the application that the list box has received the keyboard focus. The parent window of the list box receives this notification message through the WM_COMMAND message.

WM_CHARTOITEM

Sent by a list box with the LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_CHAR message.

WM_CTLCOLORLISTBOX

Sent to the parent window of a list box before the system draws the list box. By responding to this message, the parent window can set the text and background colors of the list box by using the specified display device context handle.

WM_DELETEITEM

Sent to the owner of a list box or combo box when the list box or combo box is destroyed or when items are removed by the LB_DELETESTRING, LB_RESETCONTENT, CB_DELETESTRING, or CB_RESETCONTENT message. The system sends a WM_DELETEITEM message for each deleted item. The system sends the WM_DELETEITEM message for any deleted list box or combo box item with nonzero item data.

WM_VKEYTOITEM

Sent by a list box with the LBS_WANTKEYBOARDINPUT style to its owner in response to a WM_KEYDOWN message.

Structures

DELETEITEMSTRUCT

Describes a deleted list box or combo box item. The lParam parameter of a WM_DELETEITEM message contains a pointer to this structure. When an item is removed from a list box or combo box or when a list box or combo box is destroyed, the system sends the WM_DELETEITEM message to the owner for each deleted item.

Windows NT/2000/XP: The system sends a WM_DELETEITEM message only for items deleted from an owner-drawn list box (with the LBS_OWNERDRAWFIXED or LBS_OWNERDRAWVARIABLE style) or owner-drawn combo box (with the CBS_OWNERDRAWFIXED or CBS_OWNERDRAWVARIABLE style).

Windows 95/98/Me: The system sends the WM_DELETEITEM message for any deleted list box or combo box item with nonzero item data.

Constants

List Box Styles

To create a list box by using the CreateWindow or CreateWindowEx function, use the LISTBOX class, appropriate window style constants, and the following style constants to define the list box. After the control has been created, these styles cannot be modified, except as noted.