Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.
SYNOPSIS
#include <agar/core.h> #include <agar/gui.h> |
DESCRIPTION
The
AG_Menu widget displays a hierarchical menu composed of items of the following types:
Menu elements can be displayed in text format with the AG_MenuView widget, or in icon format using AG_Toolbar(3). Note: Many functions of AG_Menu accept fn and fnArgs arguments; see AG_Event(3) for details on event handler functions in Agar. |
INHERITANCE HIERARCHY
| AG_Object(3)-> AG_Widget(3)-> AG_Menu. |
INITIALIZATION
|
The AG_MenuNew() function allocates, initializes, and attaches a new AG_Menu widget. Acceptable flags include:
The AG_MenuNewGlobal() constructor creates a global "application menu". The manner in which application menus are displayed is dependent on the underlying platform and graphics system. If there is insufficient memory, or an application menu is already defined, AG_MenuNewGlobal() may fail returning NULL. The AG_MenuExpand() function creates a new window containing an AG_MenuView widget displaying the menu items under item. The parentWidget argument should point to some parent widget responsible for triggering the popup menu. If there is none, NULL may be passed. The window is created at coordinates x, y relative to parentWidget (if parentWidget is NULL, the coordinates are relative to the upper left corner of the view area). AG_MenuCollapse() closes a window previously created by AG_MenuExpand(). It is safe to invoke AG_MenuExpand() and AG_MenuCollapse() from a widget's event handler. AG_MenuSetPadding() sets the global padding around all menu items, in pixels. AG_MenuSetLabelPadding() sets the padding around the text label of items. If a parameter is -1, its current value is preserved. |
MENU ITEMS
|
The AG_MenuNode() function inserts a new node (no-op) item displaying the given text and icon (or NULL if none). Node items are typically only used to attach subitems. The AG_MenuAction() function inserts a new action item displaying the given text and icon (or NULL if none). When selected, the item will invoke the specified event handler function fn. The AG_MenuActionKb() variant also associates the action with the given AG_KeySym(3) and modifier. The AG_MenuTool() variant also inserts an item into the specified AG_Toolbar(3) widget. The AG_MenuSetIcon() function sets the icon associated with a menu item. If an argument of NULL is given, any existing icon is removed. AG_MenuSetLabel() changes the text associated with an existing menu item. AG_MenuSetPollFn() changes the callback function associated with a given item (previously created with AG_MenuDynamicItem()). The AG_MenuDynamicItem() function creates a dynamic menu item. The specified callback routine fn will be invoked repeatedly to update the menu item. The AG_Menu object is passed as AG_SELF(), and pointer to the AG_MenuItem structure can be retrieved using AG_SENDER() (see AG_Event(3)). The callback routine is allowed to directly modify the state member of the AG_MenuItem. This variable defines the boolean state for the specified menu item (0 = disabled, 1 = enabled). If state is -1, the boolean state is determined from any boolean/flag binding associated with the item. The callback can also change the text label and icon using AG_MenuSetLabel() and AG_MenuSetIcon(). The AG_MenuItemFree() function destroys the given menu item as well as its children. The AG_MenuState() (or its variants AG_MenuEnable() and AG_MenuDisable()) request that all subsequently created menu items are assigned the given state. |
BOOLEAN AND BITMASK ITEMS
OTHER ITEMS
The AG_MenuSeparator() function inserts a horizontal menu separator. AG_MenuSection() creates a non-selectable item displaying the given text. |
POPUP MENUS
The AG_PopupNew() function creates a new popup menu and associates it with the specified widget. This association will cause the popup menu to be automatically freed when the given widget is destroyed. Once a popup menu is created, new items can be inserted using the item member of the AG_PopupMenu structure as parent. AG_PopupShow() displays the popup menu at the current mouse coordinates. AG_PopupShowAt() accepts global (view) coordinates. AG_PopupHide() hides the popup menu from the user. AG_PopupDestroy() detaches the specified popup menu from its associated widget, and releases its allocated resources. This function is automatically invoked whenever a widget is destroyed. |
EVENTS
The
AG_Menu widget reacts to the following events:
The AG_Menu widget does not generate any event. |
BINDINGS
| The AG_Menu widget does not provide any binding. |
STRUCTURE DATA
For the
AG_Menu object:
For the AG_MenuItem structure:
|
EXAMPLES
The following code fragment associates a menu with an
AG_Toolbar(3). Buttons and menu entries are created for the same actions.
AG_Toolbar *toolbar;
AG_Menu *menu;
AG_MenuItem *item;
toolbar = AG_ToolbarNew(win, AG_TOOLBAR_HORIZ, 1, 0);
menu = AG_MenuNew(win, 0);
item = AG_MenuNode(menu->root, "File", NULL);
{
AG_MenuToolbar(item, toolbar);
AG_MenuAction(item, "Load", NULL, LoadFile, NULL);
AG_MenuAction(item, "Save", NULL, SaveFile, NULL);
AG_MenuToolbar(item, NULL);
}
The following code fragment creates a menu with an action item, a boolean item and two bitmask items. Uint16 flags = 0;
#define FOO_FLAG 0x01
#define BAR_FLAG 0x02
void
SayHello(AG_Event *event)
{
char *s = AG_STRING(1);
AG_TextMsg(AG_MSG_INFO, "Hello, %s!", s);
}
void
QuitApplication(AG_Event *event)
{
AG_Quit();
}
Li ...AG_Menu *menu = AG_MenuNew(win);
AG_MenuItem *item = AG_MenuNode(menu->root, "File", NULL);
{
AG_MenuInt16Flags(item, "Foo", NULL, &flags, FOO_FLAG, 0);
AG_MenuInt16Flags(item, "Bar", NULL, &flags, BAR_FLAG, 0);
AG_MenuAction(item, "Say hello", NULL,
SayHello, "%s", "world");
AG_MenuAction(item, "Quit", NULL,
QuitApplication, NULL);
}
|
SEE ALSO
| AG_Intro(3), AG_Event(3), AG_KeySym(3), AG_Button(3), AG_Surface(3), AG_Toolbar(3), AG_Tlist(3), AG_Widget(3), AG_Window(3) |
HISTORY
| The AG_Menu widget first appeared in Agar 1.0. |
