Menu Management
[OpenGLUT API Reference]

Functions
void	glutAddMenuEntry (const char *label, int value)
void	glutAddSubMenu (const char *label, int subMenuID)
void	glutAttachMenu (int button)
void	glutChangeToMenuEntry (int item, const char *label, int value)
void	glutChangeToSubMenu (int item, const char *label, int subMenuID)
int	glutCreateMenu (void(*callback)(int value))
void	glutDestroyMenu (int menuID)
void	glutDetachMenu (int button)
int	glutGetMenu (void)
void *	glutGetMenuData (void)
void	glutRemoveMenuItem (int item)
void	glutSetMenu (int menuID)
void	glutSetMenuData (void *data)

---

Detailed Description

OpenGLUT provides an implementation of GLUT-like cascading text menus. The menus are basically association lists: A string of text is associated either with an integer or with a submenu. If with a submenu, then dragging the mouse over the submenu's name brings up the submenu. Submenu items can in turn have items with menus-or-integers. This allows you to nest menus to any desired depth.

Actual action generally occurs when an integer-bound item is selected. The integer can be any integer of the application's choosing, provided that it fits into a variable of type int. Enumerated values, array indices, and OpenGL and OpenGLUT ids are common choices. The item selection is handed to a menu callback that you specify via glutCreateMenu(). (Each menu can have its own callback, or you can use one callback for all menus, or something inbetween, according to your application's needs snf your own preferences.)

The original GLUT documentation disclaimed GLUT menus as being an attempt at ``a full-featured user interface''. Certainly, the GLUT menus are limited, but they are functional. At present, they are the only officially supported mechanism for creating practical menus. (Using subwindows in your own application window is possible, but the possibility of having your menus occluded by other applications' windows is a bit irritating.)

The following comment appeared in at least three spots in the freeglut code. Here in OpenGLUT we consolidate it into this overview, which seems more appropriate and useful. It appears to be an analysis of how old GLUT worked on WIN32 (it certainly is very different from old GLUT on X11). Some of the freeglut, hence OpenGLUT, menu problems seem to arise from trying to emulate the WIN32 behavior.

Do not execute the application's mouse callback if a menu is hooked to this button. In that case an appropriate private call should be generated.

Near as I can tell, this is the menu behaviour:

• Down-click the menu button, menu not active: activate the menu with its upper left-hand corner at the mouse location.
• Down-click any button outside the menu, menu active: deactivate the menu
• Down-click any button inside the menu, menu active: select the menu entry and deactivate the menu
• Up-click the menu button, menu not active: nothing happens
• Up-click the menu button outside the menu, menu active: nothing happens
• Up-click the menu button inside the menu, menu active select the menu entry and deactivate the menu

---

Function Documentation

void glutAddMenuEntry (  const char *  label, int  value )

Append an item to the current menu. Parameters: label  Menu item text value  Menu item callback value Inserts a given (label, value) pair into the current menu. label is the text displayed in the menu; value is the identifier received by the callback when the item is selected. The new entry is added to the end of the menu. See also: glutAddSubMenu(), glutChangeToMenuEntry(), glutChangeToSubMenu(), glutRemoveMenuItem()

void glutAddSubMenu (  const char *  label, int  subMenuID )

Append a submenu to the current menu. Parameters: label  Submenu item text subMenuID  Submenu identifier Attaches an existing menu as a submenu of the current menu. label is the text used for the item in the menu. subMenuID is the identifier of an existing menu to be appended as a submenu. The submenu is added to the end of the menu. See also: glutCreateMenu(), glutAddMenuEntry()

void glutAttachMenu (  int  button  )

Attach the current menu to the current window. Parameters: button  Mouse button to bind to Associates the button with the current menu in the current window. Todo: Assumes 3 mouse buttons. (Actually OPENGLUT_MAX_MENUS holds the assumed number of buttons.) Cannot bind to more buttons. Will not issue any warnings or errors if the user does not have enough buttons to reach your menu. See also: glutCreateMenu(), glutSetMenu(), glutDetachMenu(),

void glutChangeToMenuEntry (  int  item, const char *  label, int  value )

Replace a menu entry with an item. Parameters: item  Integer position down the list label  Menu item text value  Menu item callback value Walks the list of the menu items and replaces the numbered item in the list with the given definition. Except that it replaces a pre-existing item, this function is much like glutAddMenuEntry(). See also: glutAddMenuEntry(), glutAddSubMenu(), glutChangeToSubMenu(), glutRemoveMenuItem()

void glutChangeToSubMenu (  int  item, const char *  label, int  subMenuID )

Replace a menu entry with a submenu. Parameters: item  Integer position down the list label  Submenu item text subMenuID  Submenu identifier Walks the list of the menu items and replaces the numbered item in the list with the given submenu. See also: glutAddMenuEntry(), glutAddSubMenu(), glutChangeToMenuEntry(), glutRemoveMenuItem()

int glutCreateMenu (  void(*)(int value)  callback  )

Create a new menu. Parameters: callback  Client hook for the new menu. Create a menu with a callback bound to callback, and return the menu's integer id. When the user makes a selection from this menu, callback is invoked with the parameter value, which comes from the (label, value) pair that is defined with glutAddMenuEntry(). See also: glutAddMenuEntry(), glutAddSubMenu(), glutDestroyMenu()

void glutDestroyMenu (  int  menuID  )

Destroy a menu. Parameters: menuID  The menu to destroy. Destroys a given menu object by its ID. See also: glutCreateMenu()

void glutDetachMenu (  int  button  )

Detach menu from the current window. Parameters: button  Mouse button to unbind from. If the given button has a menu bound to it, this breaks the assocation. See also: glutCreateMenu, glutDestroyMenu(), glutAttachMenu()

int glutGetMenu (  void   )

Get the current menu ID. Returns the integer ID of the current menu. See also: glutSetMenu()

void* glutGetMenuData (  void   )

Retrieve menu user data pointer. Retrieve a previously stored user data pointer from the current menu. See also: glutSetMenuData()

void glutRemoveMenuItem (  int  item  )

Remove a given menu item. Parameters: item  Integer position down the list Walks the list of the menu items and deletes the numbered item in the list. See also: glutAddMenuEntry(), glutAddSubMenu(), glutChangeToMenuEntry(), glutChangeToSubMenu()

void glutSetMenu (  int  menuID  )

Set the current menu ID. Parameters: menuID  Selected menu Set the current menu to the specified menuID. See also: glutGetMenu()

void glutSetMenuData (  void *  data  )

Store menu user data pointer. Parameters: data  Client pointer data glutSetMenuData() associates an arbitrary user data pointer, data, with the current menu. OpenGLUT does not interpret this pointer in any way, but merely stores it for you in the menu structure. See also: glutGetMenuData()

Generated on Sat Feb 5 01:47:29 2005 for OpenGLUT by doxygen 1.3.9.1
The OpenGLUT project is hosted by sourceforge.net.