Combo Box Features
This document discusses features of the combo box. For more information, see the following topics:
Special Features
There are special-purpose messages and functions that enable an application to display a directory listing in a combo box, associate data with list items in a combo box, and change the keyboard interface for a drop-down combo box or drop-down list box.
Directory Lists
An application can add the names of files or subdirectories to a combo box by sending the CB_DIR message to it. The wParam parameter for this message specifies the attributes of the files to add, and the lParam parameter is a pointer to the text string that defines the file specification.
You can use the DlgDirListComboBox function to replace the contents of a combo box in a dialog box. The function fills the combo box with the names of drives, directories, and files that match a specified set of criteria. The DlgDirSelectComboBoxEx function retrieves the current selection in a combo box initialized by DlgDirListComboBox. These functions make it possible for the user to select a drive, directory, or file from a combo box without typing the location and name of the file.
The DlgDirListComboBox and DlgDirSelectComboBoxEx functions and the CB_DIR message are similar to the DlgDirList and DlgDirSelectEx functions and the LB_DIR message used with list boxes.
Data Associated with List Items
An application can associate data with the list items in a combo box. The CB_SETITEMDATA message associates a DWORD value with a list item, and the CB_GETITEMDATA retrieves the value associated with a list item.
The example in Creating an Owner Drawn Combo Box uses item data to associate a constant with each item in a drop-down list box. Such a unique value identifies each item independent of its sorted position.
Other applications might use item data to associate a handle or pointer with a list item. If so, an application can process a WM_DELETEITEM message to delete or free the specified object when the list item is deleted.
The Extended User Interface
Drop-down combo boxes and drop-down list boxes support an alternative keyboard interface called the extended user interface. By default, the F4 key opens or closes the list, and the DOWN ARROW changes the current selection. In a combo box with the extended user interface, however, the F4 key is disabled and pressing the DOWN ARROW key opens the drop-down list. In addition, the mouse wheel, which normally scrolls through the items in the list, does not have any function when the extended UI is set.
To select the user interface for a combo box, an application can send the CB_SETEXTENDEDUI message to the combo box. A TRUE value for the wParam parameter enables the extended user interface; a FALSE value sets the default user interface. To determine whether a combo box uses the extended user interface, an application can send the CB_GETEXTENDEDUI message to the combo box.
Cue Banners
Cue banners are a new feature of edit controls and combo boxes. The purpose of a cue banner is to provide a hint to the user as to the purpose of an edit control or combo box. The following screen shot shows an edit control with the cue text "Search".
The text of a cue banner is displayed when an edit control has no text or a combo box has no selection. When the user enters text into the edit control or makes a selection in a combo box, the cue banner disappears. By default, the cue banner also disappears when the edit control or combo box receives focus.
Combo Box Notifications
Messages from combo boxes are sent as notification codes in the form of WM_COMMAND messages. The notification code is stored in the high word of the wParam parameter, and an application can process the following combo box notification codes.
| Notification code | Description |
|---|---|
| CBN_CLOSEUP | Indicates the list in a drop-down combo box or drop-down list box is about to close. |
| CBN_DBLCLK | Indicates the user has double-clicked a list item in a simple combo box. |
| CBN_DROPDOWN | Indicates the list in a drop-down combo box or drop-down list box is about to open. |
| CBN_EDITCHANGE | Indicates the user has changed the text in the edit control of a simple or drop-down combo box. This notification code is sent after the altered text is displayed. |
| CBN_EDITUPDATE | Indicates the user has changed the text in the edit control of a simple or drop-down combo box. This notification code is sent before the altered text is displayed. |
| CBN_ERRSPACE | Indicates the combo box cannot allocate enough memory to carry out a request, such as adding a list item. |
| CBN_KILLFOCUS | Indicates the combo box is about to lose the input focus. |
| CBN_SELCHANGE | Indicates the current selection has changed. |
| CBN_SELENDCANCEL | Indicates that the selection made in the drop down list, while it was dropped down, should be ignored. |
| CBN_SELENDOK | Indicates that the selection made drop down list, while it was dropped down, should be accepted. |
| CBN_SETFOCUS | Indicates the combo box has received the input focus. |
Default Combo Box Behavior
This following table describes the messages specifically handled by the predefined COMBOBOX class window procedure.
| Message | Description |
|---|---|
| CB_ADDSTRING | Sends an LB_ADDSTRING message to the list window to add a list item. |
| CB_DELETESTRING | Sends an LB_DELETESTRING message to the list window to delete a list item. |
| CB_DIR | Adds the file names matching the specified attributes and path to the list. |
| CB_FINDSTRING | Sends an LB_FINDSTRING message to the list window. This message returns the index of the first list item that begins with the specified text. |
| CB_FINDSTRINGEXACT | Sends an LB_FINDSTRING message to the list window. This message returns the index of the first list item exactly matching the specified text. |
| CB_GETCOUNT | Sends an LB_GETCOUNT message to the list window. It returns the number of list items. |
| CB_GETCURSEL | Sends an LB_GETCURSEL message to the list window. It returns the index of the currently selected item, if any. |
| CB_GETDROPPEDCONTROLRECT | Fills the specified rectangle structure with the screen coordinates of a drop-down list. |
| CB_GETDROPPEDSTATE | Returns TRUE if a drop-down list is open; otherwise, it returns FALSE. |
| CB_GETDROPPEDWIDTH | Returns the minimum allowable width, in pixels, of the drop-down list. |
| CB_GETEDITSEL | Sends an EM_GETSEL message to the edit control, and it returns the starting and ending position of the current selection. In drop-down list boxes, the window procedure returns CB_ERR. |
| CB_GETEXTENDEDUI | Returns TRUE if the combo box is a drop-down combo box or drop-down list box and the extend user-interface flag is set; otherwise, it returns FALSE. |
| CB_GETHORIZONTALEXTENT | Sends an LB_GETHORIZONTALEXTENT message to the list window. It returns the scrollable width, in pixels, of the drop-down list. |
| CB_GETITEMDATA | Sends an LB_GETITEMDATA message to the list window. It returns the value associated with the specified list item. |
| CB_GETITEMHEIGHT | Sends an LB_GETITEMHEIGHT message to the list window. It returns the height, in pixels, of the specified owner-drawn list item. |
| CB_GETLBTEXT | Sends an LB_GETTEXT message to the list window. It copies the specified list text to the specified buffer. |
| CB_GETLBTEXTLEN | Sends an LB_GETTEXTLEN message to the list window. It returns the length, in TCHARs, of the specified list text. |
| CB_GETLOCALE | Sends an LB_GETLOCALE message to the list window. It returns the current locale for the list. |
| CB_GETMINVISIBLE | Gets the minimum number of visible items in the drop-down list of a combo box. |
| CB_GETTOPINDEX | Sends an LB_GETTOPINDEX message to the list window. It returns the index of the first visible item in the drop-down list. |
| CB_INITSTORAGE | Sends an LB_INITSTORAGE message to the list window. It initializes space for the specified number of items and the specified number of bytes for item strings. |
| CB_INSERTSTRING | Sends an LB_INSERTSTRING message to the list window. It inserts a list item at the specified position. |
| CB_LIMITTEXT | Sends an EM_LIMITTEXT message to the edit control. It sets the maximum number of characters a user can enter in the edit control. In drop-down list boxes, the window procedure returns CB_ERR. |
| CB_RESETCONTENT | Sends an LB_RESETCONTENT message to the list window, and it removes the contents of the list. |
| CB_SELECTSTRING | Sends an LB_SELECTSTRING message to the list window. It selects the first list item, if any, that begins with the characters in the specified text. |
| CB_SETCURSEL | Sends an LB_SETCURSEL message to the list window, and it sets the current selection. |
| CB_SETDROPPEDWIDTH | Sets the minimum allowable width, in pixels, of the drop down list. |
| CB_SETEDITSEL | Sends an EM_SETSEL message to the edit control. It selects the specified range of text. In drop-down list boxes, the window procedure returns CB_ERR. |
| CB_SETEXTENDEDUI | Sets or clears the extended user-interface flag. This flag changes the keys that open and close the list in a drop-down combo box or drop-down list box. If the combo box is a simple combo box, the window procedure returns CB_ERR. |
| CB_SETHORIZONTALEXTENT | Sends an LB_SETHORIZONTALEXTENT message to the list window. It sets the scrollable width, in pixels, of the drop down list. |
| CB_SETITEMDATA | Sends an LB_SETITEMDATA message to the list window. It associates the specified value with a list item. |
| CB_SETITEMHEIGHT | Sends an LB_SETITEMHEIGHT message to the list window. It sets the height of the specified owner-drawn list item or the selection field. |
| CB_SETLOCALE | Sends an LB_SETLOCALE message to the list window, and it sets the current locale for the list. The locale affects how the list is sorted if it has the CBS_SORT style and strings are added using CB_ADDSTRING. |
| CB_SETMINVISIBLE | Sets the minimum number of visible items in the drop-down list of a combo box. |
| CB_SETTOPINDEX | Sends an LB_SETTOPINDEX message to the list window. It scrolls the drop-down list so the specified item is at the top of the visible range. |
| CB_SHOWDROPDOWN | Shows or hides the drop-down list. This message has no effect on simple combo boxes. |
| WM_CHAR | Processes character input. In drop-down list boxes, this message is passed to the list window, which moves the selection to the first item beginning with the specified character. In simple and drop-down combo boxes, this message is passed to the edit control. |
| WM_CLEAR | Deletes the edit selection. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR. |
| WM_COMMAND | Processes notification messages from the edit control and list window and sends corresponding combo box notification codes to the parent window. |
| For edit control notifications, the window procedure may update the list window's current selection, caret index, and top index. For list notification messages, the window procedure may update the content of the selection field. | |
| WM_COMPAREITEM | Passes the message to the parent window, enabling the application to specify the relative sort position of two owner-drawn list items. The combo box window receives this message from the list window. |
| WM_COPY | Copies the edit selection to the clipboard. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR. |
| WM_CREATE | Initializes the combo box. |
| WM_CUT | Deletes the edit selection and places it on the clipboard. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR. |
| WM_DELETEITEM | Passes the message to the parent window, notifying the application that a list item has been deleted. The combo box window receives this message from the list window. |
| WM_DRAWITEM | Passes the message on to the parent window enabling the application to paint the specified list item. The combo box window receives this message from the list window. The window procedure can also originate this message to have the application paint the selection field of a drop-down list box. |
| WM_ENABLE | Sets the state to enable or prohibit mouse and keyboard input. |
| WM_ERASEBKGND | Returns 1, indicating that the background is erased. |
| WM_GETDLGCODE | Returns a combination of the DLG_WANTCHARS and DLGC_WANTARROWS values. |
| WM_GETFONT | Returns the handle to the current font with which the combo box will draw its text. |
| WM_GETTEXT | Copies the contents of the selection field to the specified buffer. In simple and drop-down combo boxes, the edit control processes this message. |
| WM_GETTEXTLENGTH | Returns the length, in characters, of the text in the selection field. In simple and drop-down combo boxes, the edit control processes this message. |
| WM_KEYDOWN | Processes noncharacter keyboard input. In drop-down list boxes, this message is sent to the list window, which may show or hide itself, or change its current selection or caret index. In simple and drop-down combo boxes, this message is passed to the edit control. The edit control passes certain keys to the list window, such as the UP and DOWN ARROW keys and the F4 key. |
| WM_KILLFOCUS | Hides the highlight in the selection field and closes the drop-down list, if necessary. If the window receiving the input focus is part of the combo box (for example, the edit control), this message is ignored. |
| WM_LBUTTONDBLCLK | Same as WM_LBUTTONDOWN. |
| WM_LBUTTONDOWN | Sets the focus to the combo box and, for drop-down combo boxes and drop-down lists, can open or close the list. If it opens the list, the window procedure captures the mouse to enable selection by dragging and releasing the mouse button. |
| WM_LBUTTONUP | Releases the mouse capture if the mouse opened the list. |
| WM_MEASUREITEM | Posts the message to the parent window, enabling the application to modify the contents of the specified MEASUREITEMSTRUCT structure. The combo box window receives this message from the list window. |
| WM_MOUSEMOVE | Posts the message to the list window if the mouse has opened the list and the mouse button is still down. This enables a user to select an item by dragging the mouse pointer to a list item and then releasing the button. |
| WM_NCCREATE | Allocates an internal data structure used by the combo box window procedure. |
| WM_NCDESTROY | Frees resources allocated in response to the WM_NCCREATE message. |
| WM_PAINT | Paints the invalid region of the combo box. If wParam is not NULL, it is assumed to be a device context (DC) handle passed from a subclass function. The window procedure uses the specified DC instead of calling BeginPaint and EndPaint. |
| WM_PASTE | Replaces the edit selection with the contents of the clipboard. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR. |
| WM_SETFOCUS | Sets the focus to the edit control or, in drop-down list boxes, inverts the selection field and turns on the caret in the list window. |
| WM_SETFONT | Saves the specified font handle in an internal structure, adjusts the dimensions of the selection field and list, and invalidates the combo box window. Text in the selection field and the list is displayed in the saved font. |
| WM_SETREDRAW | Sets or clears the redraw flag. If the redraw flag is cleared, the combo box is not repainted until the flag is set again. |
| WM_SETTEXT | Sets the contents of the edit control. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR. |
| WM_SIZE | Resizes the child windows, if necessary. |
| WM_SYSKEYDOWN | Opens or closes the drop-down list depending on which arrow key the user pressed. |
All other messages are passed to the DefWindowProc function for default processing.