SYNOPSIS
|
DESCRIPTION
![]() 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
MANIPULATING ITEMS
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
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:
|
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.
|
SEE ALSO
AG_Intro(3), AG_Table(3), AG_Treetbl(3), AG_Widget(3), AG_Window(3) |
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. |