Class

Summary

A framework for implementing Automation collections.

Package

com

Superclasses

standard-i-dispatch

Initargs

:count-function

A function of no arguments that should return the number of items in the collection. This initarg is required.

:items-function

A function of no arguments that should return a sequence of items in the collection. This function is called by the implementation of _NewEnum and the sequence is copied. Exactly one of :items-function and :item-generator-function must be specified.

:item-generator-function

A function of no arguments that should return an item generator , which will generate the items in the collection. See below for more details. Exactly one of :items-function and :item-generator-function must be specified.

:data-function

A function called on each item that the :items-function or :item-generator-function returns. This is called when iterating, to produce the value that is returned to the caller.

:item-lookup-function

A function which takes a single argument, an integer or a string specifying an item. The function should return the item specified. This initarg is required if the :item-method option is non-nil in define-automation-collection.

Description

The class standard-automation-collection provides a framework for implementing Automation collections. These typically provide a Count property giving the number of objects in the collect, a _NewEnum property for iterating over the element of the collection method and optionally an Item method for finding items by index or name.

The :count-function initarg specifies a function to count the items of the collection and is invoked by the implementation of the Count method.

Exactly one of the initargs :item-function and :item-generator-function must be specified to provide items for the implementation of the IEnumVARIANT instance returned by the _NewEnum method.

If :items-function is specified, then it will be called once when _NewEnum is called and should return a sequence of the items in the collection. This sequence is copied, so can be modified by the program without affecting the collection.

If :item-generator-function is specified, it should be an item generator that will generate all the items in the collection. It will be called once with the argument :clone when _NewEnum is called and then by the implementation of the resulting IEnumVARIANT interface. An item generator is a function of one argument which specifies what to do:

:next

Return two values: the next item and t. If there are no more items, return nil and nil.

:skip

If there are no more items, return nil. Otherwise skip the current item and return t.

:reset

Reset the generator so the first item will be returned again.

:clone

Return a copy of the item generator . The copy should have the same current item.

The :data-function initarg should be function to convert each item returned by the :items-function or the item generator into a value whose type is compatible with Automation (see Automation types, VT codes and their corresponding Lisp types). The default function is identity.

Example

See the example in this directory:

(example-edit-file "com/automation/collections/")

See also

define-automation-collection
standard-i-dispatch
i-dispatch