SortTableCells
int SortTableCells (int panelHandle, int controlID, Rect cellRange, int sortingDirection, int keyIndex, int descending, CellCompareCallbackPtr comparisonFunction, void *callbackData);
Purpose
Sorts a group of cells in a table control. You must specify a row, or column, as the sort key and a cell range indicating what other rows, or columns, the function should move as the values in the key row, or column, move.
When the function swaps the values of two cells, it also swaps all attributes, such as colors, fonts, and types, of the two cells.
Supported Controls
You can use SortTableCells with table 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. |
| cellRange | Rect | A Rect structure specifying the cell range you want to sort. The Rect structure is defined as follows: typedef struct { int top; int left; int height; int width; } Rect; Pass the one-based row and column indices of the first cell in the range as the top and left fields of the structure, respectively. Pass the number of columns in the range as the width field of the structure, and the number of rows in the range as the height field of the structure. You can create a Rect without having to declare a variable by using the following function: Rect MakeRect (int top, int left, int height, int width); ExampleSetTableCellRangeVals (panelHandle, controlID, MakeRect (2, 3, 5, 5), valueArray, direction); |
| sortingDirection | int | Determines whether the function sorts the values in a
row or the values in a column. If you pass VAL_ROW_MAJOR, the function interprets keyIndex as a row index and sorts the values in that row. As the function moves the value of a given cell in the key row from one column to another, to match the sort criteria, the values of all other cells in the same column that are contained in the specified cell range also are moved to the same target column. If you pass VAL_COLUMN_MAJOR, the function interprets keyIndex as a column index and sorts the values in that column. As the function moves the value of a given cell in the key column from one row to another, to match the sort criteria, the values of all other cells in the same row that are contained in the specified cell range also are moved to the same target row. |
| keyIndex | int | The index of the row, or column, that contains the key values. The function interprets this index as that of a row or a column depending on the value of sortingDirection. The row, or column, specified must be included in cellRange. If comparisonFunction is NULL, all cells in the specified row, or column, and that also are contained in cellRange must be of the same cell type. In addition, their cell type cannot be VAL_CELL_PICTURE. |
| descending | int | Specify a nonzero value or select Yes in the function panel to sort the values in descending order. Specify 0 or select No in the function panel to sort the values in ascending order. |
| comparisonFunction | CellCompareCallbackPtr | The name of an optional cell comparison function that you can use to
perform custom sorts. This function (type CellCompareCallbackPtr) takes the following form: int CVICALLBACK FunctionName (int panelHandle, int controlID, Point item1, Point item2, void *callbackData); When SortTableCells 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 table control and two point structures corresponding to the two cells you need to compare. The Point structure is defined as follows: typedef struct { int x; int y; } Point; typedef struct { int x; int y; } Point; The x field of the structure contains the one-based column index of the cell, and the y field of the structure contains the one-based row index of the cell. This function also receives the value you pass to callbackData.To perform the comparison you can, if you choose, obtain the values of the two cells using GetTableCellVal, or of any other cells you can 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 SortTableCells performs the comparisons. In this case, all cells referenced by keyIndex that are also contained in cellRange must be of the same cell type. In addition, their cell type cannot be VAL_CELL_PICTURE. If the cell type is VAL_CELL_NUMERIC, SortTableCells promotes values of different data types to doubles before comparing them. |
| 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 5.5 and later
Example
Refer to userint\colview.cws for an example of using the SortTableCells function.