WwTable Function

PV-WAVE Foundation > Reference Guide > Procedure and Function Reference: W > WwTable Function

WwTable Function

Creates an editable 2D array of cells containing string data, similar to a spreadsheet.

Usage

table = WwTable(parent, callback[, variable])

Input Parameters

parent — The widget ID of the parent widget.

callback — A procedure that is called when the contents of a cell are modified.

note	It is the calling routine’s responsibility to modify the appropriate variables when a table cell has been modified.

variable — (optional) A variable used to initialize the table cells. When this parameter is not supplied, the cells are initially empty, and the size of the table is set to the size specified by the Cols and Rows keywords. You can use the following types of variables with WwTable:

scalar

vector

2D array

structure with scalar fields or date/time structure field

All values are converted to type string within WwTable.

Returned Value

table — The widget ID of the table widget.

Keywords

Alignments — A one-dimensional array (0, ..., cols–1) of column alignments. Valid values are:

0 — Align cell contents to cell’s left edge (left justify).

1 — Center cell contents (center justify).

2 — Align cell contents to cell’s right edge (right justify).

Clabels — A one-dimensional string array (0, ..., cols–1) of column labels.

note	It is recommended that you specify row/column labels. Clicking MB2 on a row label selects the whole row; clicking MB2 on a column label selects the whole column.

Colors — Two-dimensional array (0, ..., rows–1, 0, ..., cols–1) of color indexes for table cells. This enables you to highlight particular groups of cells.

Cols — The number of columns in the table. If the Cols keyword is not specified, and the variable parameter is specified, the number of columns is calculated from the dimensions of variable. If neither Cols nor variable are specified, the size of the table is set to one column.

Cwidth — A one-dimensional array (0, ..., cols–1) of column widths. If not specified, the default column width is 10 characters.

Fixrows — The number of fixed rows in the table. Fixed rows are non-scrollable, non-editable cells that can serve as labels.

Fixcols — The number of fixed columns in the table. Fixed columns are non-scrollable, non-editable cells that can serve as labels.

note	You can specify Fixrows or Fixcols for a table, but not both.

Horizontal — If this keyword is present and nonzero, the contents of variable are displayed in natural fashion, i.e., variable rows are horizontal and columns are vertical. Horizontal is enabled by default. The Horizontal and Vertical keywords are mutually exclusive.

Name — A string specifying the name of the XbaeMatrix widget. The Name specified identifies the table widget name as part of the resource specification. Name can be used to define the column and row attributes in place of the Clabels and Rlabels keywords, although those keywords will take precedence if specified in addition to Name. (Default: table)

Position — If the widget is to be placed in a bulletin board layout, use this keyword (a two-element vector) to specify the x, y coordinates of the widget within the bulletin board.

Rlabels — A one-dimensional string array (0, ..., rows–1) of row labels.

Rows — The number of rows in the table. If the Rows keyword is not specified, and the variable parameter is specified, the number of rows is calculated from the dimensions of variable. If neither Rows nor variable are specified, the size of the table is set to one row.

Setcelldata — A copy of any PV‑WAVE variable to be passed as client data to the Setcells function.

Setcells — Allows you to name a PV‑WAVE function that is responsible for setting the values of the exposed cells. This function is called, like a callback, whenever cells are exposed (for example, as the user scrolls through the table). The function returns a string that is used to set the cell’s new value. The function’s input parameters are the table widget ID, client data specified with the Setcelldata keyword, number of optional parameters (always 2), the row, and the column of the exposed cell. If this function is specified, the variable parameter is ignored.

Using Setcells can improve performance when a large table is created. Ordinarily, when the table’s cells are populated by values taken from a single variable (the variable parameter), WwTable copies this variable first. When Setcells is used, only the values currently displayed are held in memory. See "Example 2" for more information on Setcells.

Vertical — If this keyword is present and nonzero, the contents of variable are displayed as transposed (variable rows are vertical and columns are horizontal). The Horizontal and Vertical keywords are mutually exclusive.

Visible — A two-element vector [row, column] specifying the number of rows and columns displayed. If the table size is bigger than the number of visible rows and columns, scrollbars are placed at the right and bottom edges of the window, so that you can view different portions of the table. If this keyword is not specified, four rows and four columns are displayed.

Color/Font Keywords

Background — Specifies the background color name.

Font — Specifies the name of the font used for text.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

Attachment Keywords

Bottom — If a widget ID is specified (for example, Bottom=wid), then the bottom of the widget is attached to the top of the specified widget. If no widget ID is specified (for example, /Bottom), then the bottom of the widget is attached to the bottom of the parent widget.

Left — If a widget ID is specified (for example, Left=wid), then the left side of the widget is attached to the right side of the specified widget. If no widget ID is specified (for example, /Left), then the left side of the widget is attached to the left side of the parent widget.

Right — If a widget ID is specified (for example, Right=wid), then the right side of the widget is attached to the left side of the specified widget. If no widget ID is specified (for example, /Right), then the right side of the widget is attached to the right side of the parent widget.

Top — If a widget ID is specified (for example, Top=wid), then the top of the widget is attached to the bottom of the specified widget. If no widget ID is specified (for example, /Top), then the top of the widget is attached to the top of the parent widget.

Get/Set Value

getvalue — Gets the Boolean array (0...rows–1, 0...cols–1) of selected cells. For information on cell selection, see the Discussion section.

setvalue — A two-element vector [row, column] specifying the cell to select.

Callback Parameters

Any table widget callback procedure must have the following three parameters:

wid — The table widget ID.

cell — A two-element vector [row, column] specifying the modified cell.

value — A string containing the new contents of the modified cell.

Discussion

Part of the resource specification for labeling the columns and rows can be specified using the Name keyword, otherwise the defaults are the *table.columnLabel and the *table.rowLabel resources, respectively (where columnLabel and rowLabel are the attributes).

note

The Clabels and Rlabels keywords provide a method for “hard-coding” the column and row labels (respectively) in the application. For greater flexibility, create a resource file containing the column and row labels using a text editor, and load the resource specifications using WtResource. The Name keyword can then be used in the WwTable calling sequence to specify the resources.

Selecting Cells for Editing

When a cell is selected for editing, it is considered the current cell. You can delete and add characters in the current cell using the keys on your keyboard.

To edit a cell, select it by clicking the left mouse button in the cell.

To edit cell to the left of the current cell, press the <Shift> and <Tab> keys at the same time.

To edit cell to the right of the current cell, press the <Tab> key.

To edit cell above the current cell, press the up arrow key.

To edit cell on the bottom of the current cell, press the down arrow key.

Selecting One or More Cells

This section describes how to select cells for operations other than editing.

To select a single cell, click the middle mouse button on the cell.

To extend the selection, press the <Shift> key and click the middle mouse button.

To deselect the cell, press the <Shift> and <Control> keys at the same time and click the middle mouse button.

To toggle the selection press the <Control> key and click the middle mouse button.

To select a rectangular region of cells, press the middle mouse button, drag the mouse, and then release the middle mouse button.

To select, deselect, extend, or toggle the selection of an entire row or column, click the middle mouse button (with appropriate keys listed above pressed) on the row or column label.

Example 1

The following example displays data stored in the phone_data variable in the save file:

WAVE_DIR/data/phone_example.sav

To restore this file, enter the following commands:

.RUN

RESTORE, !Data_Dir + 'phone_example.sav'

COMMON Tablecomm, phone_data

END

Callback Procedures

PRO tableCB, wid, which, text

   COMMON Tablecomm, phone_data

   PRINT, 'Table', which, text

   status = WwSetValue(wid, which)

   PRINT, WwGetValue(wid)

END

PRO ButtonCB, wid, data

   COMMON Tablecomm, phone_data

   PRINT, 'Table Selected'

   shell = WwMainWindow(wid, form, /Vertical, TITLE='Table')

   clrs = INTARR(N_TAGS(phone_data), N_ELEMENTS(phone_data))

   FOR i=0L, N_ELEMENTS(phone_data)-1 DO $

      clrs(*, i) = INDGEN(N_TAGS(phone_data)) * 20

      rlabs=STRTRIM(INDGEN(N_ELEMENTS(phone_data)), 2)

   table = WwTable(form, 'tableCB', phone_data, $

      Colors=clrs, Visible=[10, N_TAGS(phone_data)-4], $

      Clabels=TAG_NAMES(phone_data), Rlabels=rlabs, $

      /Vertical)

   status = WwSetValue(shell, /Display)

END

Widget Commands

top = WwInit('tble_ex', 'Examples', layout)

label = ['Table']

button = WwButtonBox(layout, label, 'ButtonCB')

status = WwSetValue(top, /Display)

WwLoop

Example 2

This example demonstrates the use of the Setcells and Setcelldata keywords. In this program fragment, the contents of table cells are set to the value of the row number times the column number.

Callback Procedures

FUNCTION settableCB, wid, data, n, r, c

   PRINT, data

   ; Return the string value of the product of row times column.

   RETURN, STRTRIM(STRING(r * c), 2)

END

PRO buttonCB, wid, data

   COMMON Tablecomm, phone_data

   PRINT, 'Table Selected'

   shell = WwMainWindow(wid, form, /Vertical, TITLE='Table')

   table = WwTable(form, 'tableCB', Visible=[10,5], $

      Rows=40, Cols=50, Setcells='settableCB')

   status = WwSetValue(shell, /Display)

END

Widget Commands

top = WwInit('tble_ex20', 'Examples', layout)

label = ['Table']

button = WwButtonBox(layout, label, 'buttonCB')

status = WwSetValue(top, /Display)

WwLoop