menu-object Class

Summary

The class menu-object is the superclass of all menu objects, and provides functionality for handling generic aspects of menus, menu components and menu items.

Package

capi

Superclasses

callbacks

Subclasses

titled-menu-object

Initargs

Accessors

menu-popup-callback
menu-title
menu-title-function

Readers

menu-object-enabled

Description

The simplest way to give a title to a menu-object is to just supply a title string, and this will then appear as the title of the object.

Alternatively, a title-function can be provided which will be called when the menu is about to appear and which should return the title to use. By default title-function is called on the interface of the menu-object, but this argument can be changed by passing the initarg setup-callback-argument.

To specify a mnemonic in the title returned by title-function, make title-function return the mnemonic as a second value. This value is interpreted in the same way as the mnemonic argument for menu.

When the menu object is about to appear on the screen, the CAPI does the following:

1. The setup callback items-function (if there is one) is called and the result is used to set the items, for menu and menu-component. The argument passed to items-function is the same as for the other setup callbacks (see below).
2. The popup-callback (if there is one) is called and can make arbitrary changes to that object. The popup-callback is always called with the menu object, regardless of the value of setup-callback-argument.
3. The other setup callbacks are called to set up the selection, enabled state and title. These setup callbacks include enabled-function for all menu-objects and title-function for all titled-menu-objects. The additional setup callbacks for menu-component are selection-function, selected-item-function, and selected-items-function. menu-item has the additional setup callback selected-function.

   By default setup-callback-argument is nil, which means that each of the setup callbacks is called on the interface of the menu-object. If setup-callback-argument is non-nil, then it is passed (instead of the interface) as the argument to each of the setup callbacks.

4. The menu containing the object appears with all of the changes made.

Note that enabled-slot is a short-hand means of creating an enabled-function which checks the value of a slot in the menu object's interface.

The enabled state of a menu-object is computed each time the menu is displayed, using enabled-function or enabled-slot. Therefore the accessor menu-object-enabled is only useful as a reader.

The callback argument is placed in the selection-callback, extend-callback and retract-callback slots unless these are given explicitly, and so will get called when the menu object is selected or deselected.

The callback-data-function is a function that is called with no arguments and the value it returns is used as the data to the callbacks.

Notes

1. The function enabled-function should not display a dialog or do anything that may cause the system to hang. In general this means interacting with anything outside the Lisp image, including files, databases and so on.
2. The subclass titled-menu-object is retained only for backward compatibility.

Examples

(capi:contain (make-instance
               'capi:menu-item
               :text "Press Me"
               :enabled-function #'(lambda (item)
                                     (eq (random 2)
                                     1))))

The next example illustrates the use of setup-callback-argument. The initialize-instance method adds to the "Some Numbers" menu a sub-menu that lists the selected items in the list-panel. By using setup-callback-argument in this menu, the setup callbacks (in this case enabled-function and items-function) are called directly on the list-panel.

Note that, while this example uses a CAPI object as the setup-callback-argument, any object of any type can be used.

(capi:define-interface my-interface ()
  ()
  (:panes
   (list-panel
    capi:list-panel
    :items '(1 2 3 4 5 6 7 8 9 0)
    :interaction :extended-selection
    :visible-min-height '(character 10)))
  (:menus
   (a-menu
    "Some Numbers"
    ("One" "Two")
    ))
  (:menu-bar a-menu))
 
(defmethod initialize-instance :after 
  ((self my-interface) &key)
  (with-slots (a-menu list-panel) self
    (setf (capi:menu-items a-menu)
          (append 
           (capi:menu-items a-menu)
           (list 
            (make-instance 'capi:menu
                           :items-function 
                           'capi:choice-selected-items
                           :setup-callback-argument 
                           list-panel
                           :enabled-function
                           'capi:choice-selection
                           :title 
                           "Selected Items"))))))
 
(capi:display (make-instance 'my-interface))

See also

menu
menu-item
menu-component