### 3.1 Picmenus ¶

A `picmenu` (picture menu) is analogous to a menu, but involves a user-defined picture containing sensitive spots or “buttons”. The test function `(wteste)` shows an example of a `picmenu`. A `picmenu` is created by:
`(picmenu-create buttons width height drawfn`
`&optional title dotflg w:window x y perm flat font boxflg)`

If a picmenu is to be used more than once, the common parts can be made into a `picmenu-spec` and reused:

`(picmenu-create-spec buttons width height drawfn`
`&optional dotflg font)`
`(picmenu-create-from-spec spec:picmenu-spec`
`&optional title w:window x y perm flat boxflg)`
`width` and `height` are the size of the area occupied by the picture. `(drawfn w x y)` should draw the picture at the offset `x y`. Note that the `draw` utility can be used to make the drawing function, including `picmenu` buttons. `dotflg` is non-`nil` if it is desired that small boxes be automatically added to the sensitive points when the picture is drawn. `boxflg` is non-`nil` if a box is to be drawn around the picmenu when the picture is drawn (this is only needed for flat picmenus). If `perm` is non-nil, the drawing program is not called when a selection is to be made, so that an external program must draw the `picmenu`; this avoids the need to redraw a complex picture. The remaining arguments are as described for menus.

Each of the `buttons` in a picmenu is a list:
`(buttonname offset size highlightfn unhighlightfn)`
`buttonname` is the name of the button; it is the value returned when that button is selected. `offset` is a vector `(x y)` that gives the offset of the center of the button from the lower-left corner of the picture. The remainder of the button list may be omitted. `size` is an optional list `(width height)` that gives the size of the sensitive area of the button; the default size is `(12 12)`. `(highlightfn w x y)` and `(unhighlightfn w x y)` (where `(x y)` is the center of the button in the coordinates of `w`) are optional functions to highlight the button area when the cursor is moved into it and unhighlight the button when the cursor is moved out; the default is to display a box of the specified `size`.

`(picmenu-select m &optional inside)`
If the `picmenu` is not `flat`, its window should be destroyed following the selection using `menu-destroy`.

`(picmenu-item-position m name &optional location)`
`(picmenu-delete-named-button m name:symbol)`
This deletes a button from a displayed `picmenu`. The set of deleted buttons is reset to `nil` when the picmenu is drawn.