Programming Reference: ODFacetIterator

# Programming Reference

## ODFacetIterator

Class Definition File | FacetItr.idl
Class C++ Binding | FacetItr.xh

Class Hierarchy

    SOMObject
       ODObject
          ODFacetIterator

Description

An object of the ODFacetIterator class provides access to all facets embedded in a facet.

A facet iterator is used to apply an operation to a facet and all its embedded facets. For example, you might use a facet iterator to make sure that all facets within a facet being invalidated are also invalidated.

Your part creates a facet iterator object by calling a facet's CreateFacetIterator method which returns a reference to a facet iterator object.

When you create a facet iterator, you specify the traversal type and sibling order. These two characteristics determine which facets are included in the iteration sequence and the order of the facets within the iteration sequence.

- If you specify top-down traversal, traverse the facet hierarchy top down, in depth-first order.

- If you specify bottom-up traversal, traverse the facet hierarchy bottom up, visiting the specified facet after visiting all its children. If the sibling order is front-to-back, the traversal starts with the front-most facet at the lowest level in the hierarchy. If the sibling order is back-to-front, the traversal starts with the back-most facet at the lowest level in the hierarchy.

- If you specify children-only traversal, traverse only the children of the specified facet (not including the specified facet itself).

While you are using a facet iterator, you should not modify the list of embedded facets or call the facet's MoveBefore or MoveBehind method. You must postpone adding facets to or removing facets from the list of embedded facets until after you have deleted the iterator.

For more information related to facet objects, see the class description for ODFacet. For more information on accessing objects through iterators, see the chapter on OpenDoc runtime features in the OpenDoc Programming Guide.

Methods

The methods defined by the ODFacetIterator class include:

- First
- IsNotComplete
- Next
- SkipChildren

Overridden Methods | There are no methods overridden by the ODFacetIterator class.

### First

This method begins the iteration and returns a reference to the first facet in the iteration sequence, as indicated by the traversal type and sibling order that were set for this iterator.

Signature

    ODFacet *First ()

Parameters

None.

Returns

rv (ODFacet *) - returns

  A reference to the first facet in the iteration sequence or kODNULL if the traversal type is children-only and the root facet has no embedded facets.

Remarks

The traversal type and sibling order are set by the facet's CreateFacetIterator method.

Your part must call this method before calling this facet iterator's IsNotComplete method for the first time. This method may be called multiple times. Each call resets the iteration.

Exception Handling

kODErrIteratorOutOfSync | The list of embedded facets was modified while the iteration was in progress.

Related Methods

- ODFacet::CreateFacetIterator

### IsNotComplete

This method indicates whether the iteration is incomplete.

Signature

    ODBoolean IsNotComplete ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the iteration is incomplete.

  TRUE | The iteration is incomplete.
  FALSE | The iteration is complete.

Remarks

Your part calls this method to test whether more facets remain in the iteration sequence. This method returns kODTrue if the preceding call to the First or Next method found a facet. This method returns kODFalse when you have examined all the facets (that is, when the previous call to First or Next returned kODNULL).

Exception Handling

kODErrIteratorNotInitialized | This method was called before calling the First or Next method to begin the iteration.
kODErrIteratorOutOfSync | The list of embedded facets was modified while the iteration was in progress.

### Next

This method returns a reference to the next facet in the iteration sequence.

Signature

    ODFacet *Next ()

Parameters

None.

Returns

rv (ODFacet *) - returns

  A reference to the next facet in the iteration sequence or kODNULL if you have reached the last facet.

Remarks

If you part calls this method before calling this facet iterator's First method to begin the iteration, then this method works the same as calling the First method.

Exception Handling

kODErrIteratorOutOfSync | The list of embedded facets was modified while the iteration was in progress.

### SkipChildren

This method advances to the next sibling, skipping over the embedded facets of the current facet if the traversal type of this iteration is top-down.

Signature

    void SkipChildren ()

Parameters

None.

Returns

None.

Remarks

If the traversal type for this iterator is not top-down, calling this method has no effect.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]