All Manuals > COM/Automation User Guide and Reference Manual > 4 Automation Reference Entries

standard-automation-collection 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.

Examples

See the example in this directory:

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

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


COM/Automation User Guide and Reference Manual - 01 Dec 2021 19:38:41