Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.
SYNOPSIS
#include <agar/core.h> #include <agar/gui.h> |
DESCRIPTION
|
The
AG_Tlist widget is designed to display the contents of an existing tree or list
structure.
Typically, the contents are generated from a polling routine.
The AG_Table(3) and AG_Treetbl(3) widgets are more efficient alternatives to AG_Tlist. |
INHERITANCE HIERARCHY
| AG_Object(3)-> AG_Widget(3)-> AG_Tlist. |
INITIALIZATION
|
The AG_TlistNew() function allocates, initializes, and attaches a AG_Tlist widget. The AG_TlistNewPolled() variant sets the AG_TLIST_POLL flag and configures a default tlist-poll event handler. Acceptable flags include:
AG_TlistSetRefresh() configures the rate at which the polling routine will be invoked, in milliseconds. It is only useful with AG_TlistNewPolled(). The default is 125 milliseconds. A value of -1 disables automatic updates, assuming AG_TlistRefresh() will be used to explicitely force updates. AG_TlistSetItemHeight() sets the height of all items to item_height pixels . AG_TlistSetIconWidth() sets the width of icons in pixels. The AG_TlistSetIcon() function updates the icon shown with item, scaled to w by h pixels. AG_TlistSizeHint() requests sufficient height to display nitems items at once, and sufficient width to display an item containing text. The AG_TlistSizeHintPixels() variant accepts a width argument in pixels instead of a string and the AG_TlistSizeHintLargest() variant uses the largest text label in the current list of items to determine the width. AG_TlistSetDblClickFn() arranges for the given callback fn to be invoked with the given arguments (as well as the item pointer) when the user double clicks on an item. AG_TlistSetChangedFn() arranges for the callback fn to be invoked when the user selects or deselects an item. The arguments are respectively, a pointer to the item and an integer with a value of 0 to indicate deselection and 1 to indicate selection. In order for AG_Tlist to maintain per-item states (selection flag, etc) through polling updates, items must be uniquely identifiable. By default, the p1 pointer is used. AG_TlistSetCompareFn() specifies an alternate comparison routine to use. The standard built-in routines AG_TlistCompareStrings(), AG_TlistComparePtrs() and AG_TlistComparePtrsAndClasses() are provided. |
MANIPULATING ITEMS
|
The AG_TlistAdd() function inserts a new item into the list. The icon argument specifies an optional AG_Surface(3) to display next to the label. Both the icon and the text arguments can be set to NULL. AG_TlistAddHead() places the item at the head of the list, as opposed to the tail. AG_TlistAddPtr() is a variant of AG_TlistAdd() which accepts an extra user-defined pointer p1, which will be associated with the item. AG_TlistAddPtrHead() places the item at the head of the list, as opposed to the tail. The AG_TlistDel() function detaches and frees item from its parent Nm tlist . AG_TlistUniq() scans the list for duplicates (by comparing items using the current comparison routine as configured by AG_TlistSetCompareFn ),() and removes all duplicate items. AG_TlistClear() removes all items attached to the list. The AG_TlistBegin() function removes all items attached to tlist, but remembers the selected items. AG_TlistEnd() compares each item against the previous selections and restores the selected flag accordingly. The AG_TlistSelect() and AG_TlistDeselect() functions manipulate the selected flag on item. Unless the AG_TLIST_MULTI flag is set, AG_TlistSelect() clears the selection flag on all other items. The AG_TlistSelectAll() and AG_TlistDeselectAll() functions sets/unsets the selection on all items attached to tlist. The AG_TlistSelectPtr() function selects and returns the first item with a user pointer value matching ptr. Similarly, AG_TlistSelectText() selects and returns the first item with a text field equal to text. Both of these functions invoke tlist-poll if the AG_TLIST_POLL option is set. The AG_TlistFindByIndex() function returns the item at index, or NULL if there is no such item. The AG_TlistSelectedItem() function returns the first selected item, or NULL if there are none. The AG_TlistSelectedItemPtr() function returns the user pointer of the first selected item, or NULL if there is no selected item. It is not possible to distinguish a non-existent selection from an actual selection with a NULL user pointer using this function. In event handler context, the AG_TLIST_ITEM() macro is a shortcut for AG_TlistSelectedItemPtr() on item n from the event stack. The AG_TlistFindPtr() variant copies the user pointer associated with the first selected item into p, returning 0 on success or -1 if there is no item selected. The AG_TlistFindText() function searches tlist for an item containing the text string and returns NULL if there is no such item. The AG_TlistFirstItem() and AG_TlistLastItem() functions return the first and last items on the list. AG_TlistScrollToStart() scrolls the display to the start of the list, and AG_TlistScrollToEnd() scrolls the display to the end of the list. |
POPUP MENUS
AG_MenuItem * AG_TlistSetPopupFn (AG_Tlist *tlist, AG_EventFn fn, const char *fn_args, ...)
AG_MenuItem * AG_TlistSetPopup (AG_Tlist *tlist, const char *category)
The AG_TlistSetPopupFn() function arranges for the given callback fn to be invoked with the given arguments whenever the user right-clicks on an item on the list. A pointer to the selected item is passed as the last argument to this function. Typically, the function will use AG_PopupNew(3) to display a popup menu. The AG_TlistSetPopup() function creates a popup menu that will be displayed when the user right-clicks on any item that matches the given category string. |
EVENTS
BINDINGS
The
AG_Tlist widget provides the following bindings:
|
STRUCTURE DATA
For the
AG_Tlist object:
For the AG_TlistItem structure:
|
ITEM FLAGS
|
EXAMPLES
The following code fragment displays an existing tree structure.
A callback function is used such that updates in the tree are
reflected instantly by the widget.
MyTreeItem *myTreeRoot;
void
UpdateItems(AG_Event *event)
{
AG_Tlist *tl = AG_SELF();
MyTreeItem *item = AG_PTR(1);
MyTreeItem *child;
AG_TlistItem *ti;
if (item == myTreeRoot)
AG_TlistBegin(tl);
ti = AG_TlistAddPtr(tl, NULL, item->text, item);
ti->flags |= AG_TLIST_HAS_CHILDREN;
if (ti->flags & AG_TLIST_EXPANDED) {
LIST_FOREACH(child, &item->children, children) {
AG_Event ev;
AG_EventArgs(&ev, "%p,%p", tl, child);
UpdateItems(&ev);
}
}
if (item == myTreeRoot)
AG_TlistEnd(tl);
}
AG_TlistNewPolled(NULL, 0, UpdateItems, "%p", myTreeRoot);
See demos/widgets in the Agar source distribution for more examples. |
SEE ALSO
| AG_Intro(3), AG_Widget(3), AG_Window(3) |
HISTORY
| The AG_Tlist widget first appeared in Agar 1.0. |
