5.7.3 Callbacks

All choices can have callbacks associated with them. These callbacks are activated when the application user makes a selection, and 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 , and :action-callback (called when a 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 are :interface (which causes the interface to be passed as an argument to the callback function), :data (which causes the value of the selected data to be passed) and :none (whereby 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))

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.