A menu item is an individual item in a menu or menu component, and instances of
menu-item
are created automatically by define-interface.
A character, string or plist, or the keyword
:default
.
An object used for lookup of help. Default value
t
.
A character, integer or symbol specifying a mnemonic for the menu item.
A character specifying the mnemonic escape. The default value is
#\&
.
The text displayed in the menu item is the contents of the text slot, or the contents of the title slot, otherwise it is the result of applying the print-function to the data .
selected-function
defaults to
nil
, but if non-
nil
it is a function which is called before the
menu-item
is displayed and which determines whether or not the
menu-item
is selected. By default
selected-function
is called on the interface of the
menu-item
, but this argument can be changed by passing the menu-object initarg
setup-callback-argument
.
Callbacks are made in response to a user gesture on a
menu-item
. The
callback-type
(see callbacks),
callback
and
callback-data-function
(see menu-object) are found by looking for a non-
nil
value, first in the
menu-item
, then the menu-component (if any) and finally the menu. This allows a whole menu to have, for example,
callback-type
:data
without having to specify this in each item. Some items could override this by having their
callback-type
slot non-
nil
if needed.
To specify a mnemonic in the menu item, you can use the initarg
:mnemonic
, or the initargs
:mnemonic-title
and
:mnemonic-escape
. These initargs are all interpreted just as in menu.
A menu item should not be used more in more than one place at a time.
help-key is interpreted as described for element.
accelerator can be a character or string specifying a key gesture which will be the accelerator for the menu item.
Note that
both-case-p
characters are not allowed with the single modifier
Shift
in the accelerator argument. So instead of
:accelerator "shift-x"
:accelerator "X"
Note that the
Shift
modifier still appears in the menu.
A
both-case-p
character is allowed with
Shift
if there are other modifiers, for example
:accelerator "alt-shift-x"
If
accelerator
is a
character
then the system adds the normal modifier for the platform. That is,
Command
on Cocoa and
Control
on Microsoft Windows. The shortcut is validated for the platform.
If
accelerator
is a
string
with modifier keys then the system uses it only if it follows the normal conventions for the platform. The shortcut is validated for the platform.
The special virtual modifier name "accelerator" is allowed in string values of accelerator . It is interpreted as the normal modifier key for the platform. For example:
:accelerator "accelerator-x"
means
Control+X
on Microsoft Windows and Motif, and
Command+X
on Cocoa.
If accelerator is a plist then its keys are keywords naming some or all of the supported libraries (as returned by default-library). The plist's values are characters or strings which the system interprets as above, except that no check is made that the keyboard shortcut is valid for the platform.
accelerator
has a special default value
:default
, which means that, depending on interface-keys-style for the interface, a standard accelerator is added if the item title matches a standard menu command.
alternative
, when true, makes the
menu-item
an "alternative item". Alternative items are invoked if modifiers are held while selecting the "main item". These modifiers are defined by the item's
accelerator
. The main item is the one before the first alternative item, and each alternative item must be within the same menu and menu component. For an example see
examples/capi/elements/accelerators.lisp
and for more information see the section "Alternative menu items" in the
LispWorks CAPI User Guide
.
(capi:contain (make-instance 'capi:menu-item
:text "Press Me"))
(capi:contain (make-instance 'capi:menu-item
:data :red
:print-function
'string-capitalize))
(capi:contain (make-instance
'capi:menu-item
:data :red
:print-function 'string-capitalize
:callback #'(lambda (data interface)
(capi:display-message
"Pressed ~S"
data))))
In this example note how the File menu gets accelerators automatically for its standard items:
(defun do-menu-item (item)
(capi:display-message
(format nil "~A" (capi:item-data item))))
(capi:define-interface mmm () ()
(:menu-bar f-menu a-menu)
(:menus
(f-menu
"File"
(("Open..." :data "Open...")
("New" :data "New"))
:callback 'do-menu-item
:callback-type :item)
(a-menu
"Another Menu"
(("Open..." :data "Another Open")
("New" :data "Another New")
("Blancmange" :data "Blancmange"
:accelerator #\Ctrl-\b))
:callback 'do-menu-item
:callback-type :item))
(:default-initargs
:width 300
:height 200))
;; This causes automatic accelerators on all platforms.
;; That is the default behavior on Microsoft Windows.
(defmethod capi:interface-keys-style ((self mmm))
:pc)
(capi:contain (make-instance 'mmm))
There are further examples in the files
examples/capi/applications/hangman.lisp
and
examples/capi/printing/fit-to-page.lisp
.