Table Widget Cell Attributes

The table widget supports a variety of cell attributes that you can apply either to the entire table or to a subset of its cells. You can set them at table creation with the WIDGET_TABLE function and change them after creation with the WIDGET_CONTROL procedure. You can also query for some of them with the WIDGET_INFO function. The following table describes the table cell attributes.

Attribute	Description
ALIGNMENT	Horizontal alignment of text within a cell (left, middle, right)
BACKGROUND_COLOR	Color of the background of a cell
EDITABLE	Indication of whether you can edit a cell
FONT	Font to use when drawing a cell’s text
FOREGROUND_COLOR	Color of the foreground of a cell
FORMAT	Formatting string to use when drawing a cell’s value

The following table indicates whether you can use these attributes with the widget creation (WIDGET_TABLE), modification (WIDGET_CONTROL), and querying (WIDGET_INFO) routines.

Attribute	WIDGET_TABLE	WIDGET_CONTROL	WIDGET_INFO
ALIGNMENT	Yes	Yes	No
BACKGROUND_COLOR	Yes	Yes	Yes
EDITABLE	Yes	Yes	Yes
FONT	Yes	Yes	Yes
FOREGROUND_COLOR	Yes	Yes	Yes
FORMAT	Yes	Yes	No

There are a few issues surrounding table widget attributes that you need to know, especially on Motif (UNIX) platforms. While it is expected that most users will not see any performance problems, you should consider the hardware limitations of your users’ systems.

One issue is that the more cells a table has, the more sluggish the table can be. You can mitigate this limitation by operating on as few cells as possible. For example, if you know that all cells have the same background color, WIDGET_INFO need only query for the background color of one cell.

Another issue involves color on Motif systems. Depending on the graphics system in use, there might be only a small number of distinct colors available for the table.

Setting Cell Attributes at Table Creation

You can set table cell attributes when you create the widget. The value can be either a scalar or an array of values. The application and default use of cell attributes depends on which type you choose in specifying the value. (For descriptive purposes here, consider a color value to be a scalar, although in reality it is a three-element vector of bytes.) Here are the two scenarios:

The value is specified as a scalar: Applied to all cells. Additionally, it becomes the table’s default value, used when new cells are created.
The value is specified as an array: Applied left to right, moving from the top row to the bottom row. The input array’s dimensions need not match the table’s dimensions. If the number of attribute value elements is insufficient for the number of cells, the values are recycled to apply to the cells, starting with the first value. If you supply more attribute values than there are cells, IDL does not use the remainder.

The following example shows how you can initialize a table to have the vintage look of alternating mint-green and white lines.

PRO minty_fresh

   tlb = WIDGET_BASE()

   rows = 5

   cols = 5

   ; Create 2-D array of background colors (3-D, actually)

   backgroundColors = MAKE_ARRAY( 3, cols, 2, /BYTE )

   backgroundColors[0,*,0] = 153   ; mint-green

   backgroundColors[1,*,0] = 255

   backgroundColors[2,*,0] = 204

   backgroundColors[*,*,1] = 255   ; white

   ; Create a table where every other line is mint-green

   table = WIDGET_TABLE( tlb, $

      BACKGROUND_COLOR = backgroundColors, $

      VALUE = INDGEN(cols,rows) )

   ; Realize the widgets

   WIDGET_CONTROL, tlb, /REALIZE

END

Note that in the example, only enough colors for the first two rows are specified. The table widget repeats the pattern for the remaining rows. Setting up a table with alternating column colors is even easier. To do so, you can create a table widget with the following line:

background_color = [ [153,255,204], [255,255,255] ]

If the example used this code, the table would have a checkerboard pattern because there are an odd number of columns.

The various types of cell attributes will try to convert input to the proper data type. The following table details the types and values that you should supply.

Attribute	Preferred Data Type	Value or Value Range
ALIGNMENT	BYTE	0, 1, or 2
BACKGROUND_COLOR	BYTE	RGB triplet whose elements are in the range of [0,255]
EDITABLE	BYTE	0 or non-zero
FONT	STRING	See Using Device Fonts
FOREGROUND_COLOR	BYTE	RGB triplet whose elements are in the range of [0,255]
FORMAT	STRING	See the FORMAT keyword of the PRINT procedure

For users of table widgets, the following are issues regarding cell attributes:

When a cell value is edited, the foreground and background colors revert to the system defaults for edit cells. The font remains the same.
At table creation, IDL automatically determines an optimal row height based on the fonts specified. However, an explicitly specified row height takes precedence. After creation, row heights do not automatically change when fonts change.
Row and column header cells have a limited set of attributes. Only foreground color and font can be set. Header cells are indexed by using -1. For example, the header for the third row is indexed by [-1,2], and the third column is indexed by [2,-1]. Actions on cell [-1,-1] are ignored.
On Windows, the number of distinct fonts is limited to 100. On UNIX systems, the table widget limits the number of distinct fonts to 1000 (although the user’s particular system might have limitations).

Changing Cell Attributes after Table Creation

After you create a table widget, you can change cell attributes with the WIDGET_CONTROL procedure. There are two attribute-changing scenarios to consider:

Attributes are applied to a rectangular region of cells. This occurs when all of the table’s cells are operated on because the USE_TABLE_SELECT keyword is not used, or occurs when that keyword is used and the table is in non-disjoint selection mode.

Regardless, an attribute keyword’s value can be a scalar or an array and is applied repeatedly to the targeted cells. If the array of values is exhausted, it is recycled by wrapping back to the first value. Excess values are not used. The values are applied to the cells row by row (i.e., each row is completed before the next row begins). The ordering is left to right and top to bottom.
Attributes are applied to a list of cells. This occurs when USE_TABLE_SELECT is used and the table is in disjoint selection mode. As in the previous scenario, an attribute keyword’s value can be a scalar or an array. In both cases, values are applied to cells by synchronously stepping through the list of cells and values. If the number of values is insufficient, IDL recycles them. IDL does not use excess values.

Note that when you specify scalar values, they do not replace the table’s defaults. You can set a table cell attribute’s defaults with the WIDGET_TABLE function. These defaults come into play when you use the INSERT_ROWS and INSERT_COLUMNS keywords for WIDGET_CONTROL. New cells will have the defaults unless you also supply attribute keywords to override them.

If you change fonts, the table does not adjust row or column sizes to better fit the new font. You can programmatically change cell sizes with the COLUMN_WIDTHS and ROW_HEIGHTS keywords.

Note: The ROW_HEIGHTS keyword works on Windows with the limitation that all rows receive the same height.

You can also change the column header’s height by specifying a value of -1 as the index for a cell’s row. Unlike value cells, the column header can have a height that is different from the value-cell heights. You can control the row header’s width by specifying -1 as the index for a cell’s column.

The following example code demonstrates how you can modify a table’s cell attributes. The example creates the table with all cells being editable, but changes that value so a rectangular region of six cells becomes uneditable (and are grayed out to indicate that).

PRO alternate_editability

   tlb = WIDGET_BASE()

   ; Create a table

   table = WIDGET_TABLE( tlb, $

      /EDITABLE, $              ; all cells are editable

      VALUE = INDGEN(5,5) )

   ; Change the widget

   WIDGET_CONTROL, table, $

      EDITABLE=0, $                       ; not editable

      BACKGROUND_COLOR=[223,223,223], $   ; gray them out

      USE_TABLE_SELECT=[1,1,3,2]          ; block of six cells

   ; Realize the widgets

   WIDGET_CONTROL, tlb, /REALIZE

end

IDL repeatedly applies the editability value and background colors to all six target cells. If the table were in disjoint selection mode, the USE_TABLE_SELECT line would look like this:

USE_TABLE_SELECT=[ [1,1], [2,1], [3,1], $

                   [1,2], [2,2], [3,2] ]

To apply the change to the current selection, /USE_TABLE_SELECT is sufficient.

Querying for Cell Attributes

You can retrieve certain table cell attribute values, thereby eliminating the need for the IDL programmer to independently keep track of these values. The WIDGET_INFO function can return information on the following cell attributes:

BACKGROUND_COLOR
EDITABLE
FONT
FOREGROUND_COLOR

The corresponding WIDGET_INFO keywords are preceded by “TABLE_” (e.g., TABLE_BACKGROUND_COLOR). You can query for only one attribute at a time. However, you can use the USE_TABLE_SELECT keyword conjunction with these attribute keywords to specify a set of cells to query. The following table shows how the dimensions of the returned variable depend on the table’s selection mode and the requested attribute.

Attribute Keyword	Table in Non-Disjoint Selection Mode; Selection Has M Columns and N Rows	Table in Disjoint Selection Mode; List of Selected Cells Has N Elements
TABLE_BACKGROUND_COLOR	3D array of bytes (3 x M x N)	2D array of bytes (3 x N)
TABLE_EDITABLE	2D array of bytes (M x N)	1D array of bytes (N)
TABLE_FONT	2D array of strings (M x N)	1D array of strings (N)
TABLE_FOREGROUND_COLOR	3D array of bytes (3 x M x N)	2D array of bytes (3 x N)

There is also a special case. If all values in the returned variable would be identical, USE_TABLE_SELECT returns a scalar (or a three-element array in the case of colors). This conglomeration preserves backward compatibility if you have used WIDGET_INFO to get a table’s editability. If cell editability is not uniform for the queried cells, WIDGET_INFO returns an array, and conditionals using the returned value could throw an error. Therefore, if you make use of individual cell editability, you should check and test your code for these possible errors.

Similar to the way attribute values are applied to cells, WIDGET_INFO fills the return variable in a row-by-row fashion or with a one-to-one correspondence if the table is in disjoint selection mode.

Finally, for those cells that have not been explicitly assigned a value for the queried attribute, WIDGET_INFO returns the default value. This value is the one specified by WIDGET_TABLE or, failing that, the system default.

Adding and Deleting Cells

You can add and delete table cells through a variety of methods. One is to use the WIDGET_CONTROL procedure’s row and column insertion and deletion keywords. Another is to change the table’s XSIZE or YSIZE attributes. You can also make the change by setting the table’s value. Regardless of the method, cell attributes shift appropriately with the change. Explicitly set row and column labels also shift, as do current column widths and row heights.

For example, suppose you insert a row above the current third row of an existing table by using the following statement:

WIDGET_CONTROL, myTable, $

   INSERT_ROWS = 1, $

   USE_TABLE_SELECT = [0,2,0,2]

After IDL executes this statement, the attributes of the first two rows are unchanged, and all of the other pre-existing rows have their attributes shifted down with them. Cells in the new row receive the table’s default cell attributes.

Product	IDL

Version	9.0