`:items`	The items to appear in the menu.
`:items-function`	A function to dynamically compute the items.
`:mnemonic`	A character, integer or symbol specifying a mnemonic for the menu.
`:mnemonic-escape`	A character specifying the mnemonic escape. The default value is `#\&`.
`:mnemonic-title`	A string specifying the title and a mnemonic.
`:image-function`	A function providing images for the menu items, or `nil`.

Accessors

menu-items
menu-image-function

Description

A menu has a title, and has items appearing in it, where an item can be either a menu-item, a menu-component or another menu.

The simplest way of providing items to a menu is to pass them as the argument items, but if you need to compute the items dynamically you should provide the setup callback items-function. This function should return a list of menu items for the new menu. By default items-function is called on the menu's interface, but a different argument can be specified using the menu-object initarg setup-callback-argument.

If an item is not of type menu-object, then it gets converted to a menu-object with the item as its data. This function is called before the popup-callback and the enabled-function which means that they can affect the new items.

To specify a mnemonic in the menu title, you can use the initarg :mnemonic. The value mnemonic can be:

An integer	The index of the mnemonic in the title.
A character	The mnemonic in the title.
`nil`	A character is chosen from a list of common mnemonics, or the `:default` behavior is followed. This is the default.
`:default`	A mnemonic is chosen using some rules.
`:none`	The title has no mnemonic.

An alternative way to specify a mnemonic is to pass mnemonic-title (rather than title) This is a string which provides the text for the menu title and also specifies the mnemonic character. The mnemonic character is preceded in mnemonic-title by mnemonic-escape, and mnemonic-escape is removed from mnemonic-title before the text is displayed. For example:

:mnemonic-title "&Open File..."

At most one character can be specified as the mnemonic in mnemonic-title. To make mnemonic-escape itself appear in the button, precede it in mnemonic-title with mnemonic-escape. For example:

:mnemonic-title "&Compile && Load File..."

If image-function is non-nil, it should be a function of one argument. image-function is called with the data of each menu item and should return one of:

`nil`	No image is shown.
An image	The menu displays this image.
An image id or external-image
	The system converts the value to a temporary image for the menu item and frees it when it is no longer needed.

If image-function is nil, no items in the menu have images. This is the default value.

Notes

items-function is called before the menu is raised (in order to initialize accelerators) and in particular it may be called before the interface is created. Therefore items-function, if you supply it, should work at this early stage.
On Microsoft Windows, Cocoa and GTK+, menu items can contain both images and strings, so the print-function should return the appropriate string or "" if no string is required. On Motif, if there is an image then the string is ignored. You can test programmatically whether menus with images are supported with pane-supports-menus-with-images.
On Microsoft Windows and GTK+, menu items that can have check marks (those inside menu-component with interaction :multiple-selection or :single-selection) cannot have images (the image is ignored for such items).
When debugging a menu, it may be useful to pop up a window containing a menu with the minimum of fuss. The function contain will do just that for you.
To display a menu as a context (right button) menu, use display-popup-menu, and to display a menu via a labelled button use popup-menu-button.
You must not use a menu object in multiple different places in menu bar(s) at the same time. Supply distinct instances instead. The one exception is popup menus, which can be used repeatedly and in different places.
Microsoft Windows can hide mnemonics when the user is not using the keyboard. See 3.1.4.2 Mnemonics on Microsoft Windows.

Examples

(capi:contain (make-instance 'capi:menu
                             :title "Test"
                             :items '(:red :green :blue)))

(capi:contain (make-instance 
               'capi:menu
               :title "Test"
               :items '(:red :green :blue)
               :print-function 'string-capitalize))

(capi:contain (make-instance
               'capi:menu
               :title "Test"
               :items '(:red :green :blue)
               :print-function 'string-capitalize
               :callback #'(lambda (data interface)
                             (capi:display-message 
                              "Pressed ~S" data))))

Here is an example showing how to add submenus to a menu:

(setq submenu (make-instance 'capi:menu
                             :title "Submenu..."
                             :items '(1 2 3)))

(capi:contain (make-instance
               'capi:menu
               :title "Test"
               :items (list submenu)))

Here is an example showing how to use the items-function:

(capi:contain (make-instance
               'capi:menu
               :title "Test"
               :items-function #'(lambda (interface)
                                   (loop for i below 8
                                    collect (random 10)
                                   ))))

Finally, some examples showing how to specify a mnemonic in a menu title:

(capi:contain (make-instance 
               'capi:menu
               :title "Mnemonic Title"
               :mnemonic 1 
               :items '(1 2 3)))

(capi:contain (make-instance 
               'capi:menu
               :mnemonic-title "M&nemonic Title"
               :items '(1 2 3)))

(capi:contain (make-instance 
               'capi:menu
               :mnemonic-title "M&e && You"
               :items '("Me" "You")))

This example shows how to make a menu with images:

(example-edit-file "capi/elements/menu-with-images")

There are further examples here:

(example-edit-file "capi/applications/")

menu Class

Summary

Package

Superclasses

Initargs

Accessors

Description

Notes

Examples

See also