All Manuals > CAPI User Guide and Reference Manual > 5 Choices - panes with items

5.11 Operations on collections (choices) and their items

This section describes how you can access the items of a collection. In practice you will perform these operations on instances of subclasses of choice.

5.11.1 Accessing items

Given a collection and an index, you can retrieve the actual items in the collection by get-collection-item. Find the number of items in a collection at any point by count-collection-items. map-collection-items can be used to map a function over the collection items. print-collection-item can be used to "print" an item, that is generate the same string that will be displayed for this item. The collection accessor collection-items returns a list of the items in the collection, and can be used with setf to set the items.

5.11.2 Efficient manipulation of collection items

It is always possible to modify all the items of a collection by using setf with collection-items on it. However that can be expensive when called often with large numbers of items, and can cause flickering on screen. For typical choices (when items-get-function is svref), it is possible to modify the items of the choice more efficiently by using one of replace-items, remove-items or append-items.

Note: graph-pane and tree-view are not "typical" (their items-get-function is not svref) and therefore these functions cannot be used on these panes.

5.11.3 Searching in a collection

The function search-for-item can be used to find an item in a collection.

find-string-in-collection can be used to find a string in the printed items (that is, in the result of calling the print function). There is also collection-find-string which prompts the user for the string and then searches, and collection-find-next-string to continue the search from the previous match. collection-last-search can be used to retrieve the last search string, if any.

CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:19