HeaderPane
Main
Hide
Share Link
Print

Expanding and Collapsing Items

If the items of a combo box control form a hierarchy (see item hierarchy), parent items can be expanded and collapsed. Expanding a parent item makes its immediate dependent items (the items on the next lower level) visible. Collapsing a parent item hides all its dependent items on all lower levels. The combo box manages all items as one list and takes care of hiding and showing items as needed, so an application expands and collapses items without having to add or remove items.

Expanding and Collapsing Under Program Control

FunctionDescription
ExpandExpands a parent item. The expand/collapse state of its dependent items, as saved by a previous call to Collapse, can be restored (fPreserve), or all dependent items on all levels can be expanded (fDepth). An index of -1 expands all items on level 0.
CollapseCollapses a parent item and optionally saves the expand/collapse state of its dependent items (fPreserve). An index of -1 collapses all items on level 0.
SetItemExpandExpands or collapses a parent item without preserving the expand/collapse state of its dependent items. When expanding, all dependent items on all levels can be expanded (fDepth). GetItemExpand returns whether an item is currently expanded.
SetItemExpandableMarks an item without dependent items as expandable, so it is shown like a collapsed parent item. Using SetItemExpandable with FALSE deletes the item's dependent items. GetItemExpandable returns whether an item is expandable.

In this example, all top level items are collapsed after the items have been added, then the dependent items of the first item are shown:

LONG i, count = SftBox_GetCount(hwndBox);
for (i = 0 ; i < count ; ++i) {
    if (SftBox_GetItemLevel(hwndBox, i) == 0)
        SftBox_Collapse(hwndBox, i, TRUE);
}
SftBox_Expand(hwndBox, 0, TRUE, FALSE);

When an item is added to a collapsed parent item, or when the level of an item is set and the item is not visible, its parent items are expanded automatically.

Expand/Collapse Buttons

Expand/collapse buttons are optional buttons shown in front of parent items, which allow the user to expand and collapse items using the mouse. SetShowButtons enables the expand/collapse buttons for items on all levels except level 0 and SetShowButton0 enables the buttons for items on level 0. A new combo box does not show expand/collapse buttons.

SetButtons defines the appearance of the expand/collapse buttons, which is shared by all items. It accepts one of the following predefined button styles or the handle of a bitmap with the button images (see SetButtons). All predefined styles except SFTBOX_BUTTON_STDWIDE and SFTBOX_BUTTON_LARGE also enable the expand/collapse buttons for items on all levels except level 0, as if SetShowButtons(TRUE) had been called.

SFTBOX_BUTTON_STANDARDSmall gray button with + and - symbols.
SFTBOX_BUTTON_STDWIDEWide gray button with + and - symbols.
SFTBOX_BUTTON_LARGELarge gray button with up and down symbols.
SFTBOX_BUTTON_SIMPLEWhite box with + and - symbols.
SFTBOX_BUTTON_MODERNThe button is not based on a bitmap, it is rendered by Windows.
SFTBOX_BUTTON_THEMEDA bitmap based button resembling a themed button. No actual Windows themes are used.
SFTBOX_BUTTON_AUTOMATIC, SFTBOX_BUTTON_AUTOMATIC2, SFTBOX_BUTTON_AUTOMATIC3The combo box selects a button style based on the Windows version and on whether Windows themes are used.
SftBox_SetTreeLineStyle(hwndBox, SFTBOX_TREELINE_AUTOMATIC);
SftBox_SetShowButtons(hwndBox, TRUE);               /* expand/collapse buttons (level 1..n) */
SftBox_SetShowButton0(hwndBox, TRUE);               /* expand/collapse buttons (level 0) */
SftBox_SetButtons(hwndBox, SFTBOX_BUTTON_AUTOMATIC);

Responding to the User

The combo box does not expand or collapse an item on its own when the user clicks an expand/collapse button. Instead, the parent window receives the SFTBOXN_LBUTTONDOWN_BUTTON notification (SFTBOXN_LBUTTONDBLCLK_BUTTON for a double-click) as a WM_COMMAND message and the application expands or collapses the item. GetExpandCollapseIndex returns the index of the item whose button was clicked. A click on an expand/collapse button or on the tree lines does not close the dropdown portion.

case SFTBOXN_LBUTTONDOWN_BUTTON:
case SFTBOXN_LBUTTONDBLCLK_BUTTON: {
    int index = SftBox_GetExpandCollapseIndex(hwndBox);
    if (index >= 0)
        SftBox_SetItemExpand(hwndBox, index, !SftBox_GetItemExpand(hwndBox, index), FALSE);
    break;
 }

The ItemImages sample (see Samples) handles the notifications this way. SetItemExpand is used in this example because it leaves the dropdown portion open. Expand, Collapse and the functions that add or delete items close the dropdown portion of a dropdown combo box or dropdown list combo box. An application that wants to use these functions while the dropdown portion remains open can suspend this behavior using the SftBox_RollupOnChangeOFF and SftBox_RollupOnChangeON macros (see SetRollupOnChange).

The SFTBOXN_LBUTTONDOWN_BUTTON notification is also sent when the user presses the Left arrow key on an expanded item or the Right arrow key on a collapsed parent item in a dropdown list combo box.

SetUpdateCaretExpandCollapse defines whether an item also becomes the selected item in the dropdown portion when its expand/collapse button is clicked.

Adding Dependent Items on Demand

An application does not have to add all items initially. It can add the parent items only and mark them as expandable using SetItemExpandable, without adding their dependent items. Such an item shows an expand/collapse button and the item picture of a collapsed parent item. When the application receives the SFTBOXN_LBUTTONDOWN_BUTTON notification for the item, it inserts the dependent items using InsertString and SetItemLevel, which also expands the item.

Tree Lines

Tree lines connect the items of a hierarchy. SetTreeLineStyle defines whether and how tree lines are drawn. A new combo box does not show tree lines.

SFTBOX_TREELINE_NONENo tree lines.
SFTBOX_TREELINE_SOLIDSolid tree lines. Items on level 0 are not connected to each other.
SFTBOX_TREELINE_DOTDotted tree lines. Items on level 0 are not connected to each other.
SFTBOX_TREELINE_DOT0Dotted tree lines. Items on level 0 are also connected to each other.
SFTBOX_TREELINE_TRANSPARENTTree lines are not shown, but the layout is calculated as if they were present. This only affects the horizontal indentation of levels.
SFTBOX_TREELINE_AUTOMATIC, SFTBOX_TREELINE_AUTOMATIC0Same as SFTBOX_TREELINE_TRANSPARENT.

The indentation of each level can be defined using SetIndentation and the color of the tree lines using SetCtlColors.

In a dropdown list combo box, the static portion shows the selected item indented according to its level and with its tree lines if the fStaticAligned member of the SFTBOX_CONTROL structure is TRUE, which is the default. If fStaticAligned is FALSE, the selected item is shown without indentation and tree lines.

Transition Effect

The iMouseOverTransitionEffect member of the SFTBOX_CONTROL structure (see SetControlInfo) defines whether the expand/collapse buttons and tree lines become visible gradually when the mouse cursor enters the combo box and are hidden gradually when it leaves. Expand/collapse buttons or visible tree lines must be enabled, otherwise the setting has no effect. GDI+ support is required for transition effects.

SFTBOX_TRANSITION_NONENo transition effect is used.
SFTBOX_TRANSITION_THEMEDVISTAONLY_NOFOCUSA transition effect is used when Windows themes are used and the combo box does not have the input focus. This is the default.
SFTBOX_TRANSITION_THEMEDVISTAONLYA transition effect is used when Windows themes are used.
SFTBOX_TRANSITION_ALWAYS_NOFOCUSA transition effect is used when the combo box does not have the input focus.
SFTBOX_TRANSITION_ALWAYSA transition effect is always used.

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