Agar Logo

Agar 1.7 Manual

(Printable Version)
AG_UCombo(3)

SYNOPSIS

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

DESCRIPTION

ScreenshotThe AG_UCombo widget displays an AG_Button(3) which triggers the expansion of 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_UCombo area.

INHERITANCE HIERARCHY

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

INITIALIZATION


AG_UCombo * AG_UComboNew (AG_Widget *parent, Uint flags)

void AG_UComboSizeHint (AG_UCombo *com, const char *text, int nitems)

void AG_UComboSizeHintPixels (AG_UCombo *com, int w, int h)


The AG_UComboNew() function allocates, initializes, and attaches a new AG_UCombo widget. Acceptable flags include:
AG_UCOMBO_SCROLLTOSELScroll to initial selection if it is not visible.
AG_UCOMBO_HFILLExpand horizontally in parent container.
AG_UCOMBO_VFILLExpand vertically in parent container.
AG_UCOMBO_EXPANDShorthand for AG_UCOMBO_HFILL AG_UCOMBO_VFILL|.

AG_UComboSizeHint() 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_UComboSizeHintPixels() variant specifies the size of the list in pixels.

EVENTS

The AG_UCombo widget generates the following events:
ucombo-selected (AG_TlistItem *item)
An item was selected.
ucombo-expanded (void)
The drop-down menu is now visible. May be used to populate list.
ucombo-collapsed (void)
The drop-down menu is now hidden.

STRUCTURE DATA

For the AG_UCombo object:
AG_Tlist *list The AG_Tlist(3) displayed by AG_UCombo when expanded, or NULL if collapsed (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
ComboExpanded(AG_Event *event)
{
	AG_UCombo *com = AG_UCOMBO_SELF();
	AG_Tlist *tl = com->list;

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

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

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

AG_UCombo *com;

com = AG_UComboNew(NULL, 0);
AG_SetEvent(com, "ucombo-expanded", ComboExpanded, NULL);
AG_SetEvent(com, "ucombo-selected", ComboSelected, NULL);

SEE ALSO


HISTORY

The AG_UCombo widget first appeared in Agar 1.0. "ucombo-expanded" and "ucombo-selected" appeared in Agar 1.7.0.

Csoft.net ElectronTubeStore