Agar

Agar 1.7 Manual

(Printable Version)
AG_UCombo(3)

SYNOPSIS

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

DESCRIPTION

The 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.
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_TlistAdd(com, NULL, "Foo");
	AG_TlistAdd(com, NULL, "Bar");
}

static void
ComboSelected(AG_Event *event)
{
	AG_TlistItem *item = AG_TLIST_ITEM_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. The AG_Tlist(3) was formerly pre-generated and attached to the window on expand, but for safety reasons as of Agar 1.7.0 the list member is now initialized to NULL and the list must be generated on demand (typically from "ucombo-expanded").
Csoft.net ElectronTubeStore