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. |
Methods | The methods defined by the ODEmbeddedFramesIterator class include: |
Overridden Methods | There are no methods overridden by the ODEmbeddedFramesIterator class. |
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.
This method should begin the iteration and return a reference to the first frame in the iteration sequence.
Signature
ODFrame *First () |
Parameters
None.
Returns
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.
This method should initialize this embedded-frames iterator object.
Signature
void InitEmbeddedFramesIterator (ODPart *part) |
Parameters
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
This method should indicate whether the iteration is incomplete.
Signature
ODBoolean IsNotComplete () |
Parameters
None.
Returns
| 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.
This method should indicate if this embedded-frames iterator is valid.
Signature
ODBoolean IsValid () |
Parameters
None.
Returns
| 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
This method should return a reference to the next frame in the iteration sequence.
Signature
ODFrame *Next () |
Parameters
None.
Returns
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.
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.