HeaderPane
Main
Hide
Share Link
Print

Selection

A combo box control has one selected item, or no selected item at all. The selected item is displayed in the static portion of a dropdown list combo box, with its pictures and the cells of all columns. In a simple combo box or dropdown combo box, the edit control portion displays the cell text of one column of the selected item (see SetEditSearchColumn). The selected item is also highlighted in the dropdown portion.

Selecting an Item

GetCurSel returns the index of the selected item, or -1 if no item is selected. SetCurSel selects an item under program control. An index of -1 removes the selection, which also clears the static portion or edit control portion.

LONG index = SftBox_GetCurSel(hwndBox);
if (index >= 0) {
    TCHAR szText[80];
    if (SftBox_GetTextLength(hwndBox, index, 0) < 80)
        SftBox_GetText(hwndBox, index, 0, szText);  /* cell text of column 0 */
}

SelectString, SelectStringExact, SelectStringCase and SelectStringExactCase search a column for an item and select it. If no matching item is found, these functions return -1 and no item is selected.

The user selects an item by clicking anywhere on the item in the dropdown portion or by using the keyboard (Up and Down arrow keys, Page Up, Page Down, etc.). In a dropdown list combo box, the user can also type characters to locate an item (see Searching and Autocomplete); while the dropdown portion is hidden, the item found is selected immediately. In a simple combo box or dropdown combo box, the user can also type text into the edit control portion. The combo box then searches for a matching item and selects it, based on the mode defined using SetEditSearchMode. With the search modes SFTBOX_SEARCH_AUTO, SFTBOX_SEARCH_FIRST and SFTBOX_SEARCH_AUTOCOMPLETE, if the text typed does not match an item, no item is selected and GetCurSel returns -1, while the edit control portion keeps the text entered.

The Selection While the Dropdown Portion Is Shown

In a dropdown combo box or dropdown list combo box, the user can browse through the items of the dropdown portion before accepting an item. As the mouse cursor moves over the items, the item under the mouse cursor is highlighted as selected item in the dropdown portion, but the static portion or edit control portion is not updated and SFTBOXN_SELCHANGE is not sent. The fCursorSelect member of the SFTBOX_CONTROL structure (see SetControlInfo) defines whether the highlight follows the mouse cursor, which is the default. Disabled items are not highlighted this way if the fSelectEnabledItemsOnly member is set. In a simple combo box, moving the mouse cursor over the items does not change the selection.

While the dropdown portion is shown, GetCurSel returns the item currently highlighted in the dropdown portion, even if it has not been accepted yet.

When the user clicks an item, the item is accepted: the static portion or edit control portion is updated and the dropdown portion is closed. The highlighted item is also accepted when the user closes the dropdown portion using the Enter key, the F4 key, Alt+Up Arrow, Alt+Down Arrow or the dropdown button. In a dropdown combo box, the text of the edit control portion is then replaced with the text of the accepted item, unless the highlighted item is the item that was already accepted, in which case the text typed by the user is kept. If the dropdown portion is closed without accepting an item, the highlight returns to the item displayed in the static portion or edit control portion; if no item was displayed there, no item is selected (GetCurSel returns -1). An item selected with the keyboard updates the static portion or edit control portion immediately.

Notifications

The parent window receives the following notifications as WM_COMMAND messages:

NotificationSent when
SFTBOXN_SELCHANGEThe selected item displayed in the static portion or edit control portion has changed. This notification is sent when the user selects another item (by clicking an item in the dropdown portion, using the keyboard or typing text in the edit control portion) and also when the application changes the selection, for example using SetCurSel. It is not sent while the user merely moves the mouse cursor over the items of the dropdown portion.
SFTBOXN_SELENDOKThe user has accepted the selection while the dropdown portion was shown, for example by clicking an item, by pressing the Enter key or F4 or by clicking the dropdown button. The notification is sent before the dropdown portion is closed. An application can prevent the dropdown portion from closing by sending a WM_CANCELMODE message to the combo box while handling the notification.
SFTBOXN_SELENDCANCELThe dropdown portion has been closed without accepting an item, for example because the user pressed the Escape key or because the combo box lost the input focus.

SFTBOXN_SELENDOK and SFTBOXN_SELENDCANCEL are not sent by a simple combo box, as its list is always shown.

case WM_COMMAND:
    if (LOWORD(wParam) == IDC_BOX && HIWORD(wParam) == SFTBOXN_SELCHANGE) {
        LONG index = SftBox_GetCurSel((HWND) lParam);
        /* index is -1 if no item is selected */
    }
    break;

Selection Style

SetSelectionStyle defines how the selected item is highlighted, in the dropdown portion and in the static portion:

SFTBOX_SELECTION_ALLHighlights the entire item, including all cells, the label picture and item picture. This is the default.
SFTBOX_SELECTION_CELLSHighlights the cells only.
SFTBOX_SELECTION_CELL1Highlights the text in the first cell only.
SFTBOX_SELECTION_CELLCURRENTHighlights the entire cell in the first displayed column only.
SFTBOX_SELECTION_CELL1FULLHighlights the text in the first cell only. Identical to SFTBOX_SELECTION_CELL1, but the highlight extends to the top and bottom of the cell.
SFTBOX_SELECTION_OUTLINEThis value can be combined with one of the values above. The selection is rendered using a rounded outline rectangle with a gradient fill. GDI+ support is required, otherwise SFTBOX_SELECTION_OUTLINE is ignored.

The selection style only affects the visual representation. A combo box always selects an entire item, individual cells cannot be selected. The colors used for the selected item are defined using SetCtlColors (SFTBOX_COLORS structure), and can be overridden for individual columns and cells (SFTBOX_COLUMN and SFTBOX_CELL structures, colorBgSel and colorFgSel members).

Selection Without Input Focus

SetNoFocusStyle defines how the selected item is displayed in the static portion while the combo box does not have the input focus. In a simple combo box, the setting also applies to the list of items. The dropdown portion of a dropdown combo box or dropdown list combo box always highlights the selected item.

SFTBOX_NOFOCUS_KEEPSELThe selected item is highlighted the same way as when the combo box has the input focus, using the "no focus" selection colors of the SFTBOX_COLORS structure.
SFTBOX_NOFOCUS_FRAMEThe selected item is drawn as an item that is not selected, framed by a rectangle.
SFTBOX_NOFOCUS_NOTHINGThe selected item is drawn as an item that is not selected. This is the default.

Disabled Items

An item can be disabled using SetItemStatus. By default, the user can still select a disabled item. If the fSelectEnabledItemsOnly member of the SFTBOX_CONTROL structure is set to TRUE (see SetControlInfo), disabled items are skipped when the user selects items with the keyboard or by typing text, and clicking a disabled item in the dropdown portion does not close the dropdown portion. The functions that search for an item (FindString, SelectString, etc.) then also skip disabled items. An application can always select a disabled item using SetCurSel.


Last Updated 11/21/2026 - (email)
© 2026 Softel vdm, Inc.