Programming Guide

Accessing Objects through Iterators

The OpenDoc class library implements seven iterator classes, which you can use to access collections of OpenDoc objects such as facets, windows, and drag items. In addition, OpenDoc defines the interface for an iterator that you must subclass in all cases (ODEmbeddedFramesIterator), and one that you must subclass only if you create a focus module for a nonexclusive focus (ODFocusOwnerIterator).

All OpenDoc iterator classes share certain characteristics, and you can use them all in a similar fashion. The iterators that you implement should also function in the same manner. For example, all iterators have at least these three methods:

First	Begins the iteration: sets your position to the first element in the collection, and returns the element at that position.
Next	Advances your position in the collection by one, and returns the element at your new position.
IsNotComplete	Returns kODTrue if the element at your current position is valid; returns kODFalse if your current position is beyond the last element in the collection.

Some iterators also have these methods:

Last	Returns the final element in the collection.
Previous	Returns the element in the collection prior to your current position.

For most iterators, the First and Next methods return their collection items as function results; for some, the collection items are returned in output parameters.

Iteration is not complete until you have called First or Next and it has returned kODNULL. If you have just called Next and obtained the last member of the collection, subsequently calling IsNotComplete will return kODTrue because you can still call Next one more time (it will return kODNULL). After you have called First or Next and it has returned kODNULL, calling IsNotComplete will return kODFalse.

Some iterators allow you to traverse the collection in either direction (beginning-to-end or end-to-beginning). For those iterators, the direction is an invariant; once the iteration has begun, you can't change directions. If you are traversing the collection from the beginning to the end, you call First followed by a series of calls to Next; in this case you cannot call Previous. If you are traversing the collection from the end to the beginning, you call Last followed by a series of calls to Previous; in this case you cannot call Next.

You can set up an iteration in several ways. A common method is to set up a for loop that uses the IsNotComplete method to test for completion:

ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev); for (ODFacet* facet = iter->First(ev); iter->IsNotComplete(ev); facet = iter->Next(ev)) { . . . // Perform the task of the iteration }

Or you can use a while statement to test for completion:

ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev); ODFacet* facet = iter->First() while (iter->IsNotComplete()) { . . . // Perform the task of the iteration facet = iter->Next(ev); }

A third possibility (if the Next method returns its item as a function result and if it consistently returns kODNULL for a nonexistent element) is to use that method itself to test for completion:

ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev); while ((facet = iter->Next(ev)) != kODNULL) { . . . // Perform the task of the iteration }

OpenDoc iterators consistently follow these conventions:

• You can call Next without first calling First. If you do, your first call to Next works the same as calling First.

• You must call either First or Next before calling IsNotComplete. If you do not, IsNotComplete generates the exception kODErrIteratorNotInitialized.

• For an empty collection, First and Next return kODNULL (if that type of iteration returns its information in the function result) and IsNotComplete returns kODFalse.

• If IsNotComplete returns kODTrue, the last item obtained is valid.

• If IsNotComplete returns kODFalse (at the end of the iteration), Next will return kODNULL (if that type of iteration can return null values).

• If the collection is modified while an iteration is in progress, calling any of these iterator methods generates the exception kODErrIteratorOutOfSync.