Windows Predefined Controls – Part 19
Volume – Windows User Interface
This is part 19 of my series, Windows Predefined Controls. In order to understand this tutorial, you most have read all the previous tutorials of the series. In this part of the series, we see how to create a list box.
Note: If you cannot see the code or if you think anything is missing (broken link, image absent), just contact me at email@example.com. That is, contact me for the slightest problem you have about what you are reading.
A List Box
A list box is a control that has a list of items that the user can choose from. The user chooses an item by selecting it. The user selects an item by clicking it. It is possible to select an item using the keyboard, but I will not go into that. In this series we shall talk about list boxes whose items are strings (texts). A list box can provide scroll bars if the items are too many for the space provided for the number of items. Selecting a list item changes its text color and its background color.
Creating a List Box
You can create a list box using the CreateWindowEx function. The class is, LISTBOX. Do not forget to type WS_CHILD since it is a child window. Remember that a list box is a control and it needs its unique integer identifier.
Types of List Boxes
There are two types of list boxes: single-selection and multiple-selection. Single-selection is the default. In a single-selection list box, the user can select only one item at a time. In a multiple-selection list box, the user can select more than one item at a time. If you want the multiple-selection list box, use the LBS_EXTENDEDSEL style. You do not need to type any special style for the single-selection list box.
You can create a List box using the CreateWindowEx function. After that you have to send each item string to the box using the SendMessage function. In this series, we are dealing with strings as items in the list box. The message to add a string to a list box is LB_ADDSTRING.
This message 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. The wParam parameter is not used (set it to NULL). The lParam parameter is a pointer to the null-terminated string that is to be added. The return value is the list box zero-based index of the added string. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE. These kind of return values are identifiers to constants.
Here is an example program to create a list box:
using namespace std;
LRESULT CALLBACK MainWndProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
return DefWindowProc(hwnd, uMsg, wParam, lParam);
int WINAPI WinMain(HINSTANCE hinstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
wcx.cbSize = sizeof(wcx);
wcx.style = CS_HREDRAW | CS_VREDRAW;
wcx.lpfnWndProc = MainWndProc;
wcx.cbClsExtra = 0;
wcx.cbWndExtra = 0;
wcx.hInstance = hinstance;
wcx.hIcon = NULL;
wcx.hCursor = LoadCursor(NULL, IDC_ARROW);
wcx.hbrBackground = (HBRUSH)(COLOR_BACKGROUND+1);
wcx.lpszMenuName = NULL;
wcx.lpszClassName = “MainWClass”;
wcx.hIconSm = NULL;
hwndMain = CreateWindowEx(0, “MainWClass”, “Main Window”, WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT,
CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL, hinstance, NULL);
const char *str1 = “the first string.”;
const char *str2 = “the second string.”;
const char *str3 = “the third string.”;
const char *str4 = “the fourth string.”;
const char *str5 = “the fifth string.”;
hwndLst = CreateWindowEx(0, “LISTBOX”, NULL, WS_CHILD, 100, 100, 100, 150, hwndMain, (HMENU)1, hinstance, NULL);
SendMessage(hwndLst, LB_ADDSTRING, NULL, (LPARAM)str1);
SendMessage(hwndLst, LB_ADDSTRING, NULL, (LPARAM)str2);
SendMessage(hwndLst, LB_ADDSTRING, NULL, (LPARAM)str3);
SendMessage(hwndLst, LB_ADDSTRING, NULL, (LPARAM)str4);
SendMessage(hwndLst, LB_ADDSTRING, NULL, (LPARAM)str5);
while( (bRet = GetMessage( &msg, hwndMain, 0, 0 )) != 0)
if (bRet == -1)
// handle the error and possibly exit the application
You can use the following command at the command prompt to compile the code:
g++ winlst.cpp -mwindows -o winlst.exe
The list box created by the above code is a single-selection list box. You cannot have more than one item selected (highlighted). You can add scrollbars using the windows styles, WS_VSCROLL and/or WS_HSCROLL (see later).
Creating the Multiple-Selection List Box
To create a single-selection list box you do not need any special style for that. However to create a multiple-selection list box you need to use the LBS_EXTENDEDSEL style. Replace the code segment that creates the single-selection list box above with the following and try the program again (you may use a different .exe filename).
hwndLst = CreateWindowEx(0, “LISTBOX”, NULL, WS_CHILD|LBS_EXTENDEDSEL, 100, 100, 100, 150, hwndMain, (HMENU)1, hinstance,
With the multiple-selection list box, you can select more than one item with the help of the Shift or Ctrl key on the keyboard.
That is it for this part of the series. We stop here and continue in the next part.
To arrive at any of the parts of this series, just type the corresponding title below in the Search Box of this page and click Search (use menu if available):
Static Control Styles
Windows List Box
Windows List Box Styles
Windows List Box Notifications
Windows List Box Messages
Creating a List Box
List Box Functions