Class Definition File | Arbitrat.idl |
Class C++ Binding | Arbitrat.xh |
Class Hierarchy |
SOMObject ODObject ODArbitrator |
Description | An object of the ODArbitrator class manages temporary ownership of shared resources or features among parts. A focus is a designation of ownership of a given shared resource. Focuses are defined according to the type of resource that each represents. For example, focus types include the keystroke focus, menu bar focus, and selection focus. Other focuses can be associated with system-wide resources, such as serial ports. Focuses are owned by frames. A frame's part relinquishes ownership of focuses when asked to, such as when another part is requesting ownership or when a frame is deleted. When a document is opened, the session object creates a single arbitrator object. All parts of that document share the arbitrator object; you can obtain a reference to it by calling the session object's GetArbitrator method. The OpenDoc arbitrator keeps track of which part owns a focus by consulting the focus module for that focus. A focus is registered if it has a focus module. The arbitrator is used by the OpenDoc dispatcher to determine where to send events. For example, the dispatcher directs keyboard events to the part that owns the keystroke focus and directs menu events to the part that owns the menu bar focus. Focuses may be exclusive or nonexclusive. All standard focuses defined by OpenDoc are exclusive, meaning that only one frame at a time can own a focus. The ODArbitrator class supports nonexclusive focuses, which can be owned by several frames. In such cases, the arbitrator provides a central location in which you can record and later obtain a list of the owners for that focus. For more information related to focuses, focus sets, focus types, and focus modules, see the class descriptions for ODFocusModule, ODFocusOwnerIterator, ODFocusSet, and ODFocusSetIterator. For more information related to the dispatcher, see the class description for ODDispatcher. |
Methods | The methods defined by the ODArbitrator class include: |
Overridden Methods | There are no methods overridden by the ODArbitrator class. |
This method returns 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 of ODFocusType constants, see ODFocusType.
Returns
Remarks
A part can obtain a reference to the owner of a specified exclusive focus by calling this method. This method looks up the focus module for the given focus for the specified focus and calls the focus module's AcquireFocusOwner method. If the focus is not registered, the focus has no focus module and this method is never called.
This method increments the reference count of the returned frame object. When you have finished using that frame object, you should call its Release method.
Related Methods
This method creates and initializes a focus set.
Signature
ODFocusSet *CreateFocusSet () |
Parameters
None.
Returns
Remarks
Your part calls this method to create a focus set to pass to the arbitrator's RequestFocusSet method.
Exception Handling
kODErrOutOfMemory | There is not enough memory to allocate the focus set object. |
Related Methods
This method creates a focus-owner iterator to give callers accesses to the frames that own a 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 ODFocus Type constant. For a list of ODFocusType constants, see ODFocusType.
Returns
Remarks
To get access to the owner of an exclusive focus, use the arbitrator's AcquireFocusOwner method.
While you are using a 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 focus owner until after you have deleted the iterator.
Exception Handling
kODErrFocusNotRegistered | The requested focus is not registered. |
kODErrOutOfMemory | There is not enough memory to allocate the focus-owner iterator object. |
Related Methods
This method returns a reference to the focus module for the specified focus.
Signature
ODFocusModule *GetFocusModule (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
Related Methods
This method indicates 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 nonexclusive. |
Exception Handling
kODErrFocusNotRegistered | The requested focus is not registered. |
Related Methods
This method indicates whether the specified focus is registered.
Signature
ODBoolean IsFocusRegistered (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 registered. |
kODFalse | The specified focus is not registered. |
Remarks
A focus is registered if it has a focus module.
Related Methods
This method adds the specified focus module for the specified focus.
Signature
void RegisterFocus (ODTypeToken focus, ODFocusModule *focusModule) |
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.
Exception Handling
kODErrFocusAlreadyRegistered | The requested focus is already registered. |
kODErrOutOfMemory | There is not enough memory to allocate the default focus module. |
Related Methods
This method is called by the current owner of the specified focus to relinquish ownership of it.
Signature
void RelinquishFocus (ODTypeToken focus, ODFrame *relinquishingFrame) |
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
If the focus is exclusive, it has no owner after this method executes successfully.
Exception Handling
kODErrFocusNotRegistered | The requested focus is not registered. |
Related Methods
This method is called by the current owner of the each focus in the specified focus set to relinquish ownership of it.
Signature
void RelinquishFocusSet (ODFocusSet *focusSet, ODFrame *relinquishingFrame) |
Parameters
Returns
None.
Exception Handling
kODErrFocusNotRegistered | One of the specified focuses is not registered. |
Related Methods
This method requests that the ownership of the specified focus be assigned to the specified frame.
Signature
ODBoolean RequestFocus (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 frame obtained the focus. |
kODFalse | The frame did not obtain the focus. |
Remarks
Your part calls this method to request a single focus for one of its frames; to request multiple focuses, your part calls the arbitrator's RequestFocusSet method. This return value indicates whether the specified frame obtained ownership of the specified focus.
If the specified focus is nonexclusive, the specified frame is granted ownership of the focus. If it is exclusive, the focus module calls the BeginRelinquishFocus method of the current owner's part to see if the current owner is willing to give it up.
If the request is granted, the new ownership relationship is stored in the relevant focus modules. If the request fails, the existing ownership relationships remain intact.
If the request is granted, the arbitrator contains a reference to the frame. Parts should relinquish the focus in the DisplayFrameClosed or DisplayFrameRemoved methods.
Exception Handling
kODErrFocusNotRegistered | The requested focus is not registered. |
Related Methods
This method requests that the ownership of each focus in the specified focus set be assigned to the specified frame.
Signature
ODBoolean RequestFocusSet (ODFocusSet *focusSet, ODFrame *requestingFrame) |
Parameters
Returns
kODTrue | The frame obtained the focus set. |
kODFalse | The frame did not obtain the focus set. |
Remarks
For the requested ownership to be granted, all existing owners of exclusive focuses within the specified set must be willing to relinquish these same focuses. If all of the focuses, exclusive and nonexclusive, are attainable, then the request is granted; however, even if one focus is unattainable, ownership of the focus set is not granted.
If the request is granted, the new ownership relationships are stored in the relevant focus modules. If the request fails, the existing ownership relationships remains intact.
If the request is granted, the arbitrator contains a reference to the frame. Parts should relinquish the focus in the DisplayFrameClosed or DisplayFrameRemoved methods.
Exception Handling
kODErrFocusNotRegistered | One of the requested focuses is not registered. |
Related Methods
This method directly transfers a focus from its current owner to another.
Signature
void TransferFocus (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
Your part calls this method, instead of methods that relinquish a focus, to restore ownership to a previous owner. For example, when a part requests the modal focus, as it does when displaying a modal dialog box, that part should save the previous owner of the modal focus and transfer ownership back to the previous owner when the dialog box is dismissed. This technique may be necessary if modal dialogs can be nested.
This method calls the new owner's FocusAcquired method if the new owner is not the transferring frame. If the previous owner is not the transferring frame, OpenDoc calls the previous owner's FocusLost method.
Related Methods
This method assigns the specified frame as the owner of each focus in the specified focus set.
Signature
void TransferFocusSet (ODFocusSet *focusSet, ODFrame *transferringFrame, ODFrame *newOwner) |
Parameters
Returns
None.
Remarks
This method calls the new owner's FocusAcquired method if the new owner is not the transferring frame. If the previous owner is not the transferring frame, OpenDoc calls the previous owner's FocusLost method.
Related Methods
This method removes the association between the specified focus and the focus module that manages it.
Signature
void UnregisterFocus (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
None.
Exception Handling
kODErrFocusNotRegistered | The requested focus is not registered. |
Related Methods