menu-choose [Generic Function]
Arguments: items &key associated-window printer presentation-type default-item text-style label cache unique-id id-test cache-value cache-test max-width max-height n-rows n-columns x-spacing y-spacing row-wise cell-align-x cell-align-y pointer-documentation scroll-bars
Summary: Displays a menu whose choices are given by the elements of the sequence items . It returns three values: the value of the chosen item, the item itself, and the pointer button event corresponding to the gesture that the user used to select it. If the user aborts out of the menu, a single value is returned, nil .
menu-choose calls frame-manager-menu-choose on the frame manager being used by associated-window (or the frame manager of the current application frame). All the arguments to menu-choose will be passed on to frame-manager-menu-choose .
items is a sequence of menu items. Each menu item has a visual representation derived from a display object, an internal representation that is a value object, and a set of menu item options. The form of a menu item is one of the following:
An atom--the item is both the display object and the value object.
A cons--the car is the display object and the cdr is the value object. The value object must be an atom. If you need to return a list as the value, use the :value option in the list menu item format.
A list--the car is the display object and the cdr is a list of alternating option keywords and values. The value object is specified with the keyword :value and defaults to the display object if :value is not present.
:value --This specifies the value object.
:text-style --This specifies the text style used to princ the display object when neither presentation-type nor printer is supplied.
:items --This specifies a sequence of menu items for a submenu used if this item is selected.
:documentation --This associates some documentation with the menu item. When pointer-documentation is not nil , this will be used as pointer documentation for the item.
:active --When t (the default), this item is active. When nil , the item is inactive, and cannot be selected. CLIM will generally provide some visual indication that an item is inactive, such as by "graying over" the item.
:type --This specifies the type of the item. :item (the default) indicates that the item is a normal menu item. :label indicates that the item is simply an inactive label; labels will not be "grayed over." :divider indicates that the item serves as a separator between groups of other items; separator items will usually be drawn as a horizontal line.
The visual representation of an item depends on the printer and presentation-type keyword arguments. If presentation-type is supplied, the visual representation is produced by present of the menu item with that presentation type. Otherwise, if printer is supplied, the visual representation is produced by the printer function, which receives two arguments, the item and a stream to do output on. The printer function should output some text or graphics at the stream's cursor position, but need not call present . If neither presentation-type nor printer is supplied, the visual representation is produced by princ of the display object. Note that if presentation-type or printer is supplied, the visual representation is produced from the entire menu item, not just from the display object.
associated-window is the CLIM window with which the menu is associated. This defaults to the top-level window of the current application frame.
default-item is the menu item that is indicated as the default either by some form of highlighting or by warping the mouse to appear over it.
default-style is a text style that defines how the menu items are presented.
label is a string to which the menu title will be set.
printer is a function of two arguments used to print the menu items in the menu. The two arguments are the menu item and the stream to output it on. It has dynamic extent.
presentation-type specifies the presentation type of the menu items.
cache is a boolean that indicates whether CLIM should cache this menu for later use. (Caching menus might speed up later uses of the same menu.) If cache is t , then unique-id and id-test serve to identify this menu uniquely. When cache is t , unique-id defaults to items , but programmers will generally wish to specify a more efficient tag. id-test is a function of two arguments used to compare unique-ids, which defaults to equal . cache-value is the value that is used to indicate that a cached menu is still valid. It defaults to items , but programmers may wish to supply a more efficient cache value than that. cache-test is a function of two arguments that is used to compare cache values, which defaults to equal . Both cache-value and unique-id have dynamic extent.
max-width and max-height specify the maximum width and height of the menu, in device units. They can be overridden by n-rows and n-columns .
n-rows and n-columns specify the number of rows and columns in the menu.
x-spacing specifies the amount of space to be inserted between columns of the table; the default is the width of a space character. It is specified the same way as the :x-spacing option to formatting-table .
y-spacing specifies the amount of blank space inserted between rows of the table; the default is the vertical spacing for the stream. The possible values for this option are the same as for the :y-spacing option to formatting-table .
If row-wise is t (the default) and the item list requires multiple columns, each successive element in the item list is laid out from left to right. If row-wise is nil and the item list requires multiple columns, each successive element in the item list is laid out below its predecessor, as in a telephone book.
cell-align-x specifies the horizontal placement of the cell's contents. Like the :align-x option to formatting-cell , it is one of :left (the default), :right , or :center . 17.1.2, CLIM Operators for Formatting Tables
cell-align-y specifies the vertical placement of the contents of the cell. It can be one of :top , :bottom , or :center . The default is :top . The semantics are the same as for the :align-y option to formatting-cell .
pointer-documentation is either nil (the default), meaning that no pointer documentation should be computed, or a stream on which pointer documentation should be displayed.
frame-manager-menu-choose [Generic Function]
Arguments: frame-manager items &key associated-window printer presentation-type default-item text-style label cache unique-id id-test cache-value cache-test max-width max-height n-rows n-columns x-spacing y-spacing row-wise cell-align-x cell-align-y pointer-documentation scroll-bars toolkit-p
Summary: Displays a menu whose choices are given by the elements of the sequence items . It returns three values: the value of the chosen item, the item itself, and the pointer button event corresponding to the gesture that the user used to select it. If the user aborts out of the menu, a single value is returned, nil .
For the values of the arguments, see menu-choose .
menu-choose-from-drawer [Generic Function]
Arguments: menu type drawer &key x-position y-position cache unique-id id-test cache-value cache-test default-presentation pointer-documentation leave-menu-visible
Summary: This is a lower-level routine for displaying menus. It allows the programmer much more flexibility in the menu layout. Unlike menu-choose , which automatically creates and lays out the menu, menu-choose-from-drawer takes a programmer-provided window and drawing function. The drawing function is responsible for drawing the contents of the menu; generally it will be a lexical closure over the menu items.
menu-choose-from-drawer draws the menu items into that window using the drawing function. The drawing function gets called with two arguments, stream and type . It can use type for its own purposes, for example, as the type argument in a call to present .
menu-choose-from-drawer returns two values: the object the user clicked on, and the pointer button event. If the user aborts out of the menu, nil is returned.
menu is a CLIM window to use for the menu. This argument may be specialized to provide a different look-and-feel for different host window systems.
type is a presentation type specifier for each of the mouse-sensitive items in the menu. This is the input context that will be established once the menu is displayed. For programmers who don't need to define their own types, a useful presentation type is menu-item .
drawer is a function that takes two arguments, stream and type , and draws the contents of the menu. It has dynamic extent.
x-position and y-position are the requested x and y positions of the menu. They may be nil , meaning that the position is unspecified.
If leave-menu-visible is t , the window will not disappear once the selection has been made. The default is nil , meaning that the window will disappear once the selection has been made.
default-presentation is used to identify the presentation that the mouse is pointing to when the menu comes up.
cache , unique-id , id-test , cache-value , and cache-test are as for menu-choose .
draw-standard-menu [Function]
Arguments: stream presentation-type items default-item &key item-printer max-width max-height n-rows n-columns inter-column-spacing inter-row-spacing cell-align-x cell-align-y
Summary: draw-standard-menu is the function used by CLIM to draw the contents of a menu, unless the current frame manager determines that host window toolkit should be used to draw the menu instead. stream is the stream onto which to draw the menu, presentation-type is the presentation type to use for the menu items (usually menu-item ), and item-printer is a function used to draw each item. item-printer defaults to print-menu-item .
items , default-item , max-width , max-height , n-rows , n-columns , inter-column-spacing , inter-row-spacing , cell-align-x , and cell-align-y are as for menu-choose
print-menu-item [Function]
Arguments: menu-item &optional stream
Summary: Given a menu item menu-item , displays it on the stream stream . This is the function that menu-choose uses to display menu items if no printer is supplied.
menu-item-value [Function]
Summary: Returns the value of menu-item , where the format of a menu item is described under menu-choose .
menu-item-display [Function]
Summary: Returns the display object of the menu item menu-item , where the format of a menu item is described under menu-choose .
menu-item-options [Function]
Summary: Returns the options of the menu item menu-item , where the format of a menu item is described under menu-choose .
with-menu [Macro]
Arguments: (menu &optional associated-window &key (deexpose t )) &body body
Summary: Binds menu to a "temporary" window, exposes the window on the same screen as the associated-window and runs the body. After the body has been run, the window disappears only if the boolean deexpose is t (the default).
The values returned by with-menu are the values returned by body . body may have zero or more declarations as its first forms.
menu must be a variable name. associated-window is as for menu-choose .
None of the arguments is evaluated.