Issuu on Google+

Table Control Overview

Page 1 of 12

Table Control Overview Use table controls to enter or view data arrays. Each individual table cell can be one of six types: numeric, string, picture, ring, combo box, or button. The table cells can contain numeric, text, or image data. A sample table control appears in the following figure:

Operating Table Controls Programming Table Controls Table Control Attributes Table Control Functions Table Control Events

Operating Table Controls When you set a table control to any mode other than indicator mode, you can use the keyboard or the mouse to navigate through the table and change the values in its cells. A table has two distinct states of operation: selection state, which is the default state, and edit state. These states determine how LabWindows/CVI processes keyboard and mouse input. In the selection state, you can navigate through the table and select and/or make different cells active. In the edit state, you can change the value of a particular cell.

Selection State When the table is in selection state, you can operate the table cells using the keyboard in the following ways:     

Press the left, right, up, or down arrow keys to change the active cell. Press <Home> to make the first cell in the current row the active cell. Press <End> to make the last cell in the current row the active cell. Press <Page Up> or <Page Down> to scroll the table up or down one page. Press <Ctrl-Home> to make the first cell from the first row the active cell.

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

  

Page 2 of 12

Press <Ctrl-End> to make the last cell from the last row the active cell. Press <Space> to operate a button cell if it is active. Press <Space> to view the pull-down list of values for combo box and ring cells if they are active.

You can select a range of cells by holding down the <Shift> key as you move the active cell. When you select a range of cells, you also can perform operations such as sorting, searching, copying, and pasting, on a group of cells. You can use the mouse to select cells in the following ways: 

Click anywhere within the active cell to select it. If you hold down the left mouse button, you can select a range a cells by dragging the mouse over them. Click a row label to select all the cells within that row. Click a column label to select all the cells within that column. If you hold down the left mouse button, you can select multiple rows or columns by dragging the mouse over them. Click the upper left corner of the table to select all the cells in the table.

Edit State You can edit a cell only if it is not a picture cell, a ring cell, or a button cell; it is not dimmed; and it is not an indicator cell. Switch from selection to edit state by double-clicking an editable cell. If the active cell (the currently selected cell) can be edited, pressing <F2> also enables the edit state. If you enable ATTR_AUTO_EDIT, the table switches to edit state automatically when you being to type into a cell. When the table is in edit mode, the active cell owns the keyboard focus, and this is the only cell you can edit. Edit a string cell or combo box cell in the same way that you edit a text box control. Edit a numeric cell in the same way that you edit a numeric control. A numeric cell has optional up/down arrows that are visible only when you are editing the cell. You also can edit the cell by clicking these arrows. Note  You can type multi-line text into combo box cells, but the text does not appear as multi-line in the pull-down list. When the table is in edit state, you can use the keyboard to change the cell that you are editing in the following ways: 

  

Press <Enter> to edit the cell immediately below the current cell. If the current cell is the last cell of its column, the active cell becomes the first cell of the next column. If the current cell is the last cell of the last column, the table reverts to selection state. Press <Shift-Enter> to edit the cell immediately above the current cell. Press <Tab> to edit the cell immediately to the right of the current cell. Press <Shift-Tab> to edit the cell immediately to the left of the current cell.

To use the mouse to select a cell for editing, double-click the cell you want to edit. Note  You cannot edit picture cells, ring cells, or button cells. To return the table to selection state press <Esc> or click any cell other than the cell that you are editing. If you press <Esc>, the edits you made to the cell are not retained.

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

Page 3 of 12

Row and Column Sizing If you set the size mode of a row or a column to VAL_USE_EXPLICIT_SIZE, you can size that row or column by dragging the line that separates its label from the label of the next row or column. If you configure the table to not have visible row or column labels, you can still size its rows and columns by dragging the grid lines separating the cells themselves, but these lines have a much smaller sizing area than the lines that separate the row and column labels. If you double-click a row or column separator while you size it, the row or column automatically sizes itself to the minimum size required to accommodate the numeric values, text, or images in all its cells. You can disable row sizing and column sizing for the entire table programmatically.

Context Menu If you right-click anywhere on the table control, you activate a menu that contains predefined items, as well as items you specify. The following context menu items are predefined:  

Goto—Specify a target cell to move to, using its row and column indices. Find—Search all non-picture cells in the entire table, or in a selection range, for a text string. You also have the option to include the value list of ring and combo box cells in the search. After the initial search, you can press <F3> to find the next occurrence of the same text string, or you can press <Ctrl-F3> to search backwards for the next occurrence of the text string. Sort—If you select a range of cells, sort the cells in the range using the data in one of the rows or columns as the sort key.

Copying and Pasting When the table is in selection state, you can copy one or more cells to the clipboard. Press <Ctrl-C> to copy the selected cell(s). 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 one exception: if you select a single picture cell, then its image contents are placed in the system clipboard as a bitmap. LabWindows/CVI does not copy or paste button and ring cells. You can paste the contents of the system clipboard into a table control by pressing <Ctrl-V> after selecting the cell(s) into which you want to paste the data. 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 corresponding 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, select the

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

Page 4 of 12

cell and the press <Ctrl-V>.

Events If the control mode of the table control is hot or validate, a commit event is generated when you change the value of a cell or when you press a button cell. The table control also generates events when the active cell changes or the selection changes.

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.

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

Page 5 of 12

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. Note  To optimize performance and minimize the number of times that a table draws, use the  SetTableCellRangeVals and FillTableCellRange functions. These functions set the values of multiple table cells, so they are more efficient than calling SetTableCellVal multiple times. To minimize the number of times that a table draws, you can hide the table prior to calling SetTableCellRangeVals or SetTableCellVal. To hide the table, set ATTR_VISIBLE to 0. After you set the table cell values, set ATTR_VISIBLE to 1. Also, ensure that you do not call ProcessDrawEvents or ProcessSystemEvents while you update the table cell values.

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

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

Page 6 of 12

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.

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

Page 7 of 12

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 ASCII character, <LF>, 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. 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.

You must enable the DataSocket option in the Edit Installer dialog box Drivers & Components tab if your applications use data binding. Use 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 to disconnect the table cells from the DataSocket source. The data type of the control must match the data type in the DataSocket source.

Table Control Attributes

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

Page 8 of 12

The User Interface Library attributes that are valid for table controls appear in the following list:

Control Appearance

Cell Frame Color Column Labels Color Column Labels Height Command Button Color Disable Panel Theme First Visible Column First Visible Row Frame Color Grid Area Height Grid Area Left Grid Area Top Grid Area Width Height Hide Hilite Hilite Only When Panel Active Horizontal Grid Color Horizontal Grid Visible Horizontal Scroll Offset Horizontal Scroll Offset Max Inc/Dec Arrow Width Justification Left Minimum Number of Lines Visible Number of Visible Columns Number of Visible Rows Ring Arrow Location Row Labels Color Row Labels Width Scroll Bar Color Scroll Bar Size Show Ring Arrow Table Background Color Top Unique Ring Items Upper Left Corner Color Vertical Grid Color Vertical Grid Visible Vertical Scroll Offset Vertical Scroll Offset Max Visible Width Wrap Mode

Show/Hide Parts

                                        

 

Column Labels Visible Row Labels Visible

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

  

Page 9 of 12

Scroll Bars Show Inc/Dec Arrows

Text Style         

Text Background Color Text Bold Text Color Text Font Text Font Name Length Text Italics Text Point Size Text Strikeout Text Underline

Control Settings                                 

Auto Edit Case Sensitive Compare Cell Dimmed Cell Mode Cell Shortcut Key Cell Type Control Mode Control Style Data Type Default Numeric Cell Value Default Text Cell Value Default Text Cell Value Length Dimmed Enable Column Sizing Enable Popup Menu Enable Row Sizing Enter Key Causes Newline Fit Mode Inc/Dec Arrow Color Incremental Value Maximum Entry Characters Maximum Entry Length Maximum Value Minimum Value Next Panel Control No Edit Text Range Checking Tab Position Table Mode Table Run State Text Selection Length Text Selection Start Z-Plane Position

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

DataSocket Settings   

Page 10 of 12

DataSocket Enabled DataSocket Mode DataSocket Source

Format and Precision   

Format Padding Precision

Label Appearance

Label Background Color Label Height Label Left Label Raised Label Size to Text Label Text Label Text Length Label Top Label Visible Label Width

Label Style

        

         

Label Angle Label Bold Label Color Label Font Label Font Length Label Italics Label Justification Label Point Size Label Strikeout Label Underline

Source Code Connection      

Callback Data Callback Function Name Callback Function Name Length Callback Function Pointer Constant Name Constant Name Length

Table Control Functions

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

Page 11 of 12

The following User Interface Library functions operate on table controls. ClipboardGetTableVals GetTableCellRingIndexFromValue ClipboardPutTableVals GetTableCellRingValueFromIndex DefaultCtrl GetTableCellRangeVals DeleteTableCellRangeRingItems GetTableColumnFromLabel DeleteTableCellRingItems GetTableRowAttribute DeleteTableColumns GetTableRowFromLabel DeleteTableRows GetTableSelection DiscardCtrl GetUserEvent DiscardCtrlMenuItem HideBuiltInCtrlMenuItem DSBindCtrl InsertTableCellRangeRingItem DSBindTableCellRange InsertTableCellRingItem DSUnbind InsertTableColumns DuplicateCtrl InsertTableRows FillTableCellRange InstallCtrlCallback FreeTableValStrings NewCtrl GetActiveCtrl NewCtrlMenuItem GetActiveTableCell NewCtrlMenuSeparator GetCtrlAttribute PrintCtrl GetCtrlBoundingRect QueueUserEvent GetCtrlDisplayBitmap SetActiveCtrl GetCtrlMenuAttribute SetActiveTableCell GetNumTableCellRingsItems SetCtrlAttribute GetNumTableColumns SetInputMode GetNumTableRows SetCtrlMenuAttribute GetNumTableCellRingItems SetTableCellAttribute GetRelativeMouseState SetTableCellRangeAttribute GetScaledCtrlDisplayBitmap SetTableCellRangeVals GetTableCellAttribute SetTableCellVal GetTableCellFromPoint SetTableCellValFromIndex GetTableCellFromValue SetTableColumnAttribute GetTableCellRangeRect SetTableRowAttribute

Table Control Events The following User Interface Library events are sent to table control callback functions. EVENT_ACTIVE_CELL_CHANGE EVENT_COLUMN_SIZE_CHANGE EVENT_COMBO_BOX_INSERT EVENT_COMMIT

EVENT_LEFT_DOUBLE_CLICK EVENT_LOST_FOCUS EVENT_RIGHT_CLICK EVENT_RIGHT_DOUBLE_CLICK

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


Table Control Overview

Page 12 of 12

EVENT_DISCARD EVENT_ROW_SIZE_CHANGE EVENT_GOT_FOCUS EVENT_SELECTION_CHANGE EVENT_KEYPRESS EVENT_VAL_CHANGED EVENT_LEFT_CLICK EVENT_HSCROLL EVENT_VSCROLL EVENT_EDIT_MODE_STATE_CHANGE EVENT_MOUSE_POINTER_MOVE EVENT_LEFT_CLICK_UP EVENT_RIGHT_CLICK_UP EVENT_MOUSE_WHEEL_SCROLL EVENT_TABLE_ROW_COL_LABEL_CLICK

file://C:\Documents and Settings\Administrator\Local Settings\Temp\~hh6BCE.htm

1/31/2008


CVI Table Control Reference