Agar
Agar 1.7 Manual

AG_Combo(3)

SYNOPSIS

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

DESCRIPTION

ScreenshotScreenshotThe AG_Combo widget packs a AG_Textbox(3) widget next to a AG_Button(3) which triggers the expansion of a drop-down menu (a window containing an AG_Tlist(3)) when pressed. The drop-down menu collapses if the user selects an item, or clicks outside of the AG_Combo area.

AG_Combo provides the same functionality as AG_UCombo(3), but also adds support for text search and arbitrary text input.

INHERITANCE HIERARCHY

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

INITIALIZATION


AG_Combo * AG_ComboNew (AG_Widget *parent, Uint flags, const char *format, ...)

AG_Combo * AG_ComboNewS (AG_Widget *parent, Uint flags, const char *label)

void AG_ComboSizeHint (AG_Combo *combo, const char *text, int nitems)

void AG_ComboSizeHintPixels (AG_Combo *combo, int w, int nitems)


The AG_ComboNew() function allocates, initializes, and attaches a new AG_Combo widget. The string argument specifies an optional text label to be displayed at the left of the textbox. Acceptable flags include:
AG_COMBO_POLLList contents are dynamic (pass the AG_TLIST_POLL flag to the tlist).
AG_COMBO_ANY_TEXTAllow user to enter text that does not match any item in the list.
AG_COMBO_SCROLLTOSELScroll to initial selection if it is not visible.
AG_COMBO_HFILLExpand horizontally in parent container.
AG_COMBO_VFILLExpand vertically in parent container.
AG_COMBO_EXPANDShorthand for AG_COMBO_HFILL AG_COMBO_VFILL|.

The AG_ComboSizeHint() function arranges for the AG_Tlist(3) widget displayed on popup to request a size large enough to display the given number of items. The AG_ComboSizeHintPixels() variant specifies the width in number of pixels.

ITEM SELECTION


void AG_ComboSelect (AG_Combo *combo, AG_TlistItem *item)

AG_TlistItem * AG_ComboSelectPointer (AG_Combo *combo, void *ptr)

AG_TlistItem * AG_ComboSelectText (AG_Combo *combo, const char *text)


The AG_ComboSelect() function sets the selection flag on the given item.

The AG_ComboSelectPointer() function selects the first item with a user pointer value matching ptr. Similarly, AG_ComboSelectText() selects the first item with a text string equal to text.

If the AG_COMBO_POLL option is set, both AG_ComboSelectPointer() and AG_ComboSelectText() will raise a tlist-poll event prior to making the selection.

EVENTS

The AG_Combo widget generates the following events:
combo-selected (AG_TlistItem *item)
An item was selected.
combo-expanded (void)
The drop-down menu is now visible.
combo-collapsed (void)
The drop-down menu is now hidden.
combo-text-entry (const char *text)
The AG_COMBO_ANY_TEXT option is set and the user has entered a string text which does not match any item in the list.
combo-text-unknown (const char *text)
The AG_COMBO_ANY_TEXT flag is not set and the user has entered a string text which does not match any item in the list.

STRUCTURE DATA

For the AG_Combo object:
AG_Tlist *list The AG_Tlist(3) displayed by AG_Combo when expanded, or NULL if collapsed (RO).
AG_Textbox *tbox The input AG_Textbox(3) (RO).
AG_Button *button The AG_Button(3) which triggers expansion (RO).

EXAMPLES

The following code fragment generates a drop-down menu and reacts to a selection event by displaying a text dialog:
static void
ExpandItems(AG_Event *event)
{
	AG_Combo *com = AG_COMBO_SELF();

	AG_TlistAdd(com, NULL, "Foo");
	AG_TlistAdd(com, NULL, "Bar");
}

static void
SelectItem(AG_Event *event)
{
	AG_TlistItem *item = AG_TLISTITEM_PTR(1);

	AG_TextMsg(AG_MSG_INFO, "Selected item: %s", item->text);
}

AG_Combo *com;

com = AG_ComboNew(NULL, 0);
AG_SetEvent(com, "combo-expanded", ExpandItems, NULL);
AG_SetEvent(com, "combo-selected", SelectItem, NULL);

The following code fragment generates a drop-down menu displaying a tree:
static void
ExpandTreeItems(AG_Event *event)
{
	AG_Combo *com = AG_COMBO_SELF();
	AG_TlistItem *it;

	it = AG_TlistAdd(com, NULL, "Foo");
	it->depth = 1;
	it->flags |= AG_TLIST_HAS_CHILDREN;
	{
		it = AG_TlistAdd(com, NULL, "Bar");
		it->depth = 2;
		it = AG_TlistAdd(com, NULL, "Baz");
		it->depth = 2;
	}
}

AG_Combo *com;

com = AG_ComboNew(NULL, 0);
AG_SetEvent(com, "combo-expanded", ExpandTreeItems, NULL);

SEE ALSO

AG_Button(3), AG_Intro(3), AG_Textbox(3), AG_Tlist(3), AG_UCombo(3), AG_Widget(3), AG_Window(3)

HISTORY

The AG_Combo widget first appeared in Agar 1.0. As of Agar 1.6.0, AG_COMBO_TREE is a deprecated no-op. "combo-expanded" and "combo-selected" appeared in Agar 1.7.0. The AG_Tlist(3) was formerly pre-generated and attached to the window on expansion, but as of Agar 1.7.0 the list member is now initialized to NULL and the list contents must be generated on demand from "combo-expanded".


Csoft.net ElectronTubeStore www.libAgar.org is © 2022 Julien Nadeau Carriere <vedge@csoft.net>.
Support LibAgar: www.patreon.com/libAgar.