standard-automation-collection

standard-automation-collection Class

Summary

A framework for implementing Automation collections.

Package

com

Superclasses

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.

Examples

See the example in this directory:

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