Programming Reference: ODWindowIterator

# Programming Reference

## ODWindowIterator

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

Class Hierarchy

    SOMObject
       ODObject
          ODWindowIterator

Description

An object of the ODWindowIterator class provides access to all windows of the window-state object.

You use a window iterator to apply an operation to all windows of all open drafts of the current session's document. For example, a root part might use a window iterator to tile all the open windows. A window iterator maintains a reference to its window-state object and to the current window object. The internal list of windows in the window-state object is ordered by creation time and is not related to front-to-back ordering of the windows.

Your part creates a window iterator object by calling the window-state object's CreateWindowIterator method, which returns a reference to a window iterator object.

While you are using a window iterator, you should not modify the list of opened windows. You must postpone adding windows to or removing windows from the list of open windows until after you have deleted the iterator.

For more information related to the window-state object, see the class description for ODWindowState. 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 ODWindowIterator class include:

- First
- IsNotComplete
- Last
- Next
- Previous

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

### First

This method begins the iteration and returns a reference to the first window in the window state.

Signature

    ODWindow *First ()

Parameters

None.

Returns

rv (ODWindow *) - returns

  A reference to the first window in the iteration sequence or kODNULL for an empty window state.

Remarks

If you are iterating from the first window to the last, your part must call this method before calling this window iterator's IsNotComplete method for the first time. This method may be called multiple times. Each call resets the iteration.

The Next method is called to step through the window list from first to last. This method does not increment the reference count of the returned window object.

Exception Handling

kODErrIteratorOutOfSync | The list of open windows was modified during the iteration.

### 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 windows remain in the window state. This method returns kODTrue if the preceding call to the First, Last, Next, or Previous method found a window. This method returns kODFalse when you have examined all the windows (that is, when the previous call to First, Last, Next, or Previous returned kODNULL).

Exception Handling

kODErrIteratorNotInitialized | This method was called before calling the First or Next method to begin the iteration.
kODErrIteratorOutOfSync | The list of open windows was modified during the iteration.

### Last

This method begins the iteration and returns a reference to the last window in the window state.

Signature

    ODWindow *Last ()

Parameters

None.

Returns

rv (ODWindow *) - returns

  A reference to the last window in the window state.

Remarks

If you are iterating from the last window to the first, your part must call this method before calling this window iterator's IsNotComplete method for the first time. This method may be called multiple times. Each call resets the iteration.

A Previous method call steps through the window list from last to first. This method does not increment the reference count of the returned window object.

Exception Handling

kODErrIteratorOutOfSync | The list of open windows was modified during the iteration.

### Next

This method returns a reference to the next window in the window state.

Signature

    ODWindow *Next ()

Parameters

None.

Returns

rv (ODWindow *) - returns

  A reference to the next window in the window state or kODNULL if you have reached the last window.

Remarks

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

This method does not increment the reference count of the returned window object.

Exception Handling

kODErrIteratorOutOfSync | The list of open windows was modified while the iteration was in progress.

### Previous

This method returns a reference to the previous window in the window state.

Signature

    ODWindow *Previous ()

Parameters

None.

Returns

rv (ODWindow *) - returns

  A reference to the previous window in the window state or kODNULL if you have reached the first window.

Remarks

If your part calls this method before calling this window iterator's Last method to begin the iteration, this method works the same as calling the Last method. This method does not increment the reference count of the returned window object.

Exception Handling

kODErrIteratorOutOfSync | The list of open windows was modified during the iteration.

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