WwTableUtils Function

Reference Guide > W Routines > WwTableUtils Function

Manages the contents of a table widget.

Usage

status = WwTableUtils(wid[, param1, ..., param9])

Input Parameters

wid — The widget ID of a WwTable widget.

param1, ..., param9 — (optional) These parameters depend on keyword use in the function calling sequence. See Keywords for more information.

Returned Value

status — A value indicating success or failure of the WwTableUtils call.

1 — Indicates success.

0 — Indicates failure.

Keywords

Add — Add specified rows or columns to the table at the specified position. This keyword must be used with either the Columns or the Rows modifier keywords.

If the Columns modifier keyword is used, you must specify all of the following parameters:

param1 — The column before which new columns are added.

param2 — A 2D string array of column values.

param3 — The number of columns to be added.

param4 — A 1D array of column widths.

param5 — A 1D array of column labels.

param6 — A 1D array of column maximum lengths.

param7 — A 1D array 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).

param8 — A 1D array of column label alignments. Valid values are:

0qQAlign 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).

param9 — A 2D array of column cell colors.

If the Rows modifier keyword is used, you must specify all of the following parameters:

param1 — The row before which new rows are added.

param2 — A 2D string array of row values.

param3 — The number of rows to be added.

param4 — A 1D array of row labels.

param5 — A 2D array of row cell colors.

CancelEdit — If nonzero, cancels the edit made to the currently edited cell. (See the Edit keyword.)

CommitEdit — If nonzero, commits the edit made to the currently edited cell. (See the Edit keyword.)

Delete — Deletes specified rows or columns from the table at the specified position. This keyword must be used with either the Columns or the Rows modifier keywords. If you use the Delete keyword, you must also specify the following parameters:

param1 — (long) The position (row or column) in the table to begin deleting.

param2 — The number of rows or columns to delete.

Deselect — Deselects specified rows or columns. If the All modifier keyword is used with Deselect, all rows and columns are deselected. If used with the Rows or Columns modifier keywords, the specified rows or columns are deselected, and the following parameter must be specified:

param1 — Index of row or column to deselect.

Edit — If nonzero, begin editing at the specified row and column. If used with the Cell modifier keyword, begin editing at the specified cell. If you use the Edit keyword, you must also specify the following parameters:

param1 — Row of the cell to edit.

param2 — Column of the cell to edit.

Get — If used with the Cell modifier keyword, WwTableUtils returns the value of the specified cell (not 1 or 0). The parameters param1 and param2 must be used:

param1 — Row of the cell to get.

param2 — Column of the cell to get.

If used with the Visible modifier keyword, returns the rectangle of a visible cell, and the following parameters must be used:

param1 — (output) The top row of the cell.

param2 — (output) The bottom row of the cell.

param3 — (output) The left column of the cell.

param4 — (output) The right column of the cell.

Make — Makes the specified cell visible. This keyword must be used with the Visible modifier keyword, and you must also use the following parameters:

param1 — The row of the cell to make visible.

param2 — The column of the cell to make visible.

Redraw — Redraws the specified cell. This keyword must be used with the Cell modifier keyword, and you must also use the following parameters:

param1 — The row of the cell to redraw.

param2 — The column of the cell to redraw.

Select — If used with the Columns or Rows modifier keywords, selects the specified rows or columns, and the following parameter must be used:

param1 — The index of the row or column to select.

If used with the Cell modifier keyword, selects specified cells, and the following parameters must be specified:

param1 — The row of the cell to select.

param2 — The column of the cell to select.

Set — Sets the value or color of a cell or column. This keyword must be used with the Cell, or Color and Rows, or Color and Columns modifier keywords.

If you use Set with the Cell modifier keyword, you must specify the following parameters:

param1 — The row of the cell to set.

param2 — The column of the cell to set.

param3 — The new value of the specified cell.

If you use Set with the Color and Rows modifier keywords, you must specify the following parameters:

param1 — The row at which to start setting colors.

param2 — A 2D array of new color table indices for rows.

param3 — The number of colors in the Color array.

If you use Set with the Color and Columns modifier keywords, you must specify the following parameters:

param1 — The column at which to start setting colors.

param2 — A 2D array of new color map indices for columns.

param3 — The number of elements in the Color array.

Modifier Keywords

These modifier keywords must be used in conjunction with the keywords listed.

All — When nonzero, deselects all cells in the table.

Cell — When nonzero, selects, deselects, edits, gets, or sets the color of the specified cell.

Columns — When nonzero, adds, deletes, deselects, or selects columns from the table.

Color — When nonzero, sets cell or column colors.

Rows — When nonzero, adds, deletes, deselects, or selects rows from the table.

Visible — When nonzero, obtains visible cells or makes cells visible.

Discussion

This function facilitates the portability between Microsoft Windows and X Windows applications.

Examples

The following ten code fragments demonstrate various uses of the WwTableUtils function.

(1) Add rows to a table

new_strings = STRTRIM(LONARR(numcols, numrows), 2)

new_rlabels = STRTRIM(LINDGEN(numrows) + start_row, 2)

status = WwTableUtils(tbl_wid, $

   start_row, $      ; add after this row

   new_strings, $    ; use '0' strings

   numrows, $        ; number of new rows

   new_rlabels, $    ; new row labels

   /Add, /Rows)

(2) Delete rows from a table

status = WwTableUtils(tbl_wid, $

   start_row, $    ; start location

   numrows, $      ; number of rows to delete

   /Delete, /Rows)

(3) Add columns to a table

new_strings = STRTRIM(LONARR(numcols, numrows), 2)

new_clabels = STRTRIM(LINDGEN(numcols) + start_column, 2)

new_colwidths = LONARR(numcols) + 10

status = WwTableUtils(tbl_wid, $

   start_column, $    ; add after this column

   new_strings, $     ; use '0' strings

   numcols, $         ; number of new columns

   new_colwidths, $   ; new column widths

   new_clabels, $     ; new column labels

   /Add, /Columns)

(4) Delete columns from a table

status = WwTableUtils(tbl_wid, $

   start_column, $    ; start location

   numcols, $         ; number of columns to delete

   /Delete, /Columns)

(5) Get visible cells

status = WwTableUtils(tbl_wid, top_row, bottom_row, $

   left_column, right_column, /Get, /Visible)

(6) Set the value of an individual cell

status = WwTableUtils(tbl_wid, row, col, value, /Set, /Cell)

(7) Redraw a cell

status = WwTableUtils(tbl_wid, row, col, /Redraw, /Cell)

(8) Deselect all cells

status = WwTableUtils(tbl_wid, /Deselect, /All)

(9) Select a cell

status = WwTableUtils(tbl_wid, row, col, /Select, /Cell)

(10) Make a cell visible

status = WwTableUtils(tbl_wid, row, col, /Make, /Visible)