The function menu
provides an easy interface to make a pop-up
menu, get a selection from it, and destroy it:
(menu items &optional title)
Example: (menu '(red white blue))
This simple call is all that is needed in most cases. More sophisticated menu features are described below.
The items
in a menu is a list; each item may be a symbol, a
cons
of a symbol or string and the corresponding value, or a
cons
of a function name and the corresponding value. In the
latter case, the function is expected to draw the corresponding menu
item.
If a function name is specified as the first element of a menu item, the
drawing function should have arguments (fn w x y)
, where w
is the window and x
and y
are the lower-left corner of the
drawing area. The property list of the function name should have the
property display-size
, which should be a list
(width height)
in pixels of the displayed symbol.
Menus can be associated with a particular window; if no window is specified, the menu is associated with the window where the mouse cursor is located when the menu is initialized (which might not be a Lisp user’s window). If a menu is associated with a user window, it may be permanent (left displayed after a selection is made) and may be flat (drawn directly on the containing window, rather than having its own window).
A menu can be created by menu-create
:
(menu-create items &optional title w:window x y perm flat font)
title
, if specified, is displayed over the menu. w
is an
existing window
; if specified, the menu is put within this window
at the x y
offsets specified (adjusted if necessary to keep the
menu inside the window). If no w
is specified, or if x
is
nil
, the menu is put where the cursor is the first time the menu
is displayed. perm
is non-nil
if the menu is to be
permanent, i.e., is to be left displayed after a selection has
been made. flat
is non-nil
if the menu is to be drawn
directly on the containing window. font
is a symbol or string
that names the font to be used; the default is a 9x15
typewriter
font.
The menu is returned as the value of menu-create
. Such a menu can
be saved; selections can be made from a menu m
as follows:
(menu-select m &optional inside)
or
(menu-select! m)
menu-select
will return nil
if the mouse is clicked
outside the menu, or is moved outside after it has been inside (or if
inside
is not nil
), provided that the menu is contained
within a user-created window. menu-select!
requires that a choice
be made.
In order to avoid wasting storage, unused menus should be destroyed:
(menu-destroy m)
. The simple menu
function destroys its
menu after it is used.
(menu-size m)
(menu-moveto-xy m x y)
(menu-reposition m)
menu-reposition
will reposition a flat
menu within its
parent window by allowing the user to position a ghost box using the
mouse. menu-size
returns the size of the menu as a vector,
(x y)
. menu-moveto-xy
adjusts the offsets to move a
flat
menu to the specified position within its parent window.
These functions and menu-destroy
work for picmenus and barmenus
as well.
(menu-item-position m name &optional location)
menu-item-position
returns a vector (x y)
that gives the
coordinates of the menu item whose name is name
. location
may be center
, left
, right
, top
, or
bottom
; the default is the lower-left corner of the menu item.
center
specifies the center of the box containing the menu item;
the other location
values are at the center of the specified edge
of the box.