AG_Table widget displays a set of cells organized in one or more columns.
Cells can be associated with text, numerical values, pointers to numerical
values, or custom functions.
AG_Table is optimized for tables that must be rebuilt frequently.
Individual cells, entire rows or entire columns can be selected indepedently.
Note that another table display widget, AG_Treetbl(3), is also available. It stores row information in a tree structure and provides a very different interface from AG_Table.
|AG_Object(3)-> AG_Widget(3)-> AG_Table.|
The AG_TableNew() function allocates, initializes and attaches a new AG_Table widget.
The AG_TableNewPolled() variant sets the polling flag and configures the table-poll event. event_fn is a pointer to the event-handler function responsible for populating the table (see AG_TableBegin() and AG_TableEnd() for details). event_args and the following arguments are optional AG_Event(3) style parameters that will be passed on to event_fn.
Acceptable flags include:
The AG_TableSetPollInterval() function specifies an alternate update interval for polled tables in milliseconds (default is 250ms). Polling may be paused by calling AG_TableSetPollInterval() with an argument of 0.
The AG_TableSizeHint() function requests an initial sizing, where width is the width in pixels and nrows is the number of rows to display.
AG_TableSetColHeight() sets the size of column headers in pixels. AG_TableSetRowHeight() sets the size of rows in pixels. In both cases, the default is dependent on the height of the default font.
AG_TableSetColMin() sets the minimum allowed column width, in pixels. The default is a small value intended to prevent the user from resizing columns to zero size. If existing columns are smaller than the specified value, AG_TableSetColMin() will resize them.
AG_TableSetDefaultColWidth() specifies a "default" width in pixels, to use during initial size requisition for columns using FILL or a size specification in "%".
AG_TableSetSelectionMode() defines the effect of cursor selections on the table. Possible values for mode are:
AG_TableSetSelectionColor() sets the color of the rectangle that will be blended onto selected cells, rows or columns in order to indicate selection.
AG_TableSetSeparator() changes the set of accepted field-separator characters in AG_TableAddRow() (default is ":").
The AG_TableSetPopup() function creates a contextual AG_Menu(3) item associated with a row, column or cell. If col is a valid index and row is -1, the menu is shown when clicking on the header of the given column. If col is -1 and row is a valid index, the menu is shown when clicking on any cell of the given row. If col and row are both valid indices, the menu is shown when clicking on the given cell. If both indices are -1, the menu is shown when clicking on any cell. If a contextual menu already exists for the specified indices, AG_TableSetPopup() returns a pointer to the existing menu item.
The AG_TableSetRowClickFn(), AG_TableSetColClickFn() and AG_TableSetCellClickFn() functions register a callback routine to invoke upon single-click on a row, column or cell, respectively, depending on the current selection mode. The callback routine for AG_TableSetRowClickFn() is passed the row index as an int argument. AG_TableSetColClickFn() is passed the column index and AG_TableSetCellClickFn() is passed the row and column indices in order.
The AG_TableSetRowDblClickFn(), AG_TableSetColDblClickFn(), and AG_TableSetCellDblClickFn() variants register callbacks to invoke on double-click. If both single and double-click callbacks are defined, only the single-click callback is used.
The AG_TableSetColumnAction() specifies the action(s) to take whenever a column header is pressed. Acceptable arguments to flags include:
The AG_TableAddCol() function inserts a new column into the table, returning the number of the new column if successful, or -1 if an error has occurred. name specifies the text to display in the column header. size_spec is an optional size specification (see AG_SizeSpec(3)) used in initial sizing of the column. sortFn, if not NULL, is the compare function to use for items of this column. It is passed pointers to two AG_TableCell structures to compare.
The AG_TableSelectCol() and AG_TableDeselectCol() functions control the selection flag on the given column. AG_TableSelectAllCols() and AG_TableDeselectAllCols() set the selection flag on all columns of the table. AG_TableColSelected() returns 1 if the given column is selected, 0 otherwise.
Note that the of the column selection flags are independent from the selection flag of individual cells; their meaning is application-specific.
The AG_TableAddRow() function inserts a new row into the table and returns the new row number, or -1 if a failure has occurred. The fmt argument describes the individual fields (or cells) of this row. By default, the fields are comma-separated (the separator can be changed using AG_TableSetSeparator()). Note that it is possible to mix fields of differing types into a same column as long as the sorting function of that column can handle the combinations.
Acceptable specifiers include:
The functions AG_TableSelectRow() and AG_TableDeselectRow() set the selection flag on all cells of the given row. AG_TableSelectAllRows() and AG_TableDeselectAllRows() set the selection on all cells of the table. AG_TableRowSelected() returns 1 if the given row is selected, 0 otherwise.
The AG_TableGetCell() routine returns a pointer to the table cell currently at the specified row and column position.
AG_TableSelectCell(), AG_TableDeselectCell() and AG_TableCellSelected() control and query the selection flag on an individual cell located at the given row and column.
The AG_TableCompareCells() function compares cells c1 and c2. It returns 0 if the contents of the two cells is identical, otherwise the returned value depends on the type. If the cells have different types, it returns 1. If they are text-based, the return value of strcmp(3) is returned. If they are numerical, the difference is returned. For pointer and surface cells, the return value is 1 if they differ.
The AG_TablePrintCell() function writes a formatted string representation of the current cell value, to the fixed-size buffer dst.
AG_TableSaveASCII() writes the formatted contents of the table into an ASCII file f. Each row is separated by a newline, and cells are separated by the character given by the separator argument. The function returns 0 on success, -1 on failure.
AG_Table widget generates the following events:
For the AG_TableCell structure:
For the AG_TableCol structure:
CELL DATA TYPES
The cell data type is determined by
enum ag_table_cell_type: |
The following code fragment creates a table and immediately populates it:
The following code fragment creates a table and arranges for periodical update of its contents from an UpdateMyTable() function:
For more example usages, see tests/table.c in the Agar source distribution.
|AG_Intro(3), AG_Surface(3), AG_Widget(3), AG_Window(3)|
|The AG_Table widget first appeared in Agar 1.0.|