GetTableCellFromValue
int GetTableCellFromValue (int panelHandle, int controlID, Point beginningCell, Rect cellRange, Point *cell, int searchDirection, int cellType, int dataType, ...);
Purpose
Searches a specified cell range of a table control and returns the first cell in the range with a value matching the specified value.
This function returns a cell containing the indexes {0, 0} if the value is not found.
Supported Controls
You can use GetTableCellFromValue 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. | ||||||||||||||||||||||||||||||
| beginningCell | Point | A Point structure specifying the first cell the function searches.
This cell cannot be outside the range you pass to cellRange. The Point structure is defined as follows: typedef struct { int x; int y; } Point; Pass the one-based column index of the cell in the x field of the structure, and the one-based row index of the cell in the y field of the structure. You can create a Point without having to declare a variable by using the following function: Point MakePoint (int x, int y); ExampleGetTableCellFromValue (panelHandle, controlID, MakePoint (2, 3), cellRange, &cell, searchDirection, cellType, dataType, value); |
||||||||||||||||||||||||||||||
| cellRange | Rect | A Rect structure specifying the cell range you want the function to
search. This range must include the cell passed to beginningCell. If you want to search the entire table, you can pass the VAL_TABLE_ENTIRE_RANGE macro. 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); ExampleGetTableCellFromValue (panelHandle, controlID, beginningCell, MakeRect (2, 2, 5, 5), &cell, searchDirection, cellType, dataType, value); |
||||||||||||||||||||||||||||||
| searchDirection | int | The sequence by which the function searches the cells. If you pass VAL_ROW_MAJOR, the function searches all the cells in a given row from left to right, then it searches the row immediately below, continuing until it either finds a match or until there are no rows left in the cell range. If you pass VAL_COLUMN_MAJOR, the function searches all the cells in a given column from top to bottom, then it searches the column to its immediate right, continuing until it either finds a match or until there are no columns left in the cell range. |
||||||||||||||||||||||||||||||
| cellType | int | The cell type you want to search. The function searches only the cells that match this cell type. The following table lists the possible cell types.
Pass VAL_TEXT_CELL_TYPE (–2) if you want to search all cells that have text data (cells with text data are string cells, ring cells, combo box cells and button cells). Although VAL_CELL_PICTURE is a valid cell type, it is not an acceptable input for this function. The function never searches cells of this type. When searching combo box and ring cells, this function also searches through the value list of the cell. If you would rather not include these values in your search, you can use the function GetTableCellVal to determine whether the cell returned by this function holds the target string as its value or as a member of its value list. If the latter, you can then continue calling this function starting at the next cell, and iterate until it returns a cell that holds the target string as its actual value. The function expects value to match the cell type you specify. If the cell type is VAL_CELL_NUMERIC, value must be a number matching dataType, and if the cell type is other than VAL_CELL_NUMERIC, value must be a string. |
||||||||||||||||||||||||||||||
| dataType | int | The data type of value. If cellType is VAL_CELL_NUMERIC, the function searches only numeric cells that match the data type you specify. If cellType is other than VAL_CELL_NUMERIC, this data type is ignored. The following table lists the possible data types.
The function expects value to match the data type you specify. |
||||||||||||||||||||||||||||||
| value | ... | The value you want to locate in the cells. This value must match the cell type and data type you specify. | ||||||||||||||||||||||||||||||
| Output | ||||||||||||||||||||||||||||||||
| Name | Type | Description | ||||||||||||||||||||||||||||||
| cell | Point | A Point structure indicating the row and column of the cell matching
the specified value. The Point structure is defined as follows: typedef struct { int x; int y; } Point; The function writes the one-based column index of the matching cell into the x field of the structure, and the one-based row index of the matching cell into the y field of the structure. If the function cannot find the specified value, it returns a cell containing the indices {0, 0}. |
||||||||||||||||||||||||||||||
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