Edit

Combo Box Features

  • Article

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".

screen shot of 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.