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.

Superclasses

element
titled-menu-object

Initargs

:items

The items to appear in the menu.

:items-function

A function to dynamically compute the items.

Accessors

menu-items

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 alternate way to specify a mnemonic in the menu title is to use the :mnemonic-title initarg (rather than :title ). The value should be a string with the mnemonic character preceded by the mnemonic escape. The mnemonic escape defaults to #\& (it can be changed via the :mnemonic-escape initarg). To include the mnemonic escape as a normal character in the menu title, precede it with the mnemonic escape.

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.

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
menu-component
menu-item
menu-object
contain