Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AG_TREETBL(3)	       FreeBSD 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 or-
     ganized 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 identi-
     fied.

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
     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 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
			      repopulated automatically	to reflect some	exter-
			      nal 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 (equivalent	to in-
			      voking AG_ExpandHoriz(3)).

     AG_TREETBL_VFILL	      Expand vertically	in parent (equivalent to in-
			      voking AG_ExpandVert(3)).

     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 display.

     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 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 ini-
     tially 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_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-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_TreetblDeselectColID() 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_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	ap-
     peared in Agar 1.0	as AG_Tableview. Agar-1.3.4 first featured the new
     AG_Treetbl	interface.

FreeBSD	13.0			August 20, 2002			  FreeBSD 13.0

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://www.freebsd.org/cgi/man.cgi?query=AG_Treetbl&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help