# 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.

## Parameters

Input
Name | Type | Description
panelHandle | integer | Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID | integer | 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 NewCtrl or 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); Example GetTableCellFromValue (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); Example GetTableCellFromValue (panelHandle, controlID, beginningCell, MakeRect (2, 2, 5, 5), &cell, searchDirection, cellType, dataType, value);
searchDirection | integer | 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 | integer | 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.
Constant Name | Constant Value
VAL_CELL_NUMERIC | 0
VAL_CELL_STRING | 1
VAL_CELL_RING | 3
VAL_CELL_COMBO_BOX | 4
VAL_CELL_BUTTON | 5
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 | integer | 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.
Constant Name | Constant Value
VAL_CHAR | 0L
VAL_INTEGER | 1L
VAL_SHORT_INTEGER | 2L
VAL_FLOAT | 3L
VAL_DOUBLE | 4L
VAL_UNSIGNED_SHORT_INTEGER | 6L
VAL_UNSIGNED_INTEGER | 7L
VAL_UNSIGNED_CHAR | 8L
The function expects value to match the data type you specify.
value | any type (passed by 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 (passed by reference) | 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 | integer | Return value indicating whether the function was successful. A negative number indicates that an error occurred.
Code | Error Message String
xx | Success