Class

Summary

A collection 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.

The following initargs are geometry hints, influencing the initial size and position of a collection:

:x

The x position of the collection in a pinboard.

:y

The y position of the collection in a pinboard.

:external-min-width

The minimum width of the collection in its parent.

:external-min-height

The minimum height of the collection in its parent.

:external-max-width

The maximum width of the collection in its parent.

:external-max-height

The maximum height of the collection in its parent.

:visible-min-width

The minimum visible width of the collection.

:visible-min-height

The minimum visible height of the collection.

:visible-max-width

The maximum visible width of the collection.

:visible-max-height

The maximum height of the collection.

:internal-min-width

The minimum width of the display region.

:internal-min-height

The minimum height of the display region.

:internal-max-width

The maximum width of the display region.

:internal-max-height

The maximum height of the display region.

Accessors

collection-items
collection-print-function
collection-test-function

Readers

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

Description

The main use of 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, whilst the CAPI item s 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 return. If collect-results-p is non- nil , then it should also return the results of these calls in a list.

test-function should be suitable for comparing the items in your collection. For example, if there are both strings and integers amongst your items , you should supply test-function equal .

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 , help-key and the geometry hints are intepreted as described in element.

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)

See also

append-items
count-collection-items
get-collection-item
item
map-collection-items
print-collection-item
search-for-item