All Manuals > CAPI User Guide > 6 Choices > 6.8 General properties of choices


6.8.3 Callbacks

All choices can have callbacks associated with them. Callbacks are invoked both by mouse button presses and keyboard gestures that change the selection or are "Action Gestures" such as Return . Different sorts of gesture can have different sorts of callback associated with them.

The following callbacks are available: :selection-callback , :retract-callback (called when a deselection is made), :extend-callback , :action-callback (called when a double-click occurs) and :alternative-action-callback (called when a modified double-click occurs). What makes one choice different from another is that they permit different combinations of these callbacks. This is a consequence of the differing interactions. For example, you cannot have an :extend-callback in a radio button panel, because you cannot extend selection in one.

Callbacks pass data to the function they call. There are default arguments for each type of callback. Using the :callback-type keyword allows you to change these defaults. Example values of callback-type are :interface (which causes the interface to be passed as an argument to the callback function), :data (the value of the selected data is passed), :element (the element containing the callback is passed) and :none (no arguments are passed). Also there is a variety of composite :callback-type values, such as :data-interface (which causes two arguments, the data and the interface, to be passed). See the callbacks entry in the LispWorks CAPI Reference Manual for a complete description of :callback-type values.

The following example uses a push button and a callback function to display the arguments it receives.

(defun show-callback-args (arg1 arg2)
  (display-message "The arguments were ~S and ~S" arg1 arg2))
(setq example-button 
      (make-instance 'push-button
                     :text "Push Me"
                     :callback 'show-callback-args
                     :data "Here is some data"
                     :callback-type :data-interface))
(contain example-button)

Try changing the :callback-type to other values.

If you do not use the :callback-type argument and you do not know what the default is, you can define your callback function with lambda list (&rest args) to account for all the arguments that might be passed.

Specifying a callback that is invalid for a particular choice causes a compile-time error.


CAPI User Guide (Macintosh version) - 30 Aug 2011