SortTreeItems
int SortTreeItems (int panelHandle, int controlID, int siblingIndex, int keyColumnIndex, int descending, int sortSubTrees, TreeCellCompareCallbackPtr comparisonFunction, void *callbackData);
Purpose
Sorts all the siblings of a specified tree item. You must specify a column as the sort key.
When the function swaps the two items, it also swaps all attributes, such as colors, fonts, and types, of the two items and the cells they contain.
Supported Controls
You can use SortTreeItems with tree controls.
Parameters
| Input | ||
| Name | Type | Description |
| panelHandle | int | Specifier for a particular panel that is currently in memory. You can obtain this handle from functions such as LoadPanel and NewPanel. |
| controlID | int | The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by functions such as NewCtrl and DuplicateCtrl. |
| siblingIndex | int | Zero-based index of an item whose siblings you want to sort. |
| keyColumnIndex | int | The index of the column that contains the key values. |
| descending | int | Specify a nonzero value or select Yes in the function panel to sort the items in descending order. Specify 0 or select No in the function panel to sort the items in ascending order. |
| sortSubTrees | int | Specify a nonzero value or select Yes in the function panel to sort the subtree of each sorted item. Specify 0 or select No in the function panel if you do not want to sort subtrees. |
| comparisonFunction | TreeCellCompareCallbackPtr | The name of an optional tree cell comparison function that you can use to perform custom sorts. This function (type TreeCellCompareCallbackPtr) takes the following form: int CVICALLBACK FunctionName (int panelHandle, int controlID, int item1, int item2, int keyCol, void *callbackData); When SortTreeItems needs to compare two cells, it calls your function and allows you to perform the comparison. Your function receives the panelHandle and controlID of the tree control and two item indices corresponding to the two items you need to compare. This function also receives the value you pass to callbackData. To perform the comparison you can, if you choose, obtain the labels of the two cells using GetTreeCellAttribute and ATTR_LABEL_TEXT, or of any other cells you choose to use as secondary sort keys. Return –1 if item1 is less than item2, 1 if item1 is greater than item2, and 0 if item1 and item2 are equivalent. If you choose not to use a custom comparison function, you can pass NULL and SortTreeItems performs a case-sensitive string comparison on the labels. |
| callbackData | void * | If you perform the cell comparisons through a callback function, you can provide a pointer to user-defined data. If you do not need to pass user-defined data to the callback function, or if you are not using a callback function to perform the comparisons, you can use a value of zero. |
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful. A negative number indicates that an error occurred. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 7.0 and later
Example
Refer to userint\treeList.cws for an example of using the SortTreeItems function.