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 .

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.

Note: On Cocoa, 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.

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

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

Note: by default Microsoft Windows hides mnemonics when the user is not using the keyboard. In Windows XP a system preference controls this:

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

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

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

See also

display-popup-menu
ole-control-add-verbs
menu-component
menu-item
menu-object
popup-menu-button
contain