Overview
An EditTable widget displays a table of values (integer, string or floating
point) organized in rows and columns. A table can be manipulated by the
application via convenience functions or by the end user via actions and
translations. Resources defined by the widget include the number of rows and
columns, the grid line style and color, the font used to display data, and the
title placement. Some columns can be specified as read-only while others can
be edited by the application or end user. Color or monochrome PostScript output
of the entire table or a subset of the table is also provided. An EditTable
widget can be used in conjunction with an INT Scroll widget so that the table
annotation remains visible when the table is scrolled vertically or horizontally
. Because the INT EditTable widget class is a subclass of the EditObject widget
class, it inherits the capability to draw Graphic objects on the table.
Data Organization
The data used by the EditTable widget is organized as columns of cells. Every
column in the table contains the same number of cells. Every cell in a column
has the same data type and data format.
Table Size
The table's size at widget creation time is specified in terms its initial
number of rows and columns, but it can be changed afterwards by adding or
deleting rows or columns. The EditTable widget is designed to handle very large
tables efficiently, but the practical size of a table may be limited by the
available memory.
Table Orientation
The columns in a table can be oriented vertically or horizontally. A vertical
orientation is the natural (default) orientation, but in some applications a
horizontal orientation may be useful. When the columns are oriented
horizontally, the cells in a column are drawn from left to right and the column
annotation appears on the left or the right of the column. All column and row
operations are used in the same way no matter what the column orientation is.
Data Structures
The values in the cells of the table can exist only within the EditTable widget
or they can be shared by the application and the EditTable widget. There are
some restrictions on the operations that can be performed on the table data
when it is shared by the application and the widget, but the memory required to
hold the table data is minimized in this case.
Supported Data Types
The values in the cells of a column can be short integers, integers, long
integers, floating point numbers, double precision floating point numbers,
character strings or pointers.
Using EditTable with Scroll
When the EditTable widget is a child of an INT Scroll widget, the table can be
scrolled so that the table title and row/column annotation remains visible.
Also, some columns and/or rows can be frozen so that they remain visible as the
rest of the table is scrolled.
Creating an EditTable widget
An application creates an EditTable widget as a child of a container widget
such as a Bulletin Board widget, Form widget, Scrolled Window widget, or INT
Scroll widget. The number of rows and columns, along with the format of each
column, are usually specified when the EditTable widget is created. If the
application has data that is to be displayed in the table, then the application
specifies that data to the EditTable widget after the table is created (via
convenience functions). During the creation process, the application uses
resources to specify callback procedures (for the table editing operations) and
general table attributes such as automatic row or column annotation, grid line
appearance, and fonts.
Displaying a Table
When the EditTable widget is mapped, it displays the data (if any) contained
within the columns of the table. If the data for a column has not been defined,
then the EditTable widget displays empty cells in that column.
Formatting Data
Formatting the data for display is based on a C format specifier that is
defined for each column. A callback, XmNformatCellCallback, can be invoked to
handle non standard formats or pointer data.
Updating a Table
When there are changes in the data for one or more columns in the table, the
changes can originate in the application or they can originate with the end
user. If the application changes the data in the shared data structures, then
the application must call the function XintEditTableUpdateDataDisplay for
each column that has changed, so that the EditTable widget can update the
display of the table. The application can also change the value in a specific
cell and cause the table display to be updated by using the function,
XintEditTableFillCell. If the end user changes some of the cell values, then
the EditTable widget will update the display and the shared data structures
automatically.
Editing Operations
The EditTable widget supports a large number of editing operations. The edit
operations can be performed by the application using provided functions or by
the end user via action routines. The types of edits that can be performed are
categorized as table edits, annotation edits, column edits, row edits or cell
edits.
Table Edit
The size of a table and other characteristics such as the table title,
highlight colors, and default column attributes can be changed via EditTable
resources after the table is created. Rows and columns may be cut, pasted,
inserted or deleted via action routines or convenience functions. Also, a
range of columns or rows can be reordered by the application using a supplied
function.
Annotation Edits
The row and column annotation can be changed following table creation by using
provided functions. The application changes the row and column annotation by
updating the annotation for a single row or column. Alternatively, the
application can change the annotation for all of the rows and all of the
columns at one time. In either case, the application uses provided functions.
The end user can change a single row or column annotation with an action
routine. This action routine calls an application defined callback routine
that actually performs the annotation editing operation.
Column Edits
A column can be modified by changing the format of the data in the column, by
changing the width of the column or by changing the number of rows in the
column.
Row Edits
Because a table is column oriented, the rows must be edited indirectly by
editing the columns in the table or by editing the cells in the row.
Cell Edits
The value of a cell can be changed if the cell is in an editable column and if
the application allows the edit operation to occur. The format or data type
of a cell can only be changed by changing the format or data type of the column
that the cell is in. To edit the value in a cell, the end user must select
the cell with the mouse or traverse to it using the keyboard. If the end user
enters a value after selecting the cell, then the current value will be
replaced. If the end user clicks a second time, then any new characters typed
are inserted into the current value. If the end user drags the mouse cursor
through a portion of the cell's current value, the portion of the string
selected with the mouse will be replaced with the characters typed.
Input Validation
You can specify a validate value callback so that a value entered into a cell
can be validated before the change is made permanent. The application can elect
to allow the change, substitute its own value or disallow the change.
Traversing the Table
The user can traverse the table by using the keyboard (e.g. tab, return,
cursor keys) or he can use the pointer to move from one location in the table
to another. The application can control the traversal via a callback so that
the cursor skips over areas of the table that are not relevant to the current
application operation. The XmNoverrideTextTranslations resource allows the
user to control the action of the Return, Left, Right, Up and Down keys to
provide navigation between cells or within a cell.
Cutting and Pasting
When row(s) or column(s) are deleted or copied, they are placed on the
EditTable's clipboard. The clipboard can simultaneously hold columns and rows.
When another copy or delete operation occurs, then the data copied or deleted
replaces the same type of data (row or column) currently on the clipboard.
Data on the clipboard can be pasted into the table using convenience functions
and action routines.
Interactive Move, Copy and Resize
A set of actions is available for performing interactive move, resize or copy
operations on rows, columns or cells. The actions that operate on cells are
EditTableStartDrag, EditTableExtendDrag and EditTableEndDrag. The drag action
EditTableStartDrag supports an argument which specifies the type of operation,
move, resize, copy or a combination of those. The actions for editing rows or
columns are AnnotationStartDrag, AnnotationExtendDrag and AnnotationEndDrag.
Row and column actions need to be registered in the EditTable translation
table if the table is not created as a child of a Scroll widget. Otherwise, the
application should use resources XmNrowAnnotationTranslations and
XmNcolumnAnnotationTranslations.
Frozen Columns
When the EditTable widget is a child of a Scroll widget, columns can be frozen
in the table. Frozen columns are displayed on the left or right side of the
table and are not scrolled when the table is scrolled horizontally. However,
cells in a frozen column can be selected and edited. The application uses a
function to freeze as many columns as desired. Another function is used to
release a frozen column, returning it to its former position and state.
Frozen Rows
When the EditTable widget is a child of a Scroll widget, rows can be frozen in
the table. Frozen rows are displayed above or below the table and are not
scrolled when the table is scrolled vertically. However, cells from a frozen
row can be selected or edited. The application uses a function to freeze as
many rows as desired. Another function is used to release a frozen row,
returning it to its former position and state.
Cell, Column and Row Indices
The rows and columns in a table are indexed using sequential integers. The
leftmost column has an index of 1 and the topmost row has an index of 1. The
cells in a table are indexed with a pair of integers. The first integer is
the index of the column containing the cell and the second integer is the
index of the row containing the cell. When addressing a block of cells in a
table, you usually specify the indices of the rows and columns that bound the
block of cells.
Column Annotation
The columns in a table can be annotated with character strings. The annotation
strings can be generated automatically as strings of letters in alphabetical
order (A, B, C,..., AA, AB, etc.) by the EditTable widget, or the application
can supply a string either at column creation time or after a column is created.
Row Annotation
The rows in a table can be annotated with any of the supported data types. The
supported data types are short, integer, long integer, floating point, double
precision floating point, and character string. However, you cannot mix data
types for the row annotations. The annotation strings can be generated
automatically as sequential integers by the EditTable widget, or the
application can supply a value either at row creation time or after a row is
created.
Margin Size Specification
An EditTable widget will automatically determine the optimal size for one or
more of the margins around the scrolled child window according to the setting
of the XmNautoMarginAdjust resource. You can choose which of the margins will
be automatically sized and which will be sized according to values of the
margin resources (XmNtopMargin, XmNleftMargin, XmNrightMargin, XmNbottomMargin).
However, if an EditTable widget is a child of a Scroll widget the sizes of
the (non-auto sized) margins are set using the resources of the Scroll widget
(XmNtopAnnotationHeight, XmNleftAnnotationWidth, XmNrightAnnotationHeight,
XmNbottomAnnotationHeight).
Subtables
The table displayed by an EditTable is organized as one to four subtables.
There is a separate subtable for each of the following:
- all of the cells in rows and columns that are not frozen
- the cells in rows that are frozen (if any) but not including cells in frozen columns
- the cells in columns that are frozen (if any) but not including cells in frozen rows
- the cells contained in the intersection of the frozen columns and frozen rows (if any)
You can get the widget IDs of any of these subtables using the function
XintEditTableGetSubtable.
Column and Row Visibility
The display of the columns and rows of an EditTable widget can be selectively
turned on or off using functions XintEditTableChangeColumnVisibility or
XintEditTableChangeRowVisiblity. Also, resource XmNallowPartialCellDisplay,
prevents displaying the contents of columns which are only partially visible.
Drawing Graphics on a Table
Graphic objects such as text, arrows and circles can be created and edited on
a table. Those graphics can be saved to a file for retrieval for later use.
Because graphic objects can have only one parent, a graphic object cannot span
more than one of the subtables of an EditTable. For instance, a line cannot
begin in the frozen row subtable and end in the frozen column subtable. Also
note that if a graphic object spans multiple elements in a subtable (e.g.
columns in the frozen column subtable) and that element is removed from the
subtable (e.g. releasing a frozen column that one of the line end points was
in) then the graphic object will be removed from the display. However, the
graphic object does still exist and will reappear when the removed element is
again placed in the subtable.
Graphic Object Coordinate System
The coordinate system used to draw INT Graphic objects inside an EditTable
widget subtable uses real numbers for both the X and Y axes. The X coordinate
of a point used to specify a Graphic object would be specified as the number
of the column containing the point followed by the decimal fraction of the
column where the point lies across the horizontal dimension of the column. For
instance, to specify the X coordinate of a point located horizontally in the
middle of the 3rd column, you would specify 3.5 as the X coordinate. Similarly,
the Y coordinate of a point used to specify a Graphic object would be specified
as the number of the row containing the point followed by the decimal fraction
of the row where the point lies across the vertical dimension of the column.
For instance, to specify the Y coordinate of a point located vertically one
tenth of the cell height away from the top of a cell in the 14th row, you
would specify 14.1 as the Y coordinate.