## 3 Menus ¶

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.