Class Definition File | FocusMod.idl |
Class C++ Binding | FocusMod.xh |
Class Hierarchy |
SOMObject
ODObject
ODFocusModule
|
Description | An object of the ODFocusModule class is used to manage particular types of focus or ownership of a shared resource. A focus is a designation of ownership of a given shared resource or feature, such as the keyboard or menu bar. A frame that owns an event-related focus receives events pertaining to that resource. A focus module manages a particular focus, maintaining the identity of the individual frame that own the focus. The arbitrator uses at least one internal focus module to handle standard OpenDoc event types of a particular platform. Typically, you do not need to subclass ODFocusModule or even access the internal focus module directly; however, you can define additional focus types, as needed, to handle other kinds of user events (such as input from new kinds of devices) by creating a new kind of focus module. The ODFocusModule class is an abstract superclass that you can subclass to create a focus module. You can create a focus module object from within a shell plug-in object or from within one of your part's methods that are called during startup. Before OpenDoc is able to recognize your new type of focus, you must register the associated focus module with the arbitrator. To register a focus module, you call the arbitrator's RegisterFocus method; to remove the focus module, you can call the arbitrator's UnregisterFocus method. For more information related to the arbitrator, see the class description for ODArbitrator. For more information on creating custom focus types, see the chapter on extending OpenDoc in the OpenDoc Programming Guide. |
Overriding Inherited Methods | The following methods are inherited and available for use by your subclass of ODFocusModule. |
Methods | The methods defined by the ODFocusModule class include: |
Overridden Methods | There are no methods overridden by the ODFocusModule class. |
This method should cancel the request for the frame to relinquish ownership of the specified exclusive focus.
Signature
void AbortRelinquishFocus (ODTypeToken focus,
ODFrame *requestingFrame)
|
Parameters
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.
Returns
None.
Remarks
OpenDoc calls this method, which in turns calls the AbortRelinquishFocus method of the part that owns the focus. This method should give those focus owners who have indicated willingness to relinquish focus an opportunity to back out of changes initiated when OpenDoc first called the part's BeginRelinquishFocus method.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods
This method should return a reference to the frame that owns the specified exclusive focus.
Signature
ODFrame *AcquireFocusOwner (ODTypeToken focus) |
Parameters
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 on ODFocusType constants, see ODFocusType.
Returns
Remarks
OpenDoc calls this method. A part can obtain a reference to the owner of a specified exclusive focus by calling the arbitrator's AcquireFocusOwner method, which in turn calls this method. If the focus is not registered, the focus has no focus module and this method is never called.
Before returning the frame object, your override method should call the frame object's Acquire method. When the caller has finished using the returned frame object, it should call the frame object's Release method.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods
This method should indicate whether the current owner of the specified exclusive focus is willing to give up ownership of the focus.
Signature
ODBoolean BeginRelinquishFocus (ODTypeToken focus,
ODFrame *requestingFrame)
|
Parameters
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
Returns
| kODTrue | The current owner is willing to give up ownership. |
| kODFalse | The current owner is not willing to give up ownership. |
Remarks
OpenDoc calls this method, which in turn calls the BeginRelinquishFocus method of the part that owns the focus. If the part's BeginRelinquishFocus method returns kODTrue (the typical case), this method should return kODTrue; if the part's BeginRelinquishFocus method returns kODFalse, this method should return kODFalse.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods
This method should signal to the part that owns the specified exclusive focus that it is about to lose the ownership of the it.
Signature
void CommitRelinquishFocus (ODTypeToken focus,
ODFrame *requestingFrame)
|
Parameters
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.
Returns
None.
Remarks
OpenDoc calls this method, which in turn calls the CommitRelinquishFocus method of the part that owns the focus.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods
This method should create a focus-owner iterator to give callers access to the frames that own the specified nonexclusive focus.
Signature
ODFocusOwnerIterator *CreateOwnerIterator (ODTypeToken focus) |
Parameters
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.
Returns
Remarks
OpenDoc calls this method. This method should create and initialize an instance of a focus-owner iterator that can iterate over this focus module's focus owners, and return the iterator to the caller.
While you are using the focus-owner iterator, you should not modify the list of focus owners. You must postpone adding items to or removing items from the list of facet owners until after you have deleted the iterator.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods
This method initializes this focus-module object.
Signature
void InitFocusModule (ODSession *session) |
Parameters
Returns
None.
Remarks
This method is not called directly to initialize this focus-module object but is called by a subclass-specific initialization method. By convention, every subclass of ODFocusModule should have a separate initialization method (for example, the InitMyFocusModule method) that is called when an instance of that subclass is created. The override method may have additional parameters beyond those of the InitFocusModule method. The InitMyFocusModule method should call the inherited InitFocusModule method at the beginning of its implementation.
If you subclass ODFocusModule 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 module.
Override Policy
If you subclass ODFocusModule, you should not override this method.
This method should indicate whether the specified focus is exclusive.
Signature
ODBoolean IsFocusExclusive (ODTypeToken focus) |
Parameters
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.
Returns
| kODTrue | The specified focus is exclusive. |
| kODFalse | The specified focus is not exclusive. |
Remarks
Focuses may be exclusive or nonexclusive. All of the standard focuses defined by OpenDoc are exclusive, meaning that only one frame can own the 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.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods
This method should record the specified frame as the owner of the specified focus.
Signature
void SetFocusOwnership (ODTypeToken focus,
ODFrame *frame)
|
Parameters
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.
Returns
None.
Remarks
OpenDoc calls this method. This method should record, in this focus module's internal structures, the new focus ownership.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods
This method should transfer ownership of the specified focus from one frame to another frame.
Signature
void TransferFocusOwnership (ODTypeToken focus,
ODFrame *transferringFrame,
ODFrame *newOwner)
|
Parameters
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.
Returns
None.
Remarks
OpenDoc calls this method. This method should record, in the focus module's internal structures, the transfer of focus ownership.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods
This method should remove the specified frame as the owner of the specified focus.
Signature
void UnsetFocusOwnership (ODTypeToken focus,
ODFrame *frame)
|
Parameters
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.
Returns
None.
Remarks
OpenDoc calls this method. This method should record, in the focus module's internal structures, the loss of focus ownership. This method can be called for exclusive and nonexclusive focuses.
Override Policy
If you subclass ODFocusModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.
Related Methods