SYNOPSIS

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

DESCRIPTION

The AG_Tlist widget shows a scrollable tree / list of clickable and selectable items. Items can display text and icons. Items include user-defined data fields (a signed integer v, an unsigned integer u, a user pointer p1 and a general-purpose category string cat).

For cases where the contents of the tree or list may change externally, a polling routine may be defined. Such a routine is expected to clear and repopulate the list entirely. It may be run periodically at a specified interval, whenever user interaction events occur, or by explicit call to AG_TlistRefresh(). To make polling more efficient (and to preserve per-item states such as selections across polling cycles), AG_Tlist relies on a compare function to test items for equivalence and reuse assets (including allocated structures and rendered text surfaces).

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, ...)

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

The AG_TlistNewPolled() variant enables AG_TLIST_POLL and sets the specified polling routine eventFn to run periodically (or -1 = never). The polling routine is expected to clear and populate the AG_Tlist. The AG_TlistNewPolledMs() variant sets the update rate to ms milliseconds.

Acceptable flags include:

AG_TLIST_EXPAND_NODES	Expand nodes with child items by default.
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" handler. This handler is expected to wrap its AG_TlistAdd() calls between AG_TlistBegin() and AG_TlistEnd(). Implied by AG_TlistNewPolled().
AG_TLIST_FIXED_HEIGHT	Don't reset the item height on "font-changed".
AG_TLIST_NO_LINES	Don't draw lines between nodes.
AG_TLIST_NO_KEYREPEAT	Disable keyrepeat behavior.
AG_TLIST_NO_SELECTED	Don't raise "tlist-selected" on select.
AG_TLIST_STATELESS	When using AG_TLIST_POLL, don't 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() sets the rate at which the polling routine will be invoked in milliseconds (default = 1s). A value of -1 disables automatic updates. When automatic updates are disabled, updates can be performed by calling AG_TlistRefresh(). See the AG_TLIST_POLL option for details.

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.

COMPARE FUNCTIONS

AG_TlistCompareFn AG_TlistSetCompareFn (AG_Tlist *tl, AG_TlistCompareFn fn)

int AG_TlistCompareInts "const AG_TlistItem *a, const AG_TlistItem *b)

int AG_TlistCompareUints "const AG_TlistItem *a, const AG_TlistItem *b)

int AG_TlistCompareStrings "const AG_TlistItem *a, const AG_TlistItem *b)

int AG_TlistComparePtrs "const AG_TlistItem *a, const AG_TlistItem *b)

int AG_TlistComparePtrsAndCats "const AG_TlistItem *a, const AG_TlistItem *b)

In order for AG_Tlist to be able to preserve per-item states (such as selections) through polling updates when using a polling function, it is necessary to be able to establish equivalence between items. The nature of this equivalence is application-defined and is determined by the compare function selected. The AG_TlistUniq() routine (see below) also relies on the compare function.
AG_TlistSetCompareFn() sets the comparison function to use when testing between two AG_TlistItem for equivalence. It returns a pointer to the previously selected compare function. Compare functions are defined as:

typedef int (*AG_TlistCompareFn)(const AG_TlistItem *a,
	                         const AG_TlistItem *b);

It is expected to return 0 if the two items are equivalent and non-zero if the items are not. If the returned value if non-zero, it can be used to define the sorting order. Returning a positive value in the case where (a > b) should produce a sort in descending order.
Some basic compare functions are provided:
AG_TlistCompareInts() compares the signed integer field v1.
AG_TlistCompareUints() compares the unsigned integer field u.
AG_TlistCompareStrings() compares the text strings lexicographically. The comparison is case-sensitive and ignores any locale collation.
AG_TlistComparePtrs() compares the pointer fields p1. This is the default compare function.
AG_TlistComparePtrsAndCats() compares both p1 and the category cat.

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 *tl, const AG_Surface *icon, const char *text, const void *p1)

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

void AG_TlistMoveToHead (AG_Tlist *tl, AG_TlistItem *item)

void AG_TlistMoveToTail (AG_Tlist *tl, AG_TlistItem *item)

void AG_TlistCopy (AG_Tlist *tlDst, const AG_Tlist *tlSrc)

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, const char *face, float scale, Uint flags)

void AG_TlistDel (AG_Tlist *tl, AG_TlistItem *item)

void AG_TlistSort (AG_Tlist *tl)

void AG_TlistSortByInt (AG_Tlist *tl)

void AG_TlistUniq (AG_Tlist *tl)

void AG_TlistClear (AG_Tlist *tl)

void AG_TlistBegin (AG_Tlist *tl)

void AG_TlistEnd (AG_Tlist *tl)

int AG_TlistVisibleChildren (AG_Tlist *tl, AG_TlistItem *item)

void AG_TlistSelect (AG_Tlist *tl, AG_TlistItem *item)

void AG_TlistSelectIdx (AG_Tlist *tl, Uint index)

void AG_TlistSelectAll (AG_Tlist *tl)

void AG_TlistDeselect (AG_Tlist *tl, AG_TlistItem *item)

void AG_TlistDeselectIdx (AG_Tlist *tl, Uint index)

void AG_TlistDeselectAll (AG_Tlist *tl)

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

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

AG_TlistItem * AG_TlistFindByIndex (AG_Tlist *tl, int index)

AG_TlistItem * AG_TlistSelectedItem (AG_Tlist *tl)

void * AG_TlistSelectedItemPtr (AG_Tlist *tl)

void * AG_TLIST_ITEM (idx)

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

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

AG_TlistItem * AG_TlistFirstItem (AG_Tlist *tl)

AG_TlistItem * AG_TlistLastItem (AG_Tlist *tl)

void AG_TlistScrollToStart (AG_Tlist *tl)

void AG_TlistScrollToEnd (AG_Tlist *tl)

void AG_TlistScrollToSelection (AG_Tlist *tl)

AG_TlistAdd() inserts a newly-allocated item into the list and returns a pointer to it. If icon is not NULL, it specifies an AG_Surface(3) to duplicate and display as an icon.

The AG_TlistAddHead() variant places the item at the head of the list. The AG_TlistAddPtr() variant of AG_TlistAdd() also sets the pointer field p1 on initialization.

AG_TlistAddPtrHead() places the item at the head of the list.

AG_TlistMoveToHead() moves an existing item item to the head of the list. AG_TlistMoveToTail() moves an existing item item to the tail of the list.

The AG_TlistCopy() routine copies all items from tlSrc into tlDst. Item attributes and selection flags are preserved.

AG_TlistSetIcon() sets the icon surface associated with item. A duplicate of the given surface will be used.

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. If face is NULL, use the same font face as the tlist's font. scale sets the size of the font relative to the tlist's font. If scale is 1.0f then the same size will be used. The flags argument is the set of AG_Font(3) style flags (such as AG_FONT_BOLD).

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

The AG_TlistSort() routine lexicographically sorts the items in the list by text according to the current locale collation.

AG_TlistSortByInt() sorts items based on their integer values v.

AG_TlistUniq() scans the list for duplicates and removes them. AG_TlistUniq() uses the compare function to determine equivalence between items (see AG_TlistSetCompareFn()).

AG_TlistClear() removes all items attached to the list.

The AG_TlistBegin() function removes all items attached to tl, but remembers their selection and child item expansion states. AG_TlistEnd() compares each item against the saved state and restores the selection and child item expansion states accordingly.

The AG_TlistVisibleChildren() function is meant to be called from a polling routine. It tests whether a newly-created item should make its own child items visible based on the previously saved state. If there are no matching items in the saved state (according to the Compare function), then it returns the default visibility setting (which is 1 if the AG_TLIST_EXPAND_NODES option is set, otherwise 0).

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

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 tl 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 and AG_TlistScrollToEnd() scrolls the display to the end of the list.

AG_TlistScrollToSelection() scrolls to make the first selected item visible. It's a no-op if there are no selected items.

POPUP MENUS

AG_MenuItem * AG_TlistSetPopupFn (AG_Tlist *tl, AG_EventFn fn, const char *fn_args, ...)

AG_MenuItem * AG_TlistSetPopup (AG_Tlist *tl, 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	The list of items (linkage is read-only).
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 (application-defined).
int v	User signed integer value (application-defined).
Uint u	User unsigned integer value (application-defined).
*const char cat**	Category string (application-defined).
char text[]	Text label (up to AG_TLIST_LABEL_MAX characters).
int depth	Depth in tree (0 = root).
Uint flags	Item flags (see ITEM FLAGS section below).
float scale	Scaling factor for text display (default = 1.0).

ITEM FLAGS

AG_TLIST_ITEM_DISABLED	Disable selection and draw in DISABLED style.
AG_TLIST_NO_SELECT	Disable selection and draw in DEFAULT style.
AG_TLIST_ITEM_EXPANDED	Child items are visible.
AG_TLIST_HAS_CHILDREN	At least one child item exists.
AG_TLIST_NO_POPUP	Disable popup menus (if any have been created).

EXAMPLES

The following code fragment displays an external tree structure using a recursive polling routine.

MyTreeNode *myTreeRoot;
AG_Window *win;

static void
PollMyTreeNode(AG_Tlist *tl, MyTreeNode *node, int depth)
{
	AG_TlistItem *ti;

	ti = AG_TlistAdd(tl, NULL, "Node %s", node->name);
	ti->flags |= AG_TLIST_HAS_CHILDREN;
	ti->p1 = node;
	ti->depth = depth;

	if (AG_TlistVisibleChildren(tl, ti)) {
		MyTreeNode *child;

		LIST_FOREACH(child, &node->children, children)
			PollMyTreeNode(tl, child, depth+1);
	}
}

static void
PollMyTree(AG_Event *event)
{
	AG_Tlist *tl = AG_TLIST_SELF();
	MyTreeNode *root = AG_PTR(1);

	AG_TlistBegin(tl);
	PollMyTreeNode(tl, root, 0);
	AG_TlistEnd(tl);
}

myTreeRoot = InitMyTree();
win = AG_WindowNew(0);
AG_TlistNewPolled(win, 0, PollMyTree, "%p", myTreeRoot);

HISTORY

The AG_Tlist widget first appeared in Agar 1.0. AG_TlistSelectIdx(), AG_TlistDeselectIdx(), AG_TlistSetColor() and AG_TlistSetFont() appeared in Agar 1.6.0. Options AG_TLIST_EXPAND_NODES, AG_TLIST_FIXED_HEIGHT, AG_TLIST_NO_LINES, AG_TLIST_NO_KEYREPEAT and the per-item flag AG_TLIST_ITEM_DISABLED appeared in Agar 1.7.0. The u and v integer fields and AG_TlistCompareInts() and AG_TlistCompareUints() appeared in Agar 1.7.0.