menu-item

menu-item Class

Summary

An individual item in a menu or menu component.

Package

capi

Superclasses

Initargs

`:accelerator`	A character, string or plist, or the keyword `:default`.
`:alternative`	A generalized boolean.
`:help-key`	An object used for lookup of help. Default value `t`.
`:mnemonic`	A character, integer or symbol specifying a mnemonic for the menu item.
`:mnemonic-escape`	A character specifying the mnemonic escape. The default value is `#\&`.
`:mnemonic-title`	A string specifying the text and a mnemonic.
`:selected-function`	A setup callback determining whether the item is selected.
`:enabled-function-for-dialog`
	`nil`, `t`, `:same-as-normal` or a function designator. Determines enabled state when a dialog is on screen.

Readers

help-key

Description

The class menu-item is an individual item in a menu or menu component. Instances of menu-item are often made automatically by define-interface, but you can make them explicitly as well.

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.

If selected-function is non-nil it should 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. The default value of selected-function is nil.

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"

use:

: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. For the full set of standard accelerators see 8.7.1 Standard default accelerators.

Note: accelerator is not supported when the menu-item is in the pane-menu of a simple-pane.

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:

(example-edit-file "capi/elements/accelerators")

and for more information see 8.8 Alternative menu items.

enabled-function-for-dialog determines whether the item is enabled when a dialog is on the screen. Items in the menu bar menus and sub-menus are disabled by default while a dialog is on the screen on top of the active window. You can override this by specifying enabled-function-for-dialog. The value can be one of:

`t`	The item is enabled whenever there is a dialog.
`nil`	The item is disabled whenever there is a dialog.
`:same-as-normal`	Do the same as when there is no dialog. This depends on the `enabled-function` (see menu-object).
A function	A function that is called instead of the `enabled-function` to decide if the item should be enabled. It is called with one argument, by the default the menu interface, which can be overridden by the initarg `:setup-callback-argument` (see menu-object for details).

The default value of enabled-function-for-dialog is nil.

Notes

Some accelerators do not work on some platforms because they have other standard meanings, for example on Microsoft Windows F1 always invokes the help-callback.

On X11/Motif the accelerators of alternative items do not work.

Examples

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

These are further examples:

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

(example-edit-file "capi/printing/fit-to-page")