HeaderPane
Main
Hide
Share Link
Print

SortItems

Sorts items.

C

BOOL WINAPI SftBox_SortItems(HWND hwndCtl, LONG indexTC, int col, SFTBOX_SORTPROC lpfnCompare);

C++

BOOL CSftBox::SortItems(LONG indexTC, int col, SFTBOX_SORTPROC lpfnCompare);

Parameters

hwndCtl

The window handle of the combo box control.

indexTC

The zero-based index of the item whose immediate dependent items will be sorted. This parameter can be -1, in which case all items at level 0 are sorted.

col

The zero-based column number whose text is to be sorted. If col is not a valid column number, FALSE is returned and the items are not sorted.

lpfnCompare

A pointer to a comparison callback routine of type SFTBOX_SORTPROC. This parameter may be NULL, in which case items are sorted in ascending order of their cell text.

Returns

The return value is TRUE if the function was successful, otherwise FALSE is returned.

Comments

The SortItems function sorts items.

The callback routine lpfnCompare is called to compare two items. It receives the window handle of the combo box, the cell text of both items in the column col and the application-specific values of both items (see SetItemData). The callback returns -1 if the first item is smaller than the second item, 0 if the items compare as being equal and 1 if the first item is greater than the second item. An application can sort items based on their cell text or their application-specific values. The cell text passed to the callback routine can be NULL if no text has been defined for the cell.

If lpfnCompare is NULL, the cell text of the items is compared using the Windows function CompareString with the locale of the combo box (see SetLocale). This comparison is case sensitive.

Only immediate dependent items are sorted, i.e., the items on the level immediately below the item indexTC. Dependents of the items being sorted are moved with their parent item, but are not sorted. Use a separate SortItems call for each parent item whose dependent items are to be sorted. TRUE is returned if there are no items to sort.

The sorting algorithm used preserves the order of an already sorted list, when many items have identical keys. This allows multiple columns to be sorted by sorting the least significant column first and the most significant column last.

The selected item remains selected. As its position may change, its index may be different once the items have been sorted (see GetCurSel).

SortItemsEx can be used if the comparison also requires the application-specific values of the cells (see SFTBOX_CELL, cellData).

In a combo box control using a virtual data source, sorting functions cannot be used and an error is returned. The external virtual data source should be sorted instead.

Examples

C View entire sample code

    int column = SftBox_GetHeaderButton(hwndBox);
    SFTBOX_DWORD_PTR state = SftBox_GetUserData(hwndBox);
    int lastColumn = (int) LOWORD(state) - 1;
    BOOL fDescending = HIWORD(state) != 0;

    if (column < 0)
        return;
    fDescending = (column == lastColumn) ? !fDescending : FALSE;
    SftBox_SortItems(hwndBox, -1, column, fDescending ? SortDescending : SortAscending);
    SftBox_SetUserData(hwndBox, MAKELONG(column + 1, fDescending));
}

/**********************************************************************/
/*                         Current Selections                         */
/**********************************************************************/

C++ View entire sample code

    int column = box.GetHeaderButton();
    SFTBOX_DWORD_PTR state = box.GetUserData();
    int lastColumn = (int) LOWORD(state) - 1;
    BOOL fDescending = HIWORD(state) != 0;

    if (column < 0)
        return;
    fDescending = (column == lastColumn) ? !fDescending : FALSE;
    box.SortItems(-1, column, fDescending ? SortDescending : SortAscending);
    box.SetUserData(MAKELONG(column + 1, fDescending));
}

void CMainDlg::ShowStatus(const CSftBox& box)
{
    CString status;
    LONG index = box.GetCurSel();

See Also C/C++ API | Categories | Notifications


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