Edit

ListView_SortItemsEx macro (commctrl.h)

  • Article

Uses an application-defined comparison function to sort the items of a list-view control. The index of each item changes to reflect the new sequence. You can use this macro or send the LVM_SORTITEMSEX message explicitly.

Syntax

void ListView_SortItemsEx(
   hwndLV,
   _pfnCompare,
   _lPrm
);

Parameters

hwndLV

Type: HWND

A handle to the list-view control.

_pfnCompare

Type: PFNLVCOMPARE

A pointer to an application-defined comparison function. It is called during the sort operation each time the relative order of two list items needs to be compared.

_lPrm

Type: LPARAM

The application-defined value that is passed to the comparison function.

Return value

None

Remarks

The comparison function has the following form.

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2, LPARAM lParamSort);

where lParam1 is the index of the first item and lParam2 the index of the second. The ListView_SortItemsEx's lParamSort parameter is passed to the callback function as its third parameter.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

You can send an LVM_GETITEMTEXT message to retrieve further information on an item, if needed.

This macro is similar to ListView_SortItems, except for the type of information passed to the comparison function. With ListView_SortItemsEx, the item's index is passed instead of its lparam value.

Note   During the sorting process, the list-view contents are unstable. If the callback function sends any messages to the list-view control aside from LVM_GETITEM (ListView_GetItem), the results are unpredictable.
 

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header commctrl.h