Programming Reference: ODFocusSetIterator

# Programming Reference

## ODFocusSetIterator

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

Class Hierarchy

    SOMObject
       ODObject
          ODFocusSetIterator

Description

An object of the ODFocusSetIterator class provides access to all focuses in a focus set.

You use a focus-set iterator to apply an operation to all focuses in a focus set. For example, you might store a focus set with all the focuses owned by a given frame and then use a focus-set iterator to search for a particular focus in a focus set.

Your part creates a focus-set iterator object by calling a focus set's CreateIterator method, which returns a reference to a focus-set iterator object.

While you are using a focus-set iterator, you should not modify or delete the focus set. You must postpone adding to or removing focuses from the focus set until you delete the iterator.

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 ODFocusSetIterator class include:

- First
- IsNotComplete
- Next

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

### First

This method begins the iteration and returns the first focus in the focus set.

Signature

    ODTypeToken First ()

Parameters

None.

Returns

rv (ODTypeToken) - returns

  A tokenized string representing the first focus in the focus set or kODNullFocus if the focus set is empty.

Remarks

Your part must call this method before calling this focus-set iterator's IsNotComplete method for the first time. This method may be called multiple times; each time, it resets the iteration.

Exception Handling

kODErrIteratorOutOfSync | The focus set was modified while the iteration was in progress.

### 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.

  kODTrue | The iteration is incomplete.
  kODFalse | The iteration is complete.

Remarks

Your part calls this method to test whether more focuses remain in the focus set. This method returns kODTrue if the preceding call to the First or Next method found a focus. This method returns kODFalse when you have examined all the focuses (that is, when the previous call to First or Next returned kODNULL). If the focus set is empty, this method always returns kODFalse.

Exception Handling

kODErrIteratorNotInitialized | This method was called before calling the First or Next method to begin the iteration.
kODErrIteratorOutOfSync | The focus set was modified while the iteration was in progress.

### Next

This method returns a reference to the next focus in the focus set.

Signature

    ODTypeToken Next ()

Parameters

None.

Returns

rv (ODTypeToken) - returns

  A tokenized string representing the next focus in the focus set or kODNullFocus if you have reached the end of the focus set.

Remarks

If your part calls this method before calling this focus-set iterator's First method to begin the iteration, this method works the same as calling the First method.

Exception Handling

kODErrIteratorOutOfSync | The focus set was modified while the iteration was in progress.

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