6.2.3 Deselection, retraction, and actions

As well as selecting items, users often want to deselect them. Items in multiple-selection and extended-selection lists may be deselected.

In a multiple-selection list, deselection is done by clicking on the selected item again with either of the selection or extension gestures.

In an extended-selection list, deselection is done by performing the extension gesture upon the selected item. (If this was done using the selection gesture, the list would behave as a single-selection list and all other selections would be lost.)

Just like a selection, a deselection -- or retraction -- can have a callback associated with it.

For a multiple-selection list panel, there may be the following callbacks:

• :selection-callback -- called when a selection is made
• :retract-callback -- called when a selection is retracted

Consider the following example. The function set-title changes the title of the interface to the value of the argument passed to it. By using this as the callback to the check-button-panel , the title of the interface is set to the current selection. The retract-callback function displays a message dialog with the name of the button retracted.

1. Display the example window:

(defun set-title (data interface)

  (setf (interface-title interface)

        (format nil "~A" (string-capitalize data))))

(make-instance 'check-button-panel

               :items '(one two three four five)

               :print-function 'string-capitalize

               :selection-callback 'set-title

               :retract-callback 'test-callback)

(contain *)

Figure 6.5 The example check button panel before the callback.



2. Try selecting one of the check buttons. The window title will change:

Figure 6.6 The example check button panel after the callback.



3. Now de-select the button. Notice that the retract-callback is called.

For an extended-selection list pane, there may be the following callbacks:

• :selection-callback -- called when a selection is made
• :retract-callback -- called when a selection is retracted
• :extend-callback -- called when a selection is extended

Also available in extended-selection and single-selection lists is the action callback. This is called when you double-click on an item.

• :action-callback -- called when a double-click occurs

CAPI User Guide (Windows version) - 30 Aug 2011