Programming Reference: ODArbitrator

# Programming Reference

## ODArbitrator

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:

- AcquireFocusOwner
- CreateFocusSet
- CreateOwnerIterator
- GetFocusModule
- IsFocusExclusive
- IsFocusRegistered
- RegisterFocus
- RelinquishFocus
- RelinquishFocusSet
- RequestFocus
- RequestFocusSet
- TransferFocus
- TransferFocusSet
- UnregisterFocus

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

### AcquireFocusOwner

This method returns a reference to the frame that owns the specified exclusive focus.

Signature

    ODFrame *AcquireFocusOwner (ODTypeToken focus)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be acquired.

  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

rv (ODFrame *) - returns

  A reference to the frame that owns the specified exclusive focus or kODNULL if the focus is not owned by any frame.

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

- ODFocusModule::AcquireFocusOwner
- ODSession::Tokenize

### CreateFocusSet

This method creates and initializes a focus set.

Signature

    ODFocusSet *CreateFocusSet ()

Parameters

None.

Returns

rv (ODFocusSet *) - returns

  A reference to a newly created focus set.

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

- ODArbitrator::RelinquishFocusSet

### CreateOwnerIterator

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

focus (ODTypeToken) - input

  A tokenized string representing the focus type whose owners are to be accessed.

  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

rv (ODFocusOwnerIterator *) - returns

  A reference to a newly created focus-owner iterator or kODNULL if the specified focus is exclusive.

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

- ODArbitrator::AcquireFocusOwner
- ODSession::Tokenize

### GetFocusModule

This method returns a reference to the focus module for the specified focus.

Signature

    ODFocusModule *GetFocusModule (ODTypeToken focus)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be acquired.

  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

rv (ODFocusModule *) - returns

  A reference to a focus module for the specified focus.

Related Methods

- ODSession::Tokenize

### IsFocusExclusive

This method indicates whether the specified focus is exclusive.

Signature

    ODBoolean IsFocusExclusive (ODTypeToken focus)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be tested.

  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

rv (ODBoolean) - returns

  A flag indicating whether the specified focus is exclusive.

  kODTrue | The specified focus is exclusive.
  kODFalse | The specified focus is nonexclusive.

Exception Handling

kODErrFocusNotRegistered | The requested focus is not registered.

Related Methods

- ODSession::Tokenize

### IsFocusRegistered

This method indicates whether the specified focus is registered.

Signature

    ODBoolean IsFocusRegistered (ODTypeToken focus)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be tested.

  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

rv (ODBoolean) - returns

  A flag indicating whether the specified focus is registered.

  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

- ODSession::Tokenize

### RegisterFocus

This method adds the specified focus module for the specified focus.

Signature

    void RegisterFocus (ODTypeToken focus,
                        ODFocusModule *focusModule)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be assigned to the specified focus module.

  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 the focus module that is to manage the specified focus or kODNULL to create a standard exclusive focus module.

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

- ODSession::Tokenize

### RelinquishFocus

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

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be relinquished.

  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.

relinquishingFrame (ODFrame *) - input

  A reference to a frame relinquishing ownership of the focus.

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

- ODArbitrator::RelinquishFocusSet
- ODSession::Tokenize

### RelinquishFocusSet

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

focusSet (ODFocusSet *) - input

  A reference to a focus set containing the focuses to be relinquished.

relinquishingFrame (ODFrame *) - input

  A reference to the frame relinquishing ownership of each focus in the specified focus set.

Returns

None.

Exception Handling

kODErrFocusNotRegistered | One of the specified focuses is not registered.

Related Methods

- ODArbitrator::RelinquishFocus

### RequestFocus

This method requests that the ownership of the specified focus be assigned to the specified frame.

Signature

    ODBoolean RequestFocus (ODTypeToken focus,
                            ODFrame *requestingFrame)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type whose ownership is being requested.

  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.

requestingFrame (ODFrame *) - input

  A reference to the frame requesting the focus.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the frame obtained the focus.

  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

- ODArbitrator::RequestFocusSet
- ODPart::BeginRelinquishFocus
- ODSession::Tokenize

### RequestFocusSet

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

focusSet (ODFocusSet *) - input

  A reference to a focus set being requested.

requestingFrame (ODFrame *) - input

  A reference to a frame requesting the focus.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the frame obtained the focus set.

  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

- ODArbitrator::RequestFocus

### TransferFocus

This method directly transfers a focus from its current owner to another.

Signature

    void TransferFocus (ODTypeToken focus,
                        ODFrame *transferringFrame,
                        ODFrame *newOwner)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be transferred.

  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.

transferringFrame (ODFrame *) - input

  A reference to a frame transferring ownership of the focus. This frame does not need to be the current owner.

newOwner (ODFrame *) - input

  A reference to a frame that is to be the new focus owner.

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

- ODArbitrator::TransferFocusSet
- ODPart::FocusAcquired
- ODPart::FocusLost
- ODSession::Tokenize

### TransferFocusSet

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

focusSet (ODFocusSet *) - input

  A reference to a focus set to be transferred.

transferringFrame (ODFrame *) - input

  A reference to a frame transferring ownership of the focus set.

newOwner (ODFrame *) - input

  A reference to a frame that is to be the new focus set owner.

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

- ODArbitrator::TransferFocus
- ODPart::FocusAcquired
- ODPart::FocusLost

### UnregisterFocus

This method removes the association between the specified focus and the focus module that manages it.

Signature

    void UnregisterFocus (ODTypeToken focus)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type to be removed.

  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

- ODSession::Tokenize

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