NAME

SYNOPSIS

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

DESCRIPTION

The AG_Table(3) and AG_Treetbl(3) widgets are more efficient alternatives to AG_Tlist.

INHERITANCE HIERARCHY

INITIALIZATION

AG_Tlist *
AG_TlistNewPolled(AG_Widget *parent, Uint flags, 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_TlistSetIcon(AG_Tlist *tl, AG_TlistItem *item, AG_Surface *icon);

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 sets the AG_TLIST_POLL flag and configures a default ‘tlist-poll’ event handler.

Acceptable flags include:

AG_TLIST_MULTI

Allow the user to select multiple items while holding CTRL or SHIFT.

AG_TLIST_MULTITOGGLE

Allow the user to select multiple items without holding CTRL or SHIFT.

AG_TLIST_POLL

List contents are updated dynamically by the ‘tlist-poll’ event handler (implied by AG_TlistNewPolled()). Note that it is necessary to use AG_TlistBegin() and AG_TlistEnd() when updating a dynamic list.

AG_TLIST_TREE

List contents are organized in a tree structure.

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 (equivalent to invoking AG_ExpandHoriz(3)).

AG_TLIST_VFILL

Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).

AG_TLIST_EXPAND

Shorthand for AG_TLIST_HFILL|AG_TLIST_VFILL. This is recommended as an alternative to AG_TlistSizeHint(), AG_TlistSizeHintPixels() or AG_TlistSizeHintLargest().

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

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

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

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

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

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

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_TlistSelectAll(AG_Tlist *tlist);

void
AG_TlistDeselect(AG_Tlist *tlist, AG_TlistItem *item);

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

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

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_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

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

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

TAILQ items

List of all AG_TlistItem objects (read-only, items are writeable).

int nitems

Number of items in the list (read-only).

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 (for AG_TLIST_TREE).

Uint8 flags

Item flags (see ITEM FLAGS section below).

ITEM FLAGS

AG_TLIST_EXPANDED

Indicates that the child items should be displayed (the AG_TLIST_TREE flag must be set).

AG_TLIST_HAS_CHILDREN

Indicates that this item has a non-zero number of child items.

AG_TLIST_NO_SELECT

Disallow user selection of this item.

AG_TLIST_NO_POPUP

If popup menus are in effect, disable popups for this item.

EXAMPLES

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 tests/themes.c in the Agar source distribution.

SEE ALSO

HISTORY