FreeBSD Manual Pages
AG_TREETBL(3) Library Functions Manual AG_TREETBL(3) NAME AG_Treetbl -- agar tree-based table widget SYNOPSIS #include <agar/core.h> #include <agar/gui.h> DESCRIPTION The AG_Treetbl widget displays a tree in table format (i.e., rows are orga- nized in a tree structure). It is an alternative implementation of AG_Ta- ble(3) optimized for the storage of the table data in tree form. It also differs from AG_Table in that rows and columns are uniquely identified. INHERITANCE HIERARCHY AG_Object(3)-> AG_Widget(3)-> AG_Treetbl. INITIALIZATION AG_Treetbl * AG_TreetblNew(AG_Widget *parent, Uint flags, AG_TreetblDataFn dataFn, AG_TreetblSortFn sortFn) void AG_TreetblSizeHint(AG_Treetbl *tbl, int width, int nrows) void AG_TreetblSetRefreshRate(AG_Treetbl *tbl, Uint ms) void AG_TreetblSetColHeight(AG_Treetbl *tbl, int height) void AG_TreetblSetSortCol(AG_Treetbl *tbl, AG_TreetblCol *col) void AG_TreetblSetSortMode(AG_Treetbl *tbl, enum ag_treetbl_sort_mode mode) void AG_TreetblSetExpanderCol(AG_Treetbl *tbl, AG_TreetblCol *col) The AG_TreetblNew() function allocates, initializes, and attaches a new AG_Treetbl widget. The dataFn() argument specifies the callback function from which to obtain the text to display for a given cell. The callback function should return a pointer to a valid C string to display under the given cell, and is declared as: char * MyDataFn(AG_Treetbl *tbl, int col, int row) The sortFn() argument, if not NULL, specifies an optional comparison func- tion to use in sorting cells, and is declared as: int MySortFn(AG_Treetbl *tbl, int col1, int row1, int col2, int row2) The flags argument to AG_TreetblNew() may include: AG_TREETBL_MULTI Allow selection of multiple rows at once while holding CTRL or SHIFT. AG_TREETBL_MULTITOGGLE Allow selection of multiple rows at once without holding CTRL or SHIFT. AG_TREETBL_REORDERCOLS Allow reordering of the columns through dragging and dropping of the column headers. AG_TREETBL_NODUPCHECKS Disable the safety check for duplicate row and column IDs. This option avoids a lookup in AG_TreetblAddCol() and AG_TreetblAddRow(). AG_TREETBL_SORT Enable sorting of the rows. AG_TREETBL_POLLED Enable polling mode such that the table can be re- populated automatically to reflect some external data. When a row is deleted, AG_Treetbl will re- member selection information for later use by AG_TreetblRowRestoreAll(). AG_TREETBL_HFILL Expand horizontally in parent container. AG_TREETBL_VFILL Expand vertically in parent container. AG_TREETBL_EXPAND Shorthand for AG_TREETBL_HFILL | AG_TREETBL_VFILL. This is recommended as an alternative to AG_Treet- blSizeHint(). The AG_TreetblSizeHint() function requests an initial sizing, where width is the width in pixels and nrows is the number of rows to display. AG_TreetblSetRefreshRate() sets the default update rate for dynamically up- dated cells. AG_TreetblSetColHeight() sets the height of column headers in pixels. AG_TreetblSetSortCol() specifies the column controlling the sorting of rows. AG_TreetblSetSortMode() sets the sort method, where mode is one of: AG_TREETBL_SORT_NOT No sorting AG_TREETBL_SORT_ASC Sort in ascending order AG_TREETBL_SORT_DSC Sort in descending order AG_TreetblSetExpanderCol() specifies an alternate column for the tree ex- pand/collapse controls. By default, the first column is used. ROWS AND COLUMNS AG_TreetblCol * AG_TreetblAddCol(AG_Treetbl *tbl, int colID, const char *width, const char *text, ...) AG_TreetblRow * AG_TreetblAddRow(AG_Treetbl *tbl, AG_TreetblRow *parent, int rowID, const char *argSpec, ...) AG_TreetblRow * AG_TreetblLookupRow(AG_Treetbl *tbl, int rowID) void AG_TreetblDelRow(AG_Treetbl *tbl, AG_TreetblRow *row) void AG_TreetblDelRowID(AG_Treetbl *tbl, int rowID) void AG_TreetblClearRows(AG_Treetbl *tbl) void AG_TreetblRestoreRows(AG_Treetbl *tbl) AG_TreetblAddCol() creates a new table column. colID is a unique identi- fier for the new column. If width is non-NULL, it is a AG_SizeSpec(3) specifying a default width for the new column. text is the text initially displayed in the column header. The AG_TreetblAddRow() function inserts a new row into the table. rowID is a unique identifier for the row. parent specifies the parent row in the tree. The data of the individual cells of the row are specified in argSpec and following arguments (in standard Agar argument format). AG_TreetblLookupRow() looks up the row identified by rowID. If there is no such row, the function returns NULL. AG_TreetblDelRow() removes the specified row from the table. The AG_Treet- blDelRowID() variant looks up the row by ID. AG_TreetblClearRows() (alternatively AG_TreetblBegin()) clears all the rows from the table. If AG_TREETBL_POLLED is in effect, the row-specific widget states are remembered, to be later recovered by AG_TreetblRestoreRows() (alternatively AG_TreetblEnd()). SELECTIONS void AG_TreetblSelectCol(AG_Treetbl *tbl, AG_TreetblCol *col) void AG_TreetblDeselectCol(AG_Treetbl *tbl, AG_TreetblCol *col) void AG_TreetblSelectColID(AG_Treetbl *tbl, int colID) void AG_TreetblDeselectColID(AG_Treetbl *tbl, int colID) void AG_TreetblSelectRow(AG_Treetbl *tbl, AG_TreetblRow *row) void AG_TreetblSelectRowID(AG_Treetbl *tbl, int rowID) void AG_TreetblDeselectRow(AG_Treetbl *tbl, AG_TreetblRow *row) void AG_TreetblDeselectRowID(AG_Treetbl *tbl, int rowID) void AG_TreetblSelectedRow(AG_Treetbl *tbl) void AG_TreetblSelectAll(AG_Treetbl *tbl, AG_TreetblRow *row) void AG_TreetblDeselectAll(AG_Treetbl *tbl, AG_TreetblRow *row) The AG_TreetblSelectCol() and AG_TreetblDeselectCol() routines select and deselect the specified column. The AG_TreetblSelectColID() and AG_Treet- blDeselectColID() variants look up the column by index and return -1 if no such column exists. AG_TreetblSelectRow() and AG_TreetblDeselectRow() select or deselect the specified row. The AG_TreetblSelectRowID() and AG_TreetblDeselectRowID() variants lookup the row by ID and return -1 if it is invalid. AG_TreetblSelectedRow() returns the currently selected row or NULL if there is none. If the AG_TREETBL_MULTI or AG_TREETBL_MULTITOGGLE flags are in effect, the first selected row is returned. The AG_Treetbl should be locked by the caller. The AG_TreetblSelectAll() and AG_TreetblDeselectAll() variants also se- lect/deselect the child rows. CHILDREN VISIBILITY void AG_TreetblExpandRow(AG_Treetbl *tbl, AG_TreetblRow *row) void AG_TreetblCollapseRow(AG_Treetbl *tbl, AG_TreetblRow *row) The AG_TreetblExpandRow() and AG_TreetblCollapseRow() routines control whether child rows of row are visible or hidden. This state is also con- trolled by the tree expand/collapse controls. EVENTS The AG_Treetbl widget does not generate any event. SEE ALSO AG_Intro(3), AG_Widget(3), AG_Window(3) HISTORY The AG_Treetbl widget was written by John Blitch in 2004 and first appeared in Agar 1.0 as AG_Tableview. Agar-1.3.4 first featured the new AG_Treetbl interface. Agar 1.7 December 21, 2022 AG_TREETBL(3)
NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INITIALIZATION | ROWS AND COLUMNS | SELECTIONS | CHILDREN VISIBILITY | EVENTS | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Treetbl&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>