Programming Listbox Windows API
Description of the Win32 Listbox Control, Styles, Messages
How to Create, Manipulate, Search and receive messages from a Windows Win32 AP Listbox Control - language neutral, platform specific.
Introduction
A listbox is a type of control available to Windows programmers that can contain a list of items, usually strings by default, but other types of data can be added in more advanced cases. Typically, a listbox has a right hand side scroll bar, and items are selected by single or double clicking them.
In this how-to, we present the interface to listboxes in a language neutral fashion, referring to common functions that should be available in all Windows programming environments in one form or another. Specifically:
- CreateWindow
- SendDlgItemMessage
The Windows API also defined some constants for dealing with listboxes which may or may not be available in the compiler toolkit being used:
- WM_...
- LB_...
- LBS_...
- LBN_...
These equate to values which are typically listed in most Windows API documentation included with the compiler platform. This how-to is Wine compliant, but if a reader finds that some examples do not work with their Linux/Wine implementation, they should comment below, or notify the author.
Creating the Listbox
We create a listbox by calling the CreateWindow API function, giving "listbox" as the window class name in the first parameter. The window name can be an empty string, and the other parameters follow the usual window creation standard for positioning and identifying the parent and control ID. The style parameter can be customized, however, and some common LBS_ values are:
- LBS_STANDARD - alphabetically sorted, with parent notification and a border.
- LBS_SORT - just sorted, can be combined with WS_ (i.e. WS_BORDER) and LBS_ (i.e. LBS_NOTIFY) styles.
- LBS_NOINTEGRALHEIGHT - the box is sized according to the size parameters, even if that means that a half-item is displayed at the bottom.
- LBS_DISABLENOSCROLL - a disabled scrollbar is displayed, even if the listbox is not filled.
The parent parameter should be set correctly to allow messages to be sent and received from the listbox, and the WM_VISIBLE style must be set for the control to be visible upon creation. If a scroll bar is needed, WS_VSCROLL is required, and if messages are to be received (notification) by the parent window's window procedure, the LBS_NOTIFY style needs to be added.
Adding Items to the Listbox
We add items to the listbox with a call to SendDlgItemMessage, specifying the parent window, control ID, and one of the following:
- LB_ADDSTRING - add a string to the end, or sorted if LBS_SORT specified.
- LB_INSERTSTRING - insert string at a given point.
The LPARAM of the function shall be set to a pointer to the string to be added, while the WPARAM needs to specify the index (zero based) when LB_INSERTSTRING is used, or 0 (zero) otherwise.
Removing Items from the Listbox
We remove items to the listbox with a call to SendDlgItemMessage, specifying the parent window, control ID, and specifying the LB_DELETESTRING message. The LPARAM must be set to 0, and the WPARAM to an existing item index (zero based).
Searching the Listbox
There are two messages that can be used to search the listbox:
- LB_FINDSTRING - find a substring in the listbox.
- LB_FINDSTRINGEXACT - find the exact string in the listbox.
These only work with list boxes containing text. The LPARAM of the SendDlgItemMessage function call contains a pointer to the search string, which is never case sensitive. Therefore 'mystring' and 'MyStrinG' are considered to be equivalent. If the listbox does not contain strings, then the parent window receives a WM_COMPAREITEM message in order to allow the application to ascertain whether two items are equal or not.
