Programming Reference: ODFocusModule

# Programming Reference

## ODFocusModule

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.

somInit somUninit

Methods

The methods defined by the ODFocusModule class include:

- AbortRelinquishFocus
- AcquireFocusOwner
- BeginRelinquishFocus
- CommitRelinquishFocus
- CreateOwnerIterator
- InitFocusModule
- IsFocusExclusive
- SetFocusOwnership
- TransferFocusOwnership
- UnsetFocusOwnership

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

### AbortRelinquishFocus

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

focus (ODTypeToken) - input

  A tokenized string representing the focus type which was 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.

requestingFrame (ODFrame *) - input

  A reference to a frame that originally requested the focus.

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

- ODFocusModule::BeginRelinquishFocus
- ODFocusModule::CommitRelinquishFocus
- ODPart::AbortRelinquishFocus
- ODPart::BeginRelinquishFocus
- ODSession::Tokenize

### AcquireFocusOwner

This method should return 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 whose owner is desired.

  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

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

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

- ODArbitrator::AcquireFocusOwner
- ODSession::Tokenize

### BeginRelinquishFocus

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

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

requestingFrame (ODFrame *) - input

  A reference to the frame requesting ownership of the focus.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the current owner of the specified exclusive focus is willing to give up ownership of the focus.

  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

- ODFocusModule::AbortRelinquishFocus
- ODFocusModule::CommitRelinquishFocus
- ODPart::BeginRelinquishFocus
- ODSession::Tokenize

### CommitRelinquishFocus

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

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.

requestingFrame (ODFrame *) - input

  A reference to a frame that requested the focus.

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

- ODFocusModule::AbortRelinquishFocus
- ODFocusModule::BeginRelinquishFocus
- ODPart::CommitRelinquishFocus
- ODSession::Tokenize

### CreateOwnerIterator

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

focus (ODTypeToken) - input

  A tokenized string representing the focus type whose frames you want to enumerate.

  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 (ODFocusOwnerIterator *) - returns

  A reference to a new focus-owner iterator object or kODNULL if the focus is exclusive.

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

- ODSession::Tokenize

### InitFocusModule

This method initializes this focus-module object.

Signature

    void InitFocusModule (ODSession *session)

Parameters

session (ODSession *) - input

  A reference to the current session object.

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.

### IsFocusExclusive

This method should indicate 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 specified focus is exclusive.

  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

- ODSession::Tokenize

### SetFocusOwnership

This method should record the specified frame as the owner of the specified focus.

Signature

    void SetFocusOwnership (ODTypeToken focus,
                            ODFrame *frame)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus type whose owner is to be assigned.

  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.

frame (ODFrame *) - input

  A reference to a frame that is to own the focus.

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

- ODSession::Tokenize

### TransferFocusOwnership

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

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 relinquishing ownership of the focus; it does not have to be the current owner of the focus.

newOwner (ODFrame *) - input

  A reference to a frame obtaining ownership of the focus.

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

- ODSession::Tokenize

### UnsetFocusOwnership

This method should remove the specified frame as the owner of the specified focus.

Signature

    void UnsetFocusOwnership (ODTypeToken focus,
                              ODFrame *frame)

Parameters

focus (ODTypeToken) - input

  A tokenized string representing the focus whose owner is 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.

frame (ODFrame *) - input

  A reference to the current owner of the focus.

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

- ODSession::Tokenize

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