Programming Reference

ODFocusOwnerIterator

Class Definition File	FocusOwn.idl
Class C++ Binding	FocusOwn.xh
Class Hierarchy	SOMObject ODObject ODFocusOwnerIterator
Description	An object of the ODFocusOwnerIterator class provides access to all owners of a nonexclusive focus. Focuses may be exclusive or nonexclusive. All of the standard focuses defined by OpenDoc are exclusive, meaning that only one frame can own a focus at a time. If you create a new kind of focus, you can make it nonexclusive, meaning that several frames could share ownership of it. You must create a focus-owner iterator if you create a focus module for a nonexclusive focus. The focus module keeps a list of all individual frames that own the nonexclusive focus. A focus-owner iterator contains a reference to the focus module that manages the nonexclusive focus and provides access to all of the owner frames. You use a focus-owner iterator to apply an operation to all owners of a nonexclusive focus. For example, a part might use a focus-owner iterator to notify all frames that own a video input focus to synchronize themselves so that the video is displayed in all of the frames simultaneously. The ODFocusOwnerIterator class is an abstract superclass that you can subclass to create a focus-owner iterator. Your part creates a focus-owner iterator object by calling the arbitrator's CreateOwnerIterator method. OpenDoc in turn calls the appropriate focus module's CreateOwnerIterator method, which returns a reference to a focus-owner iterator object. While you are using a focus-owner iterator, you should not modify the list of focus owners. You must postpone adding frames to or removing frames from the list of focus owners until after you have deleted the iterator. 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 ODFocusOwnerIterator. somInit somUninit
Methods	The methods defined by the ODFocusOwnerIterator class include: First InitFocusOwnerIterator IsNotComplete Next
Overridden Methods	There are no methods overridden by the ODFocusOwnerIterator class.

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 focus has no owners.

Remarks

Your part calls this method before calling this focus-owner 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 focus owners was modified while the iteration was in progress.

Override Policy

If you subclass ODFocusOwnerIterator, you must override this method. Your override must not call its inherited method; that is, your override must implement this method's functionality completely.

InitFocusOwnerIterator

This method initializes this focus-owner iterator object.

Signature
void InitFocusOwnerIterator (ODTypeToken focus, ODFocusModule *focusModule)

Parameters

focus (ODTypeToken) - input

A tokenized string representing the nonexclusive focus type of the owner returned by this iterator.

This parameter must be the tokenized form of a focus constants or the tokenized form of a part-specific focus type. You can call the session object's Tokenize method to obtain a token corresponding to an ODFocusType constant. For a list of ODFocusType constants, see ODFocusType.

focusModule (ODFocusModule *) - input

A reference to a focus module which lists the owners of the specified focus.

Returns

None.

Remarks

This method is not called directly to initialize this focus-owner iterator object, but is called by a subclass-specific initialization method. By convention, every subclass of ODFocusOwnerIterator should have a separate initialization method (for example, the InitMyFocusOwnerIterator method) that is called when an instance of that subclass is created. The override method may have additional parameters beyond those of the InitFocusOwnerIterator method. The InitMyFocusOwnerIterator method should call the inherited InitFocusOwnerIterator method at the beginning of its implementation.

If you subclass ODFocusOwnerIterator, your subclass-specific initialization method, rather than its somInit method, should handle any initialization code that can potentially fail. For example, your initialization method may attempt to allocate memory for your focus-owner iterator.

Override Policy

If you subclass ODFocusOwnerIterator, you must not override this method.

Related Methods

ODSession::Tokenize

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

Your part calls this method to test whether more focus owners remain in the iteration sequence. This method returns kODTrue if the preceding call to the First or Next method found a focus owner. This method returns kODFalse when you have examined all the focus owners (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 focus owners was modified while the iteration was in progress.

Override Policy

If you subclass ODFocusOwnerIterator, you must override this method. Your override must not call its inherited method; that is, your override must implement this method's functionality completely.

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

Your part calls this method. If your part calls this method before calling this focus-owner 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 focus owners was modified while the iteration was in progress.

Override Policy

If you subclass ODFocusOwnerIterator, you must override this method. Your override must not call its inherited method; that is, your override must implement this method's functionality completely.

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