| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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:
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:
menu-item
: it is used.
(make-instance 'menu-item :name (car element) :value (cdr
element))
.
(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 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*)
(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 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. (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.)
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.
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).
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:
(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.
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
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 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.
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.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |