# Programming with Table Controls

You can use the table control functions to create, control, and interact with a table control programmatically.

## Creating and Deleting Cells

You can create an arbitrary number of rows and columns on a table control. As you do so, you create table cells that store the data within the table control.

Use the following functions to control the number of rows in a table control: InsertTableRows, DeleteTableRows, and GetNumTableRows. InsertTableColumns, DeleteTableColumns, and GetNumTableColumns control the number of columns.

## Cell Selection

If you want to set the active cell programmatically, use SetActiveTableCell. To select a range of cells, call SetTableSelection, which makes the top-left cell in the selection the active cell.

| Note The table selection is distinct from the active cell, and whereas there always exists an active cell (that is, the cell holding the keyboard focus), the selection consists of a rectangular cell range that can be empty. The only relationship between the active cell and the selection is that, if the selection is non-empty, the active cell is always contained within the selection.

## Cell Values

Each cell has one of the following types associated with it:

- Numeric—Contains numeric data.
- String—Contains text data.
- Picture—Contains image data.
- Ring—Contains a list of items from which you can select a cell value.
- Combo box—Contains text data and a list of items from which you can select a cell value. You also can enter your own values in combo box cells.
- Button—Contains a label that you can press.

The cell type determines what type of data you can store in each cell: numeric, text, or bitmap image.

You can change the cell type to store all three types of values simultaneously in one cell, but only the value corresponding to the current cell type is visible and operable. For example, if you have a numeric cell with a value of 2.0 and you change that cell to be a string cell with a value of hello, when you change the cell back to a numeric cell, the value of the numeric cell remains 2.0.

Button, ring, combo box, and string cells can share the same string value, which means that changing a cell from one of these types to another does not change the value of the cell. Because values that appear in a ring cell must exist in the value list of the ring cell, if you change a cell type to a ring cell, its value might be changed to the first item in the value list.

You can set and get the value of a cell directly, or you can set and get the values of a range of cells, such as those of an entire row or a group of rows. Set the values of a range of cells in one of the following ways:

- To set the values from an array containing the new value of each cell, use SetTableCellRangeVals.
- To set the values from a single value that you want to propagate through each cell in a range, use FillTableCellRange.

To get the values from a range of cells, use GetTableCellRangeVals.

To set and get the values of a range of cells, all cells in the range that you specify must be of the same cell type: VAL_CELL_NUMERIC, VAL_CELL_PICTURE, or VAL_TEXT_CELL_TYPE. Cells of type VAL_TEXT_CELL_TYPE are VAL_CELL_STRING, VAL_CELL_BUTTON, VAL_CELL_RING, and VAL_CELL_COMBO_BOX. If the type is VAL_CELL_NUMERIC, the cells in the range you specify also must have the same data type.

To set and get the value of a single cell, use SetTableCellVal and GetTableCellVal.

### List of Values

Ring and combo box cells contain lists of values that the end user can select from. When you set the value of a ring cell, the value that you set must already exist in this list. If you want to obtain the index of the items selected as the cell value, call GetTableCellVal and then GetTableCellRingIndexFromValue. You can configure these items programmatically using functions such as InsertTableCellRingItem, InsertTableCellRangeRingItem, DeleteTableCellRingItems, and DeleteTableCellRangeRingItems.

## Cell, Row, and Column Attributes

You can set attributes for each individual cell using SetTableCellAttribute and SetTableCellRangeAttribute. Cell attributes can be specific to a given cell type, or they can apply regardless of cell type. Essentially any attribute that you can set on a numeric control, a text box control, or a picture control, you also can set on a table cell. Typical examples of cell attributes that you can set are visibility of the horizontal gridline, background color of the cell, and floating point precision.

You can set row and column attributes using SetTableRowAttribute and SetTableColumnAttribute. Examples of row and column attributes are the column width and whether to replace numeric row labels with custom strings.

## Cell Attribute Inheritance

When you insert new rows and columns in the table, the new cells are created with an initial set of attributes. Depending on how you are using the table, you might want the initial state of new cells to match the state of its neighboring cells in the same column, its neighboring cells in the same row, or neither. The table attribute ATTR_TABLE_MODE determines how new cells inherit their initial, default set of attributes: from their parent row, their parent column, or the table itself.

Any attribute that you can set using SetTableCellAttribute or SetTableCellRangeAttribute also can be set as a row, column or table attribute, using SetTableRowAttribute, SetTableColumnAttribute, or SetCtrlAttribute, respectively. When you set a cell attribute on a row, and the table mode is set to VAL_ROW, the row preserves this attribute value as a "master" to be used as the initial value of the corresponding attribute on any new cells you create for that row. Similarly, cell attributes set on a column are used on new cells when the table mode is set to VAL_COLUMN. Cell attributes set on the table itself are used on new cells when the table mode is set to VAL_GRID.

## Searching and Sorting

If you want to locate a particular cell value anywhere in the table, use GetTableCellFromValue. GetTableRowFromLabel and GetTableColumnFromLabel perform a similar function on the row and column labels.

GetTableCellFromValue also searches through the item list of ring and combo box cells. If you want to ignore these values, compare the string to the value returned by GetTableCellVal.

SortTableCells sorts a range of cells using the data in one of the rows or columns as the sort key. You can pass in a callback function that LabWindows/CVI calls whenever it must compare the values of any two cells, thus allowing you to customize the sort.

## Copying and Pasting

You can copy one or more cells to the clipboard using ClipboardPutTableVals. When the data appears in the system clipboard the <Tab> ASCII character separates the data of each cell, and the linefeed ASCII character, <LF>, separates the data of each row.

LabWindows/CVI skips picture cells when it copies cells to the clipboard, with the following exception: if you pass a range consisting of a single cell to ClipboardPutTableVals, and that cell is a picture cell, then the image contents of the cell are placed in the system clipboard as a bitmap image. LabWindows/CVI does not copy or paste button and ring cells.

You can paste the contents of the system clipboard into a table control using ClipboardGetTableVals. LabWindows/CVI assumes that the <Tab> ASCII character separates the data that corresponds to each cell, and that the linefeed, <LF>, ASCII character separates the data that corresponds to each row.

When the data in the clipboard includes an empty cell or cells, the paste operation makes no change to the corresponding cell or cells in the table that receives the new data. Similarly, when the data in the clipboard includes cells that contain data that cannot be converted to a valid number, the paste operation does not change to the corresponding cell or cells in the table that receives the new data.

If there is a bitmap image in the system clipboard and you want to paste it into a picture cell, pass a cell range containing only that cell to ClipboardGetTableVals.

## Context Menu

To customize the table control context menu, insert menu items corresponding to tools you want to make available to the operator of the table. For each menu item, specify a callback function and an item label using NewCtrlMenuItem. Whenever the menu item is selected, LabWindows/CVI calls the corresponding callback function.

In addition to inserting your own menu items, you can remove the built-in items (Goto, Find, and Sort). Use HideBuiltInCtrlMenuItem and ShowBuiltInCtrlMenuItem to control the visibility of these items.

You also can use control menu attributes to configure context menus. Call GetCtrlMenuAttribute and SetCtrlMenuAttribute to get and set these attributes.

## Data Binding

Linux Data binding is not supported on Linux.

You can bind table controls to a DataSocket source. Controls can have only one DataSocket connection. You must specify whether the access mode is READ mode or WRITE mode, which are defined as follows:

- READ mode—The control gets data from the DataSocket source. In READ mode, the value of the table control is updated automatically when the value changes at the source.
- WRITE mode—The control transfers data to the DataSocket source. In WRITE mode, the value at the DataSocket source is updated automatically when the value of the table control changes.

Use DSBindTableCellRange DSBindTableCellRange to bind a range of table cells to a DataSocket source. Table cells must be of the same cell type and data type, and picture cells cannot be part of the range. Data is sent to and received from the DataSocket source as a 2D array of data. Data also can be received from the DataSocket source as a 1D array and is written to the table in row-major order. Use DSUnbind DSUnbind to disconnect the table cells from the DataSocket source.

The data type of the control must match the data type in the DataSocket source.

You must enable the DataSocket option in the Edit Installer dialog box Drivers & Components Drivers & Components tab if your applications use data binding.