Programming Reference: ODEmbeddedFramesIterator

# Programming Reference

## ODEmbeddedFramesIterator

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

Class Hierarchy

    SOMObject
       ODObject
          ODEmbeddedFramesIterator

Description

An object of a subclass of ODEmbeddedFramesIterator provides access to all frames directly embedded within a display frame of you part.

If your part is a container part, there is an additional class that you must subclass and implement along with your part editor (your subclass of ODPart). You must provide an embedded-frames iterator (a subclass of ODEmbeddedFramesIterator) to allow callers to access all frames directly embedded within a display frame of your part. A caller needs access to your part's embedded frames to access the parts embedded in those frames. For example, a caller might use an embedded-frames iterator if it has a spelling checker that needs to find all text parts in your document to operate.

The ODEmbeddedFramesIterator class is an abstract superclass that you must subclass to create your embedded-frames iterator. Callers create your embedded-frames iterator object by calling your part's CreateEmbeddedFramesIterator method, which returns a reference to an embedded-frames iterator object.

While you are using an embedded-frames iterator, you should not modify the list of embedded frames for the part. You must postpone adding frames to or removing frames from the list of embedded frames for the part until after you have deleted the iterator.

For more information related to frame objects, see the description of the class ODFrame. For more information on accessing objects through iterators, see the chapter on OpenDoc runtime features in the OpenDoc Programming Guide.

Overriding Inherited Methods

The following methods are inherited and available for use by your subclass of ODEmbeddedFramesIterator.

- Purge
- somInit
- somUninit

Methods

The methods defined by the ODEmbeddedFramesIterator class include:

- CheckValid
- First
- InitEmbeddedFramesIterator
- IsNotComplete
- IsValid
- Next
- PartRemoved

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

### CheckValid

This method should check whether this embedded-frames iterator is valid and generate an exception if it is not valid.

Signature

    void CheckValid ()

Parameters

None.

Returns

None.

Remarks

Every subclass of ODEmbeddedFramesIterator must test the embedded-frames iterator's validity at the beginning of the implementation of each of its noninherited methods (except for the subclass-specific initialization method) by calling this method or the IsValid method. Unlike the IsValid method, this method has no effect if this embedded-frames iterator is valid; otherwise, it should generate an exception.

If you want to ensure that you make calls only to a valid embedded-frames iterator, without generating an exception, then call the IsValid method instead.

Exception Handling

kODErrInvalidIterator | This embedded-frames iterator is invalid and should not be used because the part that created it no longer exists.

Override Policy

If you subclass ODEmbeddedFramesIterator, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### First

This method should begin the iteration and return a reference to the first frame in the iteration sequence.

Signature

    ODFrame *First ()

Parameters

None.

Returns

rv (ODFrame *) - returns

  A reference to the first frame in the iteration sequence or kODNULL if the part has no embedded frames.

Remarks

A client of this embedded-frames iterator calls this method before calling this embedded-frames iterator's IsNotComplete method for the first time. This method may be called multiple times; each time, it resets the iteration.

Your override of this method should not increment the reference count of the returned frame object.

Exception Handling

kODErrIteratorOutOfSync | The list of embedded frame for the part was modified while the iteration was in progress.

Override Policy

If you subclass ODEmbeddedFramesIterator, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### InitEmbeddedFramesIterator

This method should initialize this embedded-frames iterator object.

Signature

    void InitEmbeddedFramesIterator (ODPart *part)

Parameters

part (ODPart *) - input

  A reference to the part whose frames this iterator traverses.

Returns

None.

Remarks

Your part's CreateEmbeddedFramesIterator method calls this method when this embedded-frames iterator is created. A client using this embedded-frames iterator does not call this method.

Override Policy

If you subclass ODEmbeddedFramesIterator, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODPart::CreateEmbeddedFramesIterator

### IsNotComplete

This method should indicate 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

A client of this embedded-frames iterator calls this method to test whether more frames remain in the iteration sequence. This method returns kODTrue if the preceding call to the First or Next method found a frame. This method returns kODFalse when you have examined all the frames (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 sequence.
kODErrIteratorOutOfSync | The list of embedded frames for the part was modified while the iteration was in progress.

Override Policy

If you subclass ODEmbeddedFramesIterator, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### IsValid

This method should indicate if this embedded-frames iterator is valid.

Signature

    ODBoolean IsValid ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the embedded-frames iterator is valid.

  kODTrue | The embedded-frames iterator is valid.
  kODFalse | The embedded-frames iterator is not valid.

Remarks

A client of this embedded-frames iterator calls this method if it wants to ensure that it makes calls only to a valid embedded-frames iterator, without generating an exception.

Override Policy

If you subclass ODEmbeddedFramesIterator, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

Related Methods

- ODEmbeddedFramesIterator::CheckValid

### Next

This method should return a reference to the next frame in the iteration sequence.

Signature

    ODFrame *Next ()

Parameters

None.

Returns

rv (ODFrame *) - returns

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

Remarks

A client of this embedded-frames iterator calls this method. If the client calls this method before calling this embedded-frame iterator's First method to begin the iteration, this method works the same as calling the First method.

Your override of this method should not increment the reference count of the returned frame object.

Exception Handling

kODErrIteratorOutOfSync | The list of embedded frames for the part was modified while the iteration was in progress.

Override Policy

If you subclass ODEmbeddedFramesIterator, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

### PartRemoved

This method should invalidate this embedded-frames iterator.

Signature

    void PartRemoved ()

Parameters

None.

Returns

None.

Remarks

The part whose embedded frames this iterator traverses calls this method when the part closes. This embedded-frames iterator then becomes invalid and should no longer attempt to communicate with its part; any pointers that this embedded-frames iterator had to its part should be considered invalid.

Override Policy

If you subclass ODEmbeddedFramesIterator, you must override this method. Your override method must not call its inherited method. Your override method must implement this method's function.

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