open-menu

Function

Package: common-graphics

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

Creates and returns a menu. Two values are returned. The first is always the new menu. The second depends on stream. The arguments are interpreted as follows:

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

The value of the :name option in the forms above which make menu-item instances (that is, the car of a cons or the value of an atom) must be able to be converted to a string with the function "string" (e.g. a string or a 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 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 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*) (regardless of the value of device) 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 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.

If the class and stream arguments do not match as described above, then nil 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.

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.

title 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.

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

selection-function is the function that is called whenever a menu-item is selected. It is passed three arguments: the menu, the menu-item chosen and the owning stream (e.g. (screen*system*) for pop-up menus, or some other menu bar for pull-down menus). The default selection-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 selection-function 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 selection-function is quite important for otherwise choosing a menu-item from a menu will not do anything.

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. A 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.

See also doc/cg.menu/menu.htm which has examples using this function. See also the Menu Editor.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.