HeaderPane
Main
Hide
Share Link
Print

Items

An item (also called row) is one entry in the list of a combo box control. It consists of the row header, the label picture and item picture, the tree lines and expand/collapse button and one cell for each column. The items are managed by the dropdown portion. The item that is selected is also displayed in the static portion or edit control portion (see current selection).

Adding and Deleting Items

Items are added using AddString, which adds an item at the end of the list, and InsertString, which inserts an item at a given position (an index of -1 adds the item at the end). The string supplied becomes the cell text of column 0 and both functions return the index of the new item. DeleteString deletes an item, DeleteDependents deletes all dependent items of an item and ResetContent deletes all items. GetCount returns the number of items. MoveItem and CopyItem move or copy an existing item to a new position.

LONG index = SftBox_AddString(hwndBox, TEXT("Florida"));  /* text of column 0 */
SftBox_SetText(hwndBox, index, 1, TEXT("FL"));            /* text of column 1 */
SftBox_SetText(hwndBox, index, 2, TEXT("Tallahassee"));   /* text of column 2 */

If the dropdown portion of a dropdown combo box or dropdown list combo box is shown while items are added or deleted, it is closed first. This can be changed using SetRollupOnChange.

When many items are added or deleted, the WM_SETREDRAW message should be used to suppress redrawing: send WM_SETREDRAW (FALSE) once, add all items, then send WM_SETREDRAW (TRUE). This avoids significant processing and greatly reduces the time needed.

If the application needs to be notified when an item is deleted, for example to free memory it has associated with the item, a callback function can be defined using SetDeleteCallback. The callback is called immediately before an item is deleted, for each item that is deleted.

The Item Index

All functions that access a particular item use the item index. This is a zero-based number describing the item's position in the list: the first item has index 0, the second item has index 1, etc. The index of an item changes when items are inserted or deleted before it. Items that are currently not visible because their parent item is collapsed keep their position in the list and are included in the numbering.

Several functions accept an index of -1 to describe the selected item, for example GetText and GetTextLength.

Item IDs

In some cases it is easier to work with a value that identifies an item no matter where it is located in the list. When an item is added, it is automatically assigned a unique item ID, which does not change during the lifetime of the item. GetItemID returns the ID of an item and GetItemIndex returns the current index of the item with a given ID.

SFTBOX_ID savedID;
LONG index;
index = SftBox_AddString(hwndBox, TEXT("Category 1"));
savedID = SftBox_GetItemID(hwndBox, index);
. . . other items are added, inserted and deleted
index = SftBox_GetItemIndex(hwndBox, savedID); /* the current index of "Category 1" */

Levels and Hierarchy

The items of a combo box can form a hierarchy. The hierarchy is defined by the level of each item. A new item is at level 0, the root level. SetItemLevel changes the level of an item and GetItemLevel returns it. Levels range from 0 to SFTBOX_MAXLEVELS. An item is a dependent of the closest preceding item with a lower level, so all an application has to do is add the items in order and set their levels. The combo box determines the relationships between items and draws the tree lines (see Expanding and Collapsing Items).

index = SftBox_AddString(hwndBox, TEXT("Fruit"));       /* level 0 */
index = SftBox_AddString(hwndBox, TEXT("Apples"));
SftBox_SetItemLevel(hwndBox, index, 1);                 /* a dependent of "Fruit" */
index = SftBox_AddString(hwndBox, TEXT("Oranges"));
SftBox_SetItemLevel(hwndBox, index, 1);                 /* another dependent of "Fruit" */
index = SftBox_AddString(hwndBox, TEXT("Vegetables"));  /* level 0 */

The following terms and functions describe the relationships between items:

TermDescription
Parent itemAn item which has dependent items, or which has been marked as expandable using SetItemExpandable. GetParent returns the index of an item's parent item (-1 if the item has no parent item).
Top parentA parent item which has no parent of its own. GetTopParent returns the top parent of an item.
Dependent itemsThe items that follow a parent item and are on a lower level. GetDependent returns the first or last immediate dependent of an item (SFTBOX_DEPENDENT_FIRST, SFTBOX_DEPENDENT_LAST) and GetDependentCount returns the number of dependents, optionally including the dependents on all lower levels.
SiblingsItems on the same level with the same parent item. GetSibling returns the first, last, previous or next sibling of an item (SFTBOX_SIBLING_FIRST, SFTBOX_SIBLING_LAST, SFTBOX_SIBLING_PREV, SFTBOX_SIBLING_NEXT).
Leaf itemAn item without dependent items.

Cell Text

Each item has one cell for each column. SetText defines the text of a cell and GetText and GetTextLength retrieve it, using the item index and the column number. Other cell attributes such as colors, font, cell picture and alignment are defined using SetCellInfo and the SFTBOX_CELL structure. Changes to the selected item are reflected in the static portion or edit control portion.

Item Data

An application can associate a value with each item using SetItemData and retrieve it using GetItemData. The value is not used by the combo box. It typically is a pointer or an index into the application's own data. FindItem searches for the item with a given value. A value can also be associated with each cell (cellData member of the SFTBOX_CELL structure).

Enabling and Disabling Items

SetItemStatus enables or disables an item and GetItemStatus returns the current status. A disabled item is drawn grayed. By default, a disabled item can still be selected by the user. If the fSelectEnabledItemsOnly member of the SFTBOX_CONTROL structure is set to TRUE (using SetControlInfo), the user can only select enabled items. An application can always select a disabled item using SetCurSel.

Showing and Hiding Items

An item is not visible if one of its parent items is collapsed. GetItemShown returns whether an item is visible. SetItemShown makes an item visible by expanding all its parent items, or hides it by collapsing its immediate parent item, which also hides all other dependent items of that parent item. The items remain in the list. Items without a parent item (level 0) are always visible and cannot be hidden. GetNextShown and GetPrevShown return the next or previous visible item, which can be used to enumerate the items the way the user sees them.


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