Major issue: There is a general issue about how these menus fit in with the menus that might be provided by the underlying toolkit. For example, under what circumstances is CLIM allowed to directly use the menu facilities provided by the host? Should :leave-menu-visible t interact with the "pushpin" facility provided by OpenLook? --- SWM [annotate]
| menu-choose | 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] |
| 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. [annotate] 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. [annotate] 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: [annotate]
The menu item options are: [annotate]
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. CLIM implementations are free to use the menus provided by the underlying window system when possible; this is likely to be the case when the printer and presentation-type are the default, and no other options are supplied. [annotate] Note: Later print-menu-item is mentioned as the function that is used as a fallback (not princ), and it is called with the whole item (not only display object) [edit]-- DK 2022-05-31 11:36Z associated-window is the CLIM window with which the menu is associated. This defaults to the top-level window of the current application frame. [annotate] default-item is the menu item where the mouse will appear. [annotate] text-style is a text style that defines how the menu items are presented. [annotate] label is a string to which the menu title will be set. [annotate] 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. [annotate] presentation-type specifies the presentation type of the menu items. [annotate] 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. [annotate] 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. [annotate] n-rows and n-columns specify the number of rows and columns in the menu. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] row-wise is as for formatting-item-list. It defaults to t. [annotate] 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. [annotate] 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. [annotate] |
| 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. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] drawer is a function that takes two arguments, stream and presentation-type, draws the contents of the menu. It has dynamic extent. [annotate] 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. [annotate] 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. [annotate] default-presentation is used to identify the presentation that the mouse is pointing to when the menu comes up. [annotate] cache, unique-id, id-test, cache-value, and cache-test are as for menu-choose. [annotate] |
| 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. [annotate] 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 [annotate] |
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. [annotate] |
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. [annotate] |
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. [annotate] |
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. [annotate] |
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). [annotate] The values returned by with-menu are the values returned by body. body may have zero or more declarations as its first forms. [annotate] menu must be a variable name. associated-window is as for menu-choose. [annotate] None of the arguments is evaluated. [annotate] |