<-- Back to AG_Intro.3

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

The AG_Tlist widget shows a scrollable tree (or list) of clickable and selectable text items.

It provides a polling mode which optimizes for cases where contents are cleared and regenerated frequently (by recycling assets).

INHERITANCE HIERARCHY

AG_Object(3)-> AG_Widget(3)-> AG_Tlist.

INITIALIZATION

AG_Tlist * AG_TlistNew (AG_Widget *parent, Uint flags)

AG_Tlist * AG_TlistNewPolled (AG_Widget *parent, Uint flags, void (*eventFn)(AG_Event *), const char *eventArgs, ...)

AG_Tlist * AG_TlistNewPolledMs (AG_Widget *parent, Uint flags, int ms, void (*eventFn)(AG_Event *), const char *eventArgs, ...)

void AG_TlistSetRefresh (AG_Tlist *tl, int ms)

void AG_TlistRefresh (AG_Tlist *tl)

void AG_TlistSetItemHeight (AG_Tlist *tl, int item_height)

void AG_TlistSetIconWidth (AG_Tlist *tl, int icon_width)

void AG_TlistSizeHint (AG_Tlist *tl, const char *text, int nitems)

void AG_TlistSizeHintPixels (AG_Tlist *tl, int w, int nitems)

void AG_TlistSizeHintLargest (AG_Tlist *tl, int nitems)

void AG_TlistSetDblClickFn (AG_Tlist *tl, AG_EventFn fn, const char *fn_args, ...)

void AG_TlistSetChangedFn (AG_Tlist *tl, AG_EventFn fn, const char *fn_args, ...)

void AG_TlistSetCompareFn (AG_Tlist *tl, int (*fn)(const AG_TlistItem *a)(const AG_TlistItem *b))

The AG_TlistNew() function allocates, initializes, and attaches a AG_Tlist widget.

The AG_TlistNewPolled() variant enables AG_TLIST_POLL and configures the specified routine eventFn to run every 1 second.

The AG_TlistNewPolledMs() variant accepts a specified update rate in milliseconds ms.

Acceptable flags include:

AG_TLIST_MULTI	Allow multiple selections (with ctrl/shift).
AG_TLIST_MULTITOGGLE	Enforce multiple selections (without ctrl/shift).
AG_TLIST_POLL	List contents are updated dynamically by the tlist-poll event handler. This handler is expected to wrap its AG_TlistAdd() calls between AG_TlistBegin() and AG_TlistEnd(). Implied by AG_TlistNewPolled().
AG_TLIST_NOSELEVENT	Don't raise the tlist-selected event on select.
AG_TLIST_NOSELSTATE	When using AG_TLIST_POLL, don't try to preserve selection information across list updates.
AG_TLIST_HFILL	Expand horizontally in parent container.
AG_TLIST_VFILL	Expand vertically in parent container.
AG_TLIST_EXPAND	Shorthand for AG_TLIST_HFILL AG_TLIST_VFILL\|.

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 given, uniform height of all items. AG_TlistSetIconWidth() sets the width of item icons in 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

AG_TlistItem * AG_TlistAdd (AG_Tlist *tl, const AG_Surface *icon, const char *format, ...)

AG_TlistItem * AG_TlistAddS (AG_Tlist *tl, const AG_Surface *icon, const char *text)

AG_TlistItem * AG_TlistAddHead (AG_Tlist *tl, const AG_Surface *icon, const char *format, ...)

AG_TlistItem * AG_TlistAddHeadS (AG_Tlist *tl, const AG_Surface *icon, const char *text)

AG_TlistItem * AG_TlistAddPtr (AG_Tlist *tlist, const AG_Surface *icon, const char *text, const void *p1)

AG_TlistItem * AG_TlistAddPtrHead (AG_Tlist *tlist, const AG_Surface *icon, const char *text, const void *p1)

void AG_TlistSetIcon (AG_Tlist *tl, AG_TlistItem *item, const AG_Surface *icon)

void AG_TlistSetColor (AG_Tlist *tl, AG_TlistItem *item, const AG_Color *color)

void AG_TlistSetFont (AG_Tlist *tl, AG_TlistItem *item, AG_Font *font)

void AG_TlistDel (AG_Tlist *tlist, AG_TlistItem *item)

int AG_TlistSort (AG_Tlist *tlist)

void AG_TlistUniq (AG_Tlist *tlist)

void AG_TlistClear (AG_Tlist *tlist)

void AG_TlistBegin (AG_Tlist *tlist)

void AG_TlistEnd (AG_Tlist *tlist)

void AG_TlistSelect (AG_Tlist *tlist, AG_TlistItem *item)

void AG_TlistSelectIdx (AG_Tlist *tlist, Uint index)

void AG_TlistSelectAll (AG_Tlist *tlist)

void AG_TlistDeselect (AG_Tlist *tlist, AG_TlistItem *item)

void AG_TlistDeselectIdx (AG_Tlist *tlist, Uint index)

void AG_TlistDeselectAll (AG_Tlist *tlist)

AG_TlistItem * AG_TlistSelectPtr (AG_Tlist *tlist, void *ptr)

AG_TlistItem * AG_TlistSelectText (AG_Tlist *tlist, const char *text)

AG_TlistItem * AG_TlistFindByIndex (AG_Tlist *tlist, int index)

AG_TlistItem * AG_TlistSelectedItem (AG_Tlist *tlist)

void * AG_TlistSelectedItemPtr (AG_Tlist *tlist)

void * AG_TLIST_ITEM (idx)

int AG_TlistFindPtr (AG_Tlist *tlist, void **p)

AG_TlistItem * AG_TlistFindText (AG_Tlist *tlist, const char *text)

AG_TlistItem * AG_TlistFirstItem (AG_Tlist *tlist)

AG_TlistItem * AG_TlistLastItem (AG_Tlist *tlist)

void AG_TlistScrollToStart (AG_Tlist *tlist)

void AG_TlistScrollToEnd (AG_Tlist *tlist)

AG_TlistAdd() inserts a newly-allocated item into the list and returns a pointer to it. The icon argument, if not NULL, specifies a graphical AG_Surface(3) to display with the label. A scaled copy of the given surface will be used. 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.

The AG_TlistAddPtrHead() variant places the item at the head of the list, as opposed to the tail.

AG_TlistSetIcon() sets the icon surface associated with item.

AG_TlistSetColor() sets an alternate text color for the specified item (or NULL to switch back to the default).

AG_TlistSetFont() sets an alternate font for the specified item (or NULL to switch back to the default font). This will increment the font object's reference count. See AG_FetchFont(3).

The AG_TlistDel() function detaches and frees item from its parent Nm tlist .

The AG_TlistSort() routine lexicographically sorts the items in the list. The function returns 0 on success or -1 if insufficient memory is available for the sort.

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.

AG_TlistSelect() sets the selection flag on item (clearing any previous selection unless AG_TLIST_MULTI is set). AG_TlistDeselect() clears the selection flag on item. AG_TlistSelectIdx() and AG_TlistDeselectIdx() reference the target AG_TlistItem by index rather than by pointer.

AG_TlistSelectAll() AG_TlistDeselectAll() sets / clears 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

The AG_Tlist widget generates the following events:

tlist-changed (AG_TlistItem *item, int state)	`item` was selected or unselected.
tlist-selected (AG_TlistItem *item)	`item` was selected.
tlist-dblclick (AG_TlistItem *item)	The user just double-clicked `item`. Binding to this event is equivalent to using AG_TlistSetDblClickFn().
tlist-return (AG_TlistItem *item)	The user has selected `item` and pressed the return key.
tlist-poll (void)	The AG_TLIST_POLL flag is set and the widget is about to be drawn or an event is being processed.

BINDINGS

The AG_Tlist widget provides the following bindings:

void *selected

The p1 (user pointer) value of the selected item, or NULL if there is no selection. The value of this binding is undefined if the AG_TLIST_MULTI or AG_TLIST_MULTITOGGLE flags are in use.

STRUCTURE DATA

For the AG_Tlist object:

TAILQ items	List of all AG_TlistItem objects (read-only, items are writeable).
int nItems	Number of items in total (read-only).
int nVisible	Number of items on screen (read-only).
Uint pollDelay	Delay in between updates in AG_TLIST_POLL mode (ms).

For the AG_TlistItem structure:

int selected	Selection flag.
*void p1**	User pointer.
*const char cat**	User "category" string (application-specific usage).
char text[]	Text to display (limit of AG_TLIST_LABEL_MAX bytes).
int depth	Depth in tree display.
Uint flags	Item flags (see ITEM FLAGS section below).
Uint fontFlags	Font style (see AG_FetchFont(3) for available flags).

ITEM FLAGS

AG_TLIST_ITEM_EXPANDED	The node is expanded and child items are visible.
AG_TLIST_HAS_CHILDREN	There is at least one child item.
AG_TLIST_NO_SELECT	Disallow user selection of this item.
AG_TLIST_NO_POPUP	Disable popup menus (if any have been created).

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_TLIST_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_ITEM_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);

HISTORY

The AG_Tlist widget first appeared in Agar 1.0. The option called AG_TLIST_TREE was deprecated and has no effect as of Agar 1.6.0. AG_TlistSelectIdx(), AG_TlistDeselectIdx(), AG_TlistSetColor(), AG_TlistSetFont() and per-item fontFlags appeared in Agar 1.6.0.