open-menu

Arguments: items class stream &rest options &key add-to-menu pop-up help-string

Creates and returns a menu, or returns nil if the request to the Operating System to create a new menu fails (see the information under the heading open-menu returns nil if a menu cannot be created near the bottom of this page) or if the class and stream arguments are inconsistent. If a menu is created, open-menu returns two values. The first is always the new menu. The second depends on stream. The arguments are interpreted as follows:

The items argument

items is a list of elements which can be a mixture of types menu-item, cons or atom. Each element is coerced in the following way:

• element is a menu-item: it is used.
• element is a cons: a menu-item is created with a form like (make-instance 'menu-item :name (car element) :value (cdr element)).
• element is an atom: a menu-item is created with a form like (make-instance 'menu-item :name element).

For each menu-item specifier in the items list that is not an actual menu-item, the string to appear on the menu for the item is created automatically by capitalizing the print name of the menu-item name and replacing any dashes with spaces. If this built-in formating is not suitable, then always pass actual menu-items whose title properties are the appropriate strings.

To insert a horizontal line between groups of menu-items, include a menu-item whose title is a string containing only a single dash character ("-"). Other attributes of the menu-item will be ignored for this special case. Alternately, include the value of the variable menu-separator in the list of menu-items instead of an actual menu-item (but see the GTK note on the page for that symbol).

Note that a specific menu-item can only be placed on one menu at a time. If you want identical menu-items on two menus, create two separate but identical menu items. You can copy a menu-item with copy-menu-item.

The class argument

The class argument is the name of the menu class to instantiate. It should be either pop-up-menu, pull-down-menu, or menu-bar, or a subclass of one of those classes. (An application may define its own menu subclasses in order to add methods to standard menu generic functions.) Note that pull-down-menu is already a subclass of pop-up-menu.

The stream argument

The stream argument is the parent on which to create the menu, and must match the specified class. If class is pop-up-menu or one of its subclasses (but not pull-down-menu or one of its subclasses), and stream is an existing pop-up-menu (or pull-down-menu), then the new menu will be created as a submenu of the pop-up-menu. If class is a pull-down-menu or one of its subclasses, and stream is an existing menu-bar, then the new menu will be created as a pull-down menu of the menu-bar. If class is a menu-bar, and stream is a top-level window that has a title-bar, then the new menu will be created as the menu-bar of that window.

In addition to the above combinations, stream may be (screen *system*) (see screen and *system*), regardless of the value of class, in order to create a menu without yet putting it on a specific parent or displaying it. A pop-up-menu created on the screen may be invoked later as a top-level pop-up-menu by calling the function pop-up-menu. A pop-up-menu or pull-down-menu created on the screen may be added later to a pop-up-menu or menu-bar parent (respectively) by calling add-to-menu. A menu-bar created on the screen may be added later to a window by calling (setf menu).

The pop-up argument

The pop-up argument specifies whether a pop-up-menu rather than a menu-bar is being created. The default value is t, so if class is menu-bar or one of its subclasses, then pop-up should be passed explicitly as nil.

stream and class mismatch

If the class and stream arguments do not match as described above, then nil is returned. (To recap, stream can always be (screen *system*) regardless of the value of class. If stream is not (screen *system*), then if class is pop-up-menu or one of its subclasses (but not pull-down-menu or one of its subclasses), stream must be an existing pop-up-menu or pull-down-menu. If class is a pull-down-menu or one of its subclasses, and stream must be existing menu-bar. If class is a menu-bar, stream must be a top-level window that has a title-bar.)

When a new menu is created: what is returned

Otherwise two values are returned: (1) the menu that was created, and (2) the menu-item that was created in order to add the new menu to a parent menu, if one in fact was created, and nil otherwise. A menu-item is created only if class is pop-up-menu or one of its subclasses, stream is a menu, and the add-to-menu argument is true.

The help-string argument

help-string is used only if the stream argument is a menu. In that case, the new menu being created by this call to open-menu becomes a child menu of the parent menu specified by the stream argument, and a new menu-item is automatically created and added to the parent menu for invoking the new child menu. help-string will become the help-string of this new menu-item on the parent menu. A menu-item-highlighted method for the parent menu may make use of this help-string, such as by calling window-message or status-bar-message to display the help-string in a status-bar whenever the end user highlights the menu-item. This works even when the parent menu is a menu-bar (in which case the new menu-item is displayed on the menu-bar itself to invoke a pull-down menu).

The options argument

options are pairs of keys and values, treated the same as for make-window. Any make-window initargs that may work for menus but are not explicit keyword arguments to open-menu may thus still be specified. Options include:

• title: this argument is used only if the stream argument is a menu. In that case, the new menu being created by this call to open-menu becomes a child menu of the parent menu specified by the stream argument, and a new menu-item is automatically created and added to the parent menu for invoking the new child menu. title will be used as the label of this new menu-item on the parent menu. If the parent menu is a menu-bar, then the title will be displayed on the menu-bar itself. Note that the Windows operating system does not support titles on non-child pop-up menus.
• on-click: the value of this argument should be a function name or function object naming the function that is called whenever a menu-item is selected. Such a function is passed three arguments: the menu, the menu-item chosen and the owning stream (e.g. (screen *system*) -- see screen and *system* -- for pop-up menus, or some other menu bar for pull-down menus). The default on-click function simply returns the unevaluated value of the selected menu-item, but eval-menu-item, funcall-menu-item, and funcall-menu-item-with-window may be useful.

  Pop-up menus are displayed by calling pop-up-menu. The value returned by the on-click is also returned by pop-up-menu so your code can use that value to decide what action to take. Pull-down menus, however, are displayed by an internal function whose return value is not available to user code. So, for pull-down menus, the on-click is quite important: if it does not do anything, choosing a menu-item from a menu will not do anything. The default function, which, as said above, simply returns the unevaluated value of the selected menu-item, does not do anything useful for pull-down menus since the returned value is discarded by the (internal) function that displayed the menu. Again, the functions eval-menu-item, funcall-menu-item, and funcall-menu-item-with-window are useful for pull-down menus.

The add-to-menu argument

add-to-menu controls the effect of creating a menu when the stream argument to open-menu is an existing menu. In that case, the argument should be one of the following values (the same values that the position argument to add-to-menu can have):

• :start: add new menu at the start of stream menu
• :end: add new menu at the end of stream menu
• non-negative integer: the menu-item that is created for the new menu is inserted into the parent menu (the value of the stream argument) at that index position, as in add-to-menu. (Position zero is the start of the menu. An integer position greater than the length of the menu is interpreted as the end of the menu.)

The new menu is incorporated into a menu-item whose name is the title of the new menu and whose value is the new menu. In this case, the second value returned from open-menu is the new menu-item added to stream menu.

While it is typical not to specify a value when stream is not a menu, you can specify nil in that case.

open-menu returns nil if a menu cannot be created

open-menu returns nil if the operating system failed to make the requested menu. Such failure is typically due to one of the operating system's tables for all windows and menus becoming full. This situation should be rare, but if it does happen then your application should be modified to close any windows or menus that are no longer being used, in order to free up the corresponding operating system resources. Note that removing a menu-bar from a window (by passing nil to (setf menu)) does not close the menu, and closing a menu does not close its sub-menus, since each of these can still be used elsewhere. If your application creates lots of menus over time, it is prudent to call close on each menu and sub-menu that will no longer be used.

Other documentation

See also the menu chapter in the IDE User Guide, which has examples using this function. See also the Menu Editor.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.