|
|
IDL Reference Guide: IDL GUIBuilder Widget Reference |
|
Table widgets display data and allow for data editing by the user. Tables can have one or more rows and one or more columns.
When programming in IDL, you create table widgets using the WIDGET_TABLE function. For more information, see WIDGET_TABLE.
For table widgets, you can set common attributes and table-specific attributes. For a list of common attributes, see Common Attributes. These are the table widget-specific attributes:
The Alignment attribute specifies how the text is aligned in the cells. These are the possible values:
In the generated *.pro file, this value is specified with the ALIGNMENT keyword to the widget creation routine.
The Column Labels attribute specifies the labels for the table columns. By default, this value is set to empty strings, but you can set it to any set of strings. To set the labels for table rows, use the Row Labels attribute.
To enter more than one string in the Value field, type in a string, then press Control+Enter (at the end of each line). This moves you to the next line, or the next label for a column. When you have entered as many labels as you want, press Enter to set the values.
In the generated *.pro file, this value is specified with the COLUMN_LABELS keyword to the widget creation routine.
The Disjoint Selection attribute determines whether the user is allowed to select multiple, unconnected cell regions within the table. By default, this value is set to False, indicating that only a single selection is allowed. To allow disconnected regions, set this value to True.
In the generated *.pro file, the False value is specified with the DISJOINT_SELECTION keyword to the widget creation routine.
The Display Headers attribute determines if the table headings, the row and column labels, are displayed. By default, this value is set to True, indicating that table heading should be displayed. To disable the display of table headings, set this value to False.
In the generated *.pro file, the False value is specified with the NO_HEADERS keyword to the widget creation routine.
The Editable attribute determines if the table widget is editable or not. By default, this value is set to False, which means the text widget is not editable, and the text is read-only. To make the text widget editable, set this value to True.
In the generated *.pro file, this value is specified with the EDITABLE keyword to the widget creation routine.
The Number of Columns attribute specifies the number of columns in the table widget. This value sets the full, virtual width of the table. By default, it is set to 6.
In the generated *.pro file, this value is specified with the XSIZE keyword to the widget creation routine.
| Note To have a scrollable table, set the Scroll attribute to True. Then, to specify the visible size of the table, set the Viewport Columns attribute. |
The Number of Rows attribute specifies the number of rows in the table widget. This value sets the full, virtual height of the table. By default, it is set to 6.
In the generated *.pro file, this value is specified with the YSIZE keyword to the widget creation routine.
| Note To have a scrollable table, set the Scroll attribute to True. Then, to specify the visible size of the table, set the Viewport Columns attribute. |
The Resize Columns attribute determines if this user can resize table columns. By default, this value is set to True, indicating that the user can resize the columns. To specify that the columns of the table are not resizeable by the user, set this value to False.
In the generated *.pro file, this value is specified with the RESIZEABLE_COLUMNS keyword to the widget creation routine.
| Note If you set the Display Headers attribute to False, the ability to resize the columns is automatically disabled. |
The Row/Column Major attribute specifies how data is transferred to the table widget, either by Row or by Column. By default, this value is set to Row, indicating that the data should be read into the table as if each element of the vector is a structure containing one row's data. To specify that the data should be read into the table as if each element of the vector is a structure containing one column's data, set this value to Column. Note that for either setting to work properly the structures must all be of the same type, and must have one field for each column or row in the table.
In the generated *.pro file, this value is specified with the ROW_MAJOR or the COLUMN_MAJOR keyword to the widget creation routine.
The Row Labels attribute specifies the labels for the table rows. By default, this value is set to empty strings, but you can set it to any set of strings. To set the labels for table columns, use the Column Labels attribute.
To enter more than one string in the Value field, type in a string, then press Control+Enter (at the end of each line). This moves you to the next line, or the next label for a row. When you have entered as many labels as you want, press Enter to set the values.
In the generated *.pro file, this value is specified with the ROW_LABELS keyword to the widget creation routine.
The Scroll attribute determines if the table widget has scroll bars. By default, this value is set to False, indicating that the table will have no scroll bars. To enable scroll bars, set this value to True. If you set this value to True, you can set the size of the scrollable region with the Viewport Rows and Viewport Columns properties.
In the generated *.pro file, this value is specified with the SCROLL keyword to the widget creation routine.
The Tab Mode attribute specifies what support the widget has for receiving or losing focus through tabbing. By default, this value is set to Inherit.
| Note It is not possible to tab to disabled (Sensitive = False) or hidden (Visible = False) widgets. |
Allowable values are:
| Note The default tab mode of a widget is Inherit. The tabbing support defined for the parent base, described in Base Widget Attributes, is inherited by widget children unless otherwise specified. |
| Note In widget applications on the UNIX platform, the Motif library controls what widgets are brought into and released from focus using tabbing. The TAB_MODE keyword value is always zero, and any attempt to change it is ignored when running a widget application on the UNIX platform. Tabbing behavior may vary significantly between UNIX platforms; do not rely on a particular behavior being duplicated on all UNIX systems. |
In the generated *.pro file, this value is specified with the TAB_MODE keyword to the widget creation routine. For more information on tabbing among widgets, see Tabbing in Widget Applications.
The Viewport Columns attribute specifies the number of columns that should be visible in the scroll area of the table widget. By default, this value is set to 6.
If you first set the Scroll attribute to True, you can then set this value to any size from 0 to n columns within the limits of your full table size. The full table size, or virtual width in columns, is set with the Number of Columns attribute.
This attribute is used only when the Component Sizing attribute is set to Default. If you set the Component Sizing attribute to Explicit, either through the Properties dialog or by dragging the component to specific size, the Viewport Columns attribute is ignored, and the X Size and the Y Size properties are used.
In the generated *.pro file, this value is specified with the X_SCROLL_SIZE keyword to the widget creation routine.
The Viewport Rows attribute specifies the number of rows that should be visible in the scroll area of the table widget. By default, this value is set to 6.
If you first set the Scroll attribute to True, you can then set this value to any size from 0 to n rows, within the limits of your full table size. The full table size, or virtual height in rows, is set with the Number of Rows attribute.
This attribute is used only when the Component Sizing attribute is set to Default. If you set the Component Sizing attribute to Explicit, either through the Properties dialog or by dragging the component to specific size, the Viewport Rows attribute is ignored, and the X Size and the Y Size properties are used.
In the generated *.pro file, this value is specified with the Y_SCROLL_SIZE keyword to the widget creation routine.
For table widgets, you can set common event properties and table-specific event properties. By default, event values are not set. For a list of events common to all widgets, see Common Events.
These are the table widget-specific event properties:
The OnCellSelect value is the routine that is called when cells are selected in the table. When you set this value, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify.
Event is the event structure returned when range of cells is selected or deselected and is of the following type:
{ WIDGET_TABLE_CELL_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:4,
SEL_LEFT:0L, SEL_TOP:0L, SEL_RIGHT:0L, SEL_BOTTOM:0L }
The range of cells selected is given by the zero-based indices into the table specified by the SEL_LEFT, SEL_TOP, SEL_RIGHT, and SEL_BOTTOM fields. When cells are deselected, either by changing the selection or by clicking in the upper left corner of the table, an event is generated in which the SEL_LEFT, SEL_TOP, SEL_RIGHT, and SEL_BOTTOM fields contain the value -1.
| Note Two WIDGET_TABLE_CELL_SEL events are generated when an existing selection is changed to a new selection. If your code uses this event, be sure to differentiate between select and deselect events. |
The OnColWidth value is the routine that is called when the column width is changed. When you set this value, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when a column width is changed by the user and is of the following type:
{ WIDGET_TABLE_COLUMN_WIDTH, ID:0L, TOP:0L, HANDLER:0L, TYPE:7,
COLUMN:0L, WIDTH:0L }
COLUMN contains the zero-based column number, and WIDTH contains the new width.
The OnDelete value is the routine that is called when text is deleted from the table. When you set this value, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify.
Event is the event structure returned when any amount of text is deleted from a cell of a table widget and is of the following type:
{ WIDGET_TABLE_DEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:2, OFFSET:0L,
LENGTH:0L, X:0L, Y:0L }
OFFSET is the (zero-based) character position of the first character deleted, and it is the insertion position that will result when the next character is inserted. LENGTH gives the number of characters involved. The X and Y fields give the zero-based address of the cell within the table.
The OnFocus value is the routine that is called when the keyboard focus of the base changes. When you set it, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify.
Event is the returned event structure, which is of the following type:
{ WIDGET_KBRD_FOCUS, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 }
ENTER returns 1 (one) if the table widget is gaining the keyboard focus, or 0 (zero) if the table widget is losing the keyboard focus.
The OnInsertChar value is the routine that is called when text is inserted in the table. When you set this value, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when a single character is typed into a cell of a table widget and is of the following type:
{ WIDGET_TABLE_CH, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, OFFSET:0L,
CH:0B, X:0L, Y:0L }
OFFSET is the (zero-based) insertion position that will result after the character is inserted. CH is the ASCII value of the character. The X and Y fields indicate the zero-based address of the cell within the table.
The OnInsertString value is the routine that is called when text is inserted in the table. When you set this value, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when multiple characters are pasted into a cell and is of the following type:
{ WIDGET_TABLE_STR, ID:0L, TOP:0L, HANDLER:0L, TYPE:1, OFFSET:0L,
STR:'', X:0L, Y:0L }
OFFSET is the (zero-based) insertion position that will result after the text is inserted. STR is the string to be inserted. The X and Y fields indicate the zero-based address of the cell within the table.
The OnInValidData value is the routine that is called when invalid data is set in a cell. When you set this value, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when the text entered by the user does not pass validation, and the user has finished editing the field (by pressing Tab or Enter). The event structure is of the following type:
{ WIDGET_TABLE_INVALID_ENTRY, ID:0L, TOP:0L, HANDLER:0L, TYPE:8,
STR:'', X:0L, Y:0L }
STR contains invalid contents entered by the user as a text string. The X and Y fields contain the cell location.
The OnTextSelect value is the routine that is called when text is selected in the table. When you set this value, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when an area of text is selected.
The event structure is of the following type:
{WIDGET_TABLE_TEXT_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:3,
OFFSET:0L, LENGTH:0L, X:0L, Y:0L}
This event announces a change in the insertion point. OFFSET is the (zero-based) character position of the first character to be selected. LENGTH gives the number of characters involved. A LENGTH of zero indicates that the widget has no selection, and that the insertion position is given by OFFSET. The X and Y fields indicate the zero-based address of the cell within the table.
IDL Online Help (March 06, 2007)