Class

Summary

The class menu creates a menu for an interface when specified as part of the menu bar (or as a submenu of a menu on the menu bar). It can also be displayed as a context menu.

Package

capi

Superclasses

element
titled-menu-object

Initargs

: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 .

Note: 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.

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 object

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

1. On 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 Microsoft Windows and 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.
2. 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.
3. 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.
4. By default Microsoft Windows hides mnemonics when the user is not using the keyboard. In Windows XP (and later) a system preference controls this:

Display > Appearance > Effects > Hide underlined letters...

Example

(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")))

There is an example showing how to make a menu with images in examples/capi/elements/menu-with-images.lisp .

There are further examples in the directory examples/capi/applications/ .

See also

display-popup-menu
menu-component
menu-item
menu-object
ole-control-add-verbs
pane-supports-menus-with-images
popup-menu-button