25 Menu Facilities

menu-choose will call frame-manager-menu-choose on the frame manager being used by associated-window (or the frame manager of the current application frame). All of the arguments to menu-choose will be passed on to frame-manager-menu-choose .

frame-manager-menu-choose

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 scroll-bars pointer-documentation

[Generic function]

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 .

Implementation note: the default method on standard-frame-manager will generally be implemented in terms of CLIM's own window stream and formatting facilities, such as using menu-choose-from-drawer on a stream allocated by with-menu . However, some frame managers may be able to use a native menu facility to handle most (if not all) menus. If the native menu facility cannot handle some cases, it can simply use call-next-method to invoke the default method.

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 described below.

• 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 ---specifies the value object.

• :style ---specifies the text style used to princ the display object when neither presentation-type nor printer is supplied.

• :items ---specifies a sequence of menu items for a sub-menu to be used if this item is selected.
• :documentation ---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 true (the default), this item is active. When false , 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 ---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 divider between groups of other items; divider items will usually be drawn as a horizontal line.

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 where the mouse will appear.

text-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 true , then unique-id and id-test serve to uniquely identify this menu. When cache is true , 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 .

cell-align-x specifies the horizontal placement of the contents of the cell. Can be one of :left , :right , or :center . The default is :left . The semantics are the same as for the :align-x option to formatting-cell .

cell-align-y specifies the vertical placement of the contents of the cell. 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 .

row-wise is as for formatting-item-list . It defaults to t .

scroll-bars specifies whether the menu should have scroll bars. It acts the same way as the :scroll-bars option to make-clim-stream-pane . It defaults to :vertical .

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.

menu-choose-from-drawer

menu presentation-type drawer &key x-position y-position cache unique-id id-test cache-value cache-test default-presentation pointer-documentation

[Generic function]

This is a 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 that closes 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 presentation-type . It can use presentation-type for its own purposes, such as using it as the presentation 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, a single value is returned, nil .

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.

presentation-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 presentation-type , 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 true , the window will not be deexposed once the selection has been made. The default is false , meaning that the window will be deexposed 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

stream presentation-type items default-item &key item-printer max-width max-height n-rows n-columns x-spacing y-spacing row-wise cell-align-x cell-align-y

[Function]

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 , x-spacing , y-spacing , row-wise , cell-align-x , and cell-align-y are as for menu-choose

print-menu-item

menu-item &optional (stream *standard-output* )

[Function]

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

menu-item

[Function]

Returns the value of the menu item menu-item , where the format of a menu item is described under menu-choose . If menu-item is not a menu item, the result is unspecified.

menu-item-display

menu-item

[Function]

Returns the display object of the menu item menu-item , where the format of a menu item is described under menu-choose . If menu-item is not a menu item, the result is unspecified.

menu-item-options

menu-item

[Function]

Returns the options of the menu item menu-item , where the format of a menu item is described under menu-choose . If menu-item is not a menu item, the result is unspecified.

with-menu

(menu &optional associated-window &key (deexpose t)) &body body

[Macro]

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 is deexposed only if the boolean deexpose is true (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.