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 organized in a tree structure). It is an alternative implementation of AG_Table(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 func- tion 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 dis- play 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 function 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 with- out holding CTRL or SHIFT. AG_TREETBL_REORDERCOLS Allow reordering of the columns through drag- ging 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 repopulated automatically to reflect some ex- ternal data. When a row is deleted, AG_Treetbl will remember 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_TreetblSizeHint(). The AG_TreetblSizeHint() function requests an initial sizing, where width is the width in pixels and nrows is the number of rows to dis- play. AG_TreetblSetRefreshRate() sets the default update rate for dynamically updated 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 expand/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 iden- tifier 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 spec- ified 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_TreetblDelRowID() 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-spe- cific 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_TreetblDeselectColID() variants look up the column by index and re- turn -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 controlled 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 ap- peared 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+14.3.quarterly>