OpenGLUT 0.6.3 development - OpenGLUT: Menu Management
Keywords: OpenGLUT, FreeGLUT, OpenGL, GLUT, X11, Windows, Programming, Documentation, Download, Development, Sourceforge

OpenGLUT Documentation
Introduction | Documentation | Examples | Proposals | Authors | Copying | Todo | Bugs | Links

# 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 FREEGLUT_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(* | callback)(int value) | ) |

  | 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()

OpenGLUT Development @ Sourceforge
Homepage | Summary | Files | CVS | Forums | Lists | Bugs | RFE
Generated on Tue Oct 5 18:44:33 2004 for OpenGLUT by doxygen 1.3.8
The OpenGLUT project is hosted by sourceforge.net.