menu

Arguments: frame-window

Returns the menu-bar of frame-window. The menu-bar is displayed along the top of the frame-window.

The setf of this function may be called to add a menu-bar to a window. The new value may be a menu-bar that was created by calling open-menu, or nil to remove the window's current menu-bar if there is one. A menu-bar should not exist on more than one window at the same time, though it may be removed from one window and then added to another.

A menu-bar is structured the same way as a pop-up menu, except that each of its menu-items denotes one of the pull-down menus of the menubar, with the title of the menu-item being a pull-down menu title that is displayed along the menu-bar, and the value of the menu-item being a menu containing the pull-down menu's items.

If you use the IDE, you can add a menubar to a form (and thus to the window associated to the form in the application) by clicking on the extended editor button of the menu property of the form. Doing so displays the menu editor.

Common Graphics does not automatically close a menu-bar when it is removed from a window, because in general menus may be reused on the same or other windows or parent menus, and so Common Graphics does not know whether you are done with a menu-bar when you remove it. Any menus that are not closed explicitly by an application are closed automatically when Lisp exits, and so there is ordinarily no need for an application to close its menus. But if so many menus are being created that the operating system runs out of related resources (leading to errors), the application may call close on each menu that will no longer be used. A menu-bar should be removed from its window before calling close on it. Closing a menu does not close its submenus, and so these must be closed individually (either before or after closing the parent menu) to close an entire menu hierarchy.

Limitations of child window menu bars on all platforms:

Menu-bar access keys and keyboard shortcuts will never be routed to a child window, and will go to the menu-bar of the top-level parent (or its owner window) instead, if it has a menu-bar.

Limitations of child window menu bars on MS Windows only

• The menu-bar is actually a child pane that emulates a "real" menu-bar, because MS Windows does not allow menu bars on child windows. This primarily means that other windows must be offset downward by (menu-bar-height) to avoid covering (or being covered by) the menu bar pane.
• Exposing one pull-down menu and then moving the mouse over the title of another pull-down menu does not remove the first menu and expose the second one. This is probably not feasible to improve because Common Graphics is waiting on a foreign function call that pops up the menu and tracks it within the operating system. Instead you must click on the second menu's title to show that menu.

Ubuntu note:

If you run on the Ubuntu version of Linux, then you will probably need to avoid using (setf menu) to swap alternate menu bars onto a window. When putting a menu bar onto a window that had already been on the window and then removed, we have noticed strange effects such as all of the commands on the pull-down menus being replaced with a single "Activate" command that CG doesn't know about. This is likely related to GTK modifications that Ubuntu appears to have made to shift menu bars onto title bars, though the problem persists if you select the Ubuntu option to show menus "in the window's toolbar" (actually in its title bar) rather than the default option to show them "in the menu bar" (actually in the main window's title bar). In any case, an alternate approach for exchanging the pull-down menus on a window that works well on all platforms is to keep the same menu bar menu object on the window and to replace its set of menu-items, to replace the set of pull-down menus that are on the single menu bar.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 9.0 page.
Created 2019.8.20.