collection

collection Class

Summary

A class that collects together a set of items, and provides functionality for accessing and displaying them.

Package

capi

Superclasses

capi-object
callbacks

Subclasses

choice

Initargs

`:items`	The items in the collection.
`:print-function`	A function that prints an item.
`:test-function`	A comparison function between two items.
`:items-count-function`
	A function which returns the length of items.
`:items-get-function`
	A function that returns the `n`th item.
`:items-map-function`
	A function that maps a function over the items.
`:accepts-focus-p`	Specifies that the collection should accept input. The default value is `t`.
`:help-key`	An object used for lookup of help.
`:editing-callback`	Specifies an in-place editing callback for tree-view and list-panel.

Accessors

collection-items
collection-print-function
collection-test-function
collection-editing-callback

Readers

collection-items-count-function
collection-items-get-function
collection-items-map-function
help-key

Description

The main use of the class collection is as a part of the class choice, which provides selection capabilities on top of the collection handling, and which is used by list panels, button panels and menus amongst others.

The items in the collection are printed by print-collection-item.

Items can be instances of the CAPI class item or any Lisp object. The main difference is that non-CAPI items use the callbacks specified for the collection, while the CAPI items will use their callbacks in preference if these are specified.

By default, items must be a sequence, but this can be changed by specifying items-get-function, items-count-function, and items-map-function.

items-get-function should take as arguments the items and an index, and should return the indexed item. The default is svref.

items-count-function should take the items as an argument and should return the number of them.

items-map-function should take as arguments the items, a function function and a flag collect-results-p, and should call function on each of the items in turn. If collect-results-p is non-nil, then it should also return the results of these calls in a list.

print-function should be a one argument function which returns a string. The default is princ-to-string. To display an item, the collection call print-function with the item, and then draws the resulting string (the way it draws is different between the subclasses of choice). The time when print-function is called is not defined; it may happen before the string is needed for drawing, and may be cached so not called each time the item is drawn. The function choice-update-item can be used to flush the cache when needed.

test-function should be suitable for comparing the items in your collection, returning a boolean. For example, if there are both strings and integers amongst your items, you should supply test-function cl:equal. The default value of test-function is cl:eq.

You can change the items using (setf collection-items). Note that there is an optimization append-items that is sometimes useful when adding items.

accepts-focus-p and help-key are interpreted as described in element.

If editing-callback is nil (the default), then in-place editing is not allowed. If editing-callback is non-nil, then in-place editing may be allowed for the collection if the operating system supports it (currently this is only implemented for tree-view, list-panel and multi-column-list-panel). editing-callback is called by LispWorks with arguments:

collection collection column-index item action data

collection is the pane being edited. column-index is the column number being edited (0 meaning the first column). item is the item of collection being edited. action is one of:

`:editp`	The user wants to start editing the item. `editing-callback` should return true if the item can be edited and false otherwise. `data` is always `nil`.
`:validp`	The user wants to finish editing the item. `editing-callback` should return true if `data` (a string) is valid for this item and false otherwise.
`:set`	The item has been edited. `editing-callback` should parse `data` (a string) and set the item to it. The return value is ignored.
`:cancel`	The user has cancelled editing the item. `data` is always `nil`.
`:done`	The user has finished editing. `data` and `data` are both `nil`. The column-index and index are undefined in this call. Note: If the user enters a string that is the same as the current value, `editing-callback` may not be called with `:set` or `:cancel`, but it will always be called with `:done`, to ensure that you can do any cleanups that are needed.

Examples

The following code uses push-button-panel, a subclass of collection.

(capi:contain (make-instance
               'capi:push-button-panel
               :items '(one two three)))
 
(capi:contain (make-instance
               'capi:push-button-panel
               :items '(one two three)
               :print-function 'string-capitalize))

The following example provides a collection with all values from 1 to 6 by providing an items-get-function and an items-count-function.

(capi:contain (make-instance
               'capi:push-button-panel
               :items 6
               :items-get-function 
                 #'(lambda (items index) (1+ index))
               :items-count-function
                 #'(lambda (items) items)))

Here is an example demonstrating the use of CAPI items in a collections list of items to get more specific callbacks.

(defun specific-callback (data interface)
  (capi:display-message "Specific callback for ~S" 
                        data))
 
(defun generic-callback (data interface)
  (capi:display-message "Ordinary callback for ~S"
                        data))
 
(capi:contain (make-instance
               'capi:list-panel
               :items (list (make-instance
                             'capi:item
                             :text "Special"
                             :data 1000
                             :selection-callback 
                             'specific-callback)
                            2 3 4)
               :selection-callback 'generic-callback)
              :visible-min-width 200
              :visible-min-height 200)