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

OpenGLUT Menu Window Proposal

This is a proposal for the purpose of discussion and discussion. This API is not currently implemented in OpenGLUT.

The "unmanaged" demo with custom menu; experimental

This proposal seeks to define, and justify, client-controlled menu windows. An experimental implementation is currently provided in OpenGLUT, per the outline below. It is not formally endorsed, but application developers are encouraged to use it and provide feedback on its utility. See also the unmanaged demo. (So-called because the feature originally used a GLUT_UNMANAGED display mode flag to glutInitDisplaymode().)

The Problem.

OpenGLUT has inherited a menu API indirectly from the old GLUT, and an implementation of same directly from freeglut.

The API limits one to pop-up windows, rather than pull-down windows. They can only contain text, of a single predefined font, in two predefined colors (plus a beveling box). The layout is strictly linear, with the positioning determiend by fixed logic in the OpenGLUT library---there is no option to open the menu such that the "current" choice, in a multiway selection, is near the mouse. Nor is there any facility to navigate menus via keyboard (a major feature that some have noted as lacking in GLUT/freeglut/OpenGLUT menus).

The freeglut implementation suffers from bugs that leave multiple menus hanging onscreen, and can make menu selection unnatural. E.g., if one holds down the menu button to bring up a menu, selects an item that has a sub-menu attached, and (still holding the mouse button down), drags over to the sub-menu, finally letting go over a sub-menu item, OpenGLUT fails to properly respond to the selection of the sub-menu item.

While the GLUT API is functional, and it is possible to use the implementation, there is no provision for clients to create their own menus to work around the limitations and bugs.

The Anomaly.

For the most part, GLUT defines fairly atomic, low-level behavior. The GUI elements provided are mouse-clicks, windows, drawing regions, and keyboard input. To build a slider or a file requester you have to do some real work.

Menus stand out as anomalies. In old GLUT, this made more sense, since old GLUT didn't actually work very hard; apparently, old GLUT used system menus. freeglut works very hard for its menus, in contrast. freeglut menus are much more complex than a simple GUI slider, and are probably about as complex as a fairly usable file-requester. Yet the API provided is stilted and limiting, because old GLUT was aiming for simplicity.

The Proposal.

There are a few options open to improve on things:

  1. Revert to old GLUT's approach of using system menus. While this would not improve the flexibility, it would simplify OpenGLUT and remove most or all menu related bugs.
  2. Tell clients to use subwindows for custom menus, or regular top-level onscreen windows. This would work for proof-of-concept type menus, but would not work for more serious GUI support.
  3. Fix some of the bugs in the freeglut/OpenGLUT implementation of GLUT-style menus. This would still leave the API inflexible.
  4. Extend the API with more controls and options. The challenge here is to find an API that is flexible enough without introducing too much complication to OpenGLUT. This also leaves old bugs unaddressed.
  5. Expose the underlying mechanism of menu-creation and perhaps remove the GLUT-style menus altogether. The problem here is that you get "atoms" again, and must build up menus from more elementary pieces. But, a GUI programmer already doing buttons and sliders and input fields with the OpenGLUT API should feel at home.

These are not all mutually incompatible, of course. And unless the old style GLUT menus are removed altogether, OpenGLUT should try to eliminate bugs in the old GLUT menu API.

However, this proposal asserts that exposing the mechanism for controlling menu windows is more in line with the GLUT approach to GUI construction, and is also simple to attain with what we already have.

The Definition.

A working definition is that menu windows appear exactly as do freeglut/OpenGLUT windows created by the menu system---save that the ones created by the client directly are to be placed under client control as much as possible. This is deliberately vague, since there is no OpenGLUT definition for what the old style popup menus should be like. This definition is open for modification, however.

A menu window is a pop-up window that may be placed anywhere by the application. Although system resources may always preclude any attempted operation, menu windows more closely respect the programmer's requests (as much as is practical for OpenGLUT to ensure). Additionally, menu windows will have no title, borders, or other decoration or other controls. These two major concepts are linked: Without any user control over the window, the application must have sufficient control to present the windows.

Some features that may make menu windows easier to work with in practice, and hence are tentatively suggested, are:

The Experimental Implementation.

OpenGLUT provides an experimental implementation of the ``menu window'' concept. This is via glutCreateMenuWindow(). (Formerly, GLUT_UNMANAGED was provided as a flag to the glutInitDisplayMode() function, but that concept has split into the present menu windows and the GLUT_BORDERLESS flag---see OpenGLUT Borderless Window Proposal.)

The experimental implementation does not enforce the associated hiding/destruction of menu-windows when the parent goes away.

The current support is through one new function:

glutCreateMenuWindow(int parent, int x, int y, int w, int h)

The similarity to glutCreateSubWindow() should be apparent.

A menu window exists as a top-level window at this time. The coordinates are relative to the position of the parent window. It is contemplated to make one of two changes:

  1. Put the window in the sapce space as the parent. (So it would be a subwindow if the parent is a subwindow.)

  1. Use absolute screen coordinates rather than parent-relative coordinates.

Unlike a subwindow, a menu window exists in the same space as the parent. (Alternatively, it could be pushed to the top-level space; that has some appeal, but could make coordinate translation a bit more tedious.)

The parent is the parent window to which keyboard input will cascade.

The x and y coordinates are relative to the parent, though they need not lie within the parent.

The w and h width and height values can be arbitrary positive values, up to whatever limits may be imposed by the window system.

If the parent is a top-level window (or if menu windows are always top-level), then the created menu window should respect the current display mode settings. (Alternative: Borrow from the parent?)

The Generalization.

The feature seems to be of broader utility at first glance. We are actively looking at ways to make a broader use work, but a separate feature, with accompanying proposal, may be the way to go.

The generalization is to ``borderless'' windows. This seems to work well at first with the menu concept, but there are wrinkles in attempts to implement these as a single concept. Utility for the generalized borderless windows would include:

Some of these, e.g., menus, seem to be satisfactorily functional with the experimental implementation.

The Future of This API.

The menu window concept may be enshrined. Or it may be submerged into a more flexible underlying menu infrastructure. Or it may be merged with the borderless window concept. Which of these fates, or if some other emerges, will be determined by experience---our own, and that of any courageous spirits who toy with this feature while it is experimental.


Feedback, comments or suggestions can be directed either to the mail list or discussion forum.

OpenGLUT Development @ Sourceforge
Homepage | Summary | Files | CVS | Forums | Lists | Bugs | RFE

Generated on Sat Feb 5 01:47:28 2005 for OpenGLUT by doxygen
The OpenGLUT project is hosted by