Windows List Box Messages
Windows Predefined Controls – Part 18
Volume - Windows User Interface
Forward: In this part of the series, we look at Windows List Box Messages.
By: Chrysanthus Date Published: 29 Aug 2012
Introduction
Note: If you cannot see the code or if you think anything is missing (broken link, image absent), just contact me at forchatrans@yahoo.com. That is, contact me for the slightest problem you have about what you are reading.
Directory Listing
A list box can hold any set of items. In particular, it can hold a directory listing; that is, each item in the list box is an item of a directory listing (subdirectory or filename).
Messages
The application can send a message to a control. The message can be sent with the SendMessage function. If you have forgotten the details of the SendMessage function, then read in this blog, the tutorial titled, Control Messages. If you have forgotten how to handle LOWORD and HIWORD, then read in this blog the tutorial titled, Edit Control Messages. Remember, a message can return a value. The returned value is actually returned by the SendMessage function. I now give you the messages and their meanings.
LB_ADDFILE: This message adds the specified filename to a list box that contains a directory listing. In order to use this message code, the list box to which the filename is added must have been filled by the DlgDirList function. Here, the wParam parameter is not used (set it to NULL). The lParam is a pointer to a buffer (char array) that specifies the name of the file to add. The return value is the list box zero-based index of the file that was added, or LB_ERR if an error occurs.
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.
LB_DELETESTRING: This message deletes a string in a list box. The wParam is the list box zero-based index of the string to be deleted. The lParam is used (set it to NULL). The return value is a count of the strings remaining in the list. The return value is LB_ERR if the wParam parameter specifies an index greater than the number of items in the list.
LB_DIR: This message 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. The wParam parameter is the attributes of the files or directories to be added to the list box. It can be one or more of the following values.
Value: Meaning
DDL_ARCHIVE: Includes archived files.
DDL_DIRECTORY: Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES: With this, all mapped drives are added to the list. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE: Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN: Includes hidden files. This is for files of the hidden attribute.
DDL_READONLY: Includes read-only files. This is for files of the read-only attribute.
DDL_READWRITE: Includes read-write files with no additional attributes. This is the default setting.
DDL_SYSTEM: Includes system files.
The lParam parameter is a pointer to the null-terminated string that specifies an absolute path, relative path, or filename. An absolute path can begin with a drive letter (for example, e:) or a UNC name (for example, \ machinename sharename). If the string specifies a filename or directory that has the attributes specified by the wParam parameter, the filename or directory is added to the list. If the filename or directory name contains wildcard characters (? or *), all files or directories that match the wildcard expression and have the attributes specified by the wParam are added to the list. If the message succeeds, the return value is the zero-based index of the last name added to the list. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new strings, the return value is LB_ERRSPACE.
LB_FINDSTRINGEXACT: This message finds the first list box string that exactly matches the specified string; the search is not case sensitive. The wParam is the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues searching from the top of the list box back to the item specified by the wParam parameter. If wParam is – 1, the entire list box is searched from the beginning. The lParam is a pointer to the null-terminated string for which to search. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters. The return value is the zero-based index of the matching item, or LB_ERR if the search was unsuccessful.
LB_GETANCHORINDEX: The item from which a multiple selection starts is called the anchor item. This message gets the index of the anchor item. A multiple selection spans all items from the anchor item to the caret item. The wParam is not used; it must be zero. The lParam is not used; it must be zero. The return value is the index of the anchor item.
LB_GETCARETINDEX: This message 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. The wParam is not used; it must be zero. The lParam is not used; it must be zero. The return value is the zero-based index of the focused list box item, or 0 if no item has the focus.
LB_GETCURSEL: This message gets the index of the currently selected item, if any, in a single-selection list box. The wParam is not used; it must be zero. The lParam is not used; it must be zero. In a single-selection list box, the return value is the zero-based index of the currently selected item. If there is no selection, the return value is LB_ERR.
LB_GETHORIZONTALEXTENT: This message gets the scrollable width, in pixels, that a list box can be scrolled horizontally if the list box has a horizontal scroll bar. The wParam is not used; it must be zero. The lParam is not used; it must be zero. The return value is the scrollable width, in pixels, of the list box.
LB_GETITEMDATA: An application can define a value and associated it with an item in the list box. This message gets the application-defined value associated with the specified list box item. The wParam is the index of the item. The lParam is not used. The return value is the value associated with the item, or LB_ERR if an error occurs.
LB_GETITEMHEIGHT: This message gets the height of each item in a list box. The wParam should be zero. The lParam is not used (set it to NULL). The return value is the height, in pixels, of each item in the list box.
LB_GETITEMRECT: This message gets the dimensions of the rectangle that bounds a list box item as it is currently displayed in the list box. The wParam is the zero-based index of the item. The lParam is a pointer to a RECT struct (see later) that will receive the client coordinates for the item in the list box. If an error occurs, the return value is LB_ERR. The dimensions of the rectangle read are kept in the RECT struct, which should have been declared previously in the application.
LB_GETLOCALE: This message gets the current locale (see later) 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. The wParam is not used; it must be zero. The lParam is not used; it must be zero. The return value specifies the current locale of the list box. The HIWORD contains the country/region code and the LOWORD contains the language identifier.
LB_GETSEL: This message gets the selection state of an item (that is, is an item selected or not). The wParam is the zero-based index of the item. The lParam is not used (set it to NULL). If an item is selected, the return value is greater than zero; otherwise, it is zero. If an error occurs, the return value is LB_ERR.
LB_GETSELCOUNT: This message gets the total number of selected items in a multiple-selection list box. The wParam is not used; it must be zero. The lParam is not used; it must be zero. The return value is the count of selected items in the list box. If the list box is a single-selection list box, the return value is LB_ERR.
LB_GETSELITEMS: This message fills a buffer with an array of integers that specify the item numbers of selected items in a multiple-selection list box. The wParam is the maximum number of selected items whose item numbers are to be placed in the buffer. The lParam is a pointer to a buffer large enough for the number of integers specified by the wParam parameter. The return value is the number of items placed in the buffer. If the list box is a single-selection list box, the return value is LB_ERR.
LB_GETTEXTLEN: This message gets the length of a string in a list box. The wParam is the zero-based index of the string. The lParam is not used (set it to NULL). The return value is the length of the string, in TCHARs (characters), excluding the terminating null character. If the wParam parameter does not specify a valid index, the return value is LB_ERR.
LB_GETTEXT: This message gets a string from a list box. The wParam is the zero-based index of the string to retrieve. The lParam is a pointer to the buffer that will receive the string; it is type LPTSTR (see later) which is subsequently cast to an LPARAM. The buffer must have sufficient space for the string and a terminating null character ( ). An LB_GETTEXTLEN message can be sent before the LB_GETTEXT message to retrieve the length, in TCHARs (characters), of the string. The return value is the length of the string, in TCHARs, excluding the terminating null character. If wParam does not specify a valid index, the return value is LB_ERR.
LB_GETTOPINDEX: This message 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. The wParam is not used; it must be zero. The lParam is not used; it must be zero. The return value is the index of the first visible item in the list box.
LB_INITSTORAGE: If your list box would have more than 100 items then you have to use this message before an application adds a large number of items to the list box. This message allocates memory for storing list box items. It helps speed up the initialization of list boxes that have a large number of items (more than 100). It reserves the specified amount of memory so that subsequent LB_ADDSTRING, LB_INSERTSTRING, LB_DIR, and LB_ADDFILE messages take the shortest possible time. The wParam is the number of items to add. The lParam is the amount of memory, in bytes (characters), to allocate for item strings. If the message is successful, the return value is the total number of items for which memory has been pre-allocated, that is, the total number of items added by all successful LB_INITSTORAGE messages. If the message fails, the return value is LB_ERRSPACE. With Microsoft Windows NT 4.0 : This message does not allocate the specified amount of memory; however, it always returns the value specified in the wParam parameter.
LB_INSERTSTRING: This message 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. The wParam is the zero-based index of the position at which to insert the string; the other strings are pushed one step downward. If this parameter is –1, the string is added to the end of the list. The lParam is a pointer to the null-terminated string to be inserted. The return value is the index of the position at which the string was inserted. 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.
LB_RESETCONTENT: This message removes all items from a list box. The wParam is not used; it must be zero. The lParam is not used; it must be zero. This message does not return a value.
LB_SELECTSTRING: The message 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. The list box is scrolled, if necessary, to bring the selected item into view. Do not use this message with a list box that has the LBS_MULTIPLESEL or the LBS_EXTENDEDSEL styles. The wParam is the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the wParam parameter. If wParam is –1, the entire list box is searched from the beginning. The lParam is a pointer to the null-terminated string that contains the prefix for which to search. The search is case insensitive, so this string can contain any combination of uppercase and lowercase letters. If the search is successful, the return value is the index of the selected item. If the search is unsuccessful, the return value is LB_ERR and the current selection is not changed.
LB_SELITEMRANGE: This message selects or deselects one or more consecutive items in a multiple-selection list box. Use this message only with multiple-selection list boxes. This message can select a range only within the first 65,536 items. The wParam is set to TRUE to select the range of items, or FALSE to deselect it. The LOWORD of lParam specifies the zero-based index of the first item to select. The HIWORD specifies the zero-based index of the last item to select. If an error occurs, the return value is LB_ERR.
LB_SELITEMRANGEEX: This message selects one or more consecutive items in a multiple-selection list box. The wParam specifies the zero-based index of the first item to select. The lParam specifies the zero-based index of the last item to select. If an error occurs, the return value is LB_ERR. You should use this message only with multiple-selection list boxes. Note: If the wParam parameter is less than the lParam parameter, the specified range of items is selected. If wParam is greater than or equal to lParam, the range is removed from the specified range of items. To select only one item, select two items and then deselect the unwanted item.
LB_SETANCHORINDEX: The item from which a multiple selection starts is called the anchor item. A multiple selection spans all items from the anchor item to the caret item. This message sets the anchor item. The wParam specifies the index of the new anchor item. The lParam is not used (set it to NULL). If the message succeeds, the return value is zero. If the message fails, the return value is LB_ERR.
LB_SETCARETINDEX: This message 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. The wParam specifies the zero-based index of the list box item that is to receive the focus rectangle. The lParam can be FALSE and in that case the item is scrolled until it is fully visible; if it is TRUE, the item is scrolled until it is at least partially visible. If an error occurs, the return value is LB_ERR (-1). Otherwise, LB_OKAY (0) is returned. Note: If this message is sent to a single-selection list box that does not contain a selected item, the caret index is set to the item specified by the wParam parameter. If the single-selection list box does contain a selected item, the list box returns LB_ERR.
LB_SETCOLUMNWIDTH: This message sets the width, in pixels, of all columns in a multiple-column list box. The wParam specifies the width, in pixels, of all columns. The lParam parameter is not used (set it to NULL). This message does not return a value.
LB_SETCOUNT: This message sets the count of items in a list box created with the LBS_NODATA style and not created with the LBS_HASSTRINGS style. The wParam specifies the new count of items in the list box. The lParam is not used (set it to NULL). If an error occurs, the return value is LB_ERR. If there is insufficient memory to store the items, the return value is LB_ERRSPACE. The LB_SETCOUNT message is supported only by list boxes created with the LBS_NODATA style and not created with the LBS_HASSTRINGS style. So all other list boxes return LB_ERR.
LB_SETCURSEL: This message 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. The wParam specifies the zero-based index of the string that is selected. If this parameter is -1, the list box is set to have no selection. The lParam is not used (set it to NULL). If an error occurs, the return value is LB_ERR. If the wParam parameter is –1, the return value is LB_ERR even though no error occurred. Note: You should use this message only with single-selection list boxes. You cannot use it to set or remove a selection in a multiple-selection list box.
LB_SETHORIZONTALEXTENT: This message 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. The wParam specifies the number of pixels by which the list box can be scrolled. The lParam not used (set it to NULL). This message does not return a value.
LB_SETITEMDATA: This message sets a value associated with the specified item in a list box. The wParam specifies the zero-based index of the item. If this value is -1, the lParam value applies to all items in the list box. The lParam specifies the value to be associated with the item. If an error occurs, the return value is LB_ERR.
LB_SETITEMHEIGHT: The message sets the height, in pixels, of items in a list box. The wParam should be set it to zero. The lParam specifies the height, in pixels, of the item. The maximum height is 255 pixels. If the index or height is invalid, the return value is LB_ERR.
LB_SETLOCALE: This message 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. The wParam specifies the locale identifier (see later) that the list box will use for sorting when adding text. Use the MAKELCID macro (see later) to construct a locale identifier. The lParam is not used (SET it to NULL). The return value is the previous locale identifier. If the wParam parameter specifies a locale that is not installed on the system, the return value is LB_ERR and the current list box locale is not changed.
LB_SETSEL: This message selects a string in a multiple-selection list box. The wParam specifies how to set the selection. If this parameter is TRUE, the item is selected and highlighted; if it is FALSE, the highlight is removed and the item is no longer selected.
The lParam specifies the zero-based index of the item to set. If this parameter is –1, the selection is added to or removed from all items, depending on the value of wParam, and no scrolling occurs. If an error occurs, the return value is LB_ERR.
LB_SETTABSTOPS: This message sets the tab-stop positions in a list box. The wParam specifies the number of tab stops. The lParam is a pointer to the first member of an array of integers containing the tab stops. The integers represent the number of quarters of the average character width for the font that is selected into the list box. However, if the list box is part of a dialog box, the integers are in dialog template units. The tab stops must be sorted in ascending order; backward tabs are not allowed. If all the specified tabs are set, the return value is TRUE; otherwise, it is FALSE.
LB_SETTOPINDEX: This message ensures that the specified item in a list box is visible. The wParam is the zero-based index of the item in the list box. The lParam is not used (set to NULL). If an error occurs, the return value is LB_ERR.
That is it for this part of the series. We stop here and continue in the next part.
Chrys
Related Courses
C++ CourseRelational Database and Sybase
Windows User Interface
Computer Programmer – A Jack of all Trade – Poem
NEXT