![](../../Home/Icons/Home.gif)
![](../icons/UpCNM.gif)
![](../icons/CNMContext.gif)
![](../../Home/Icons/Search.gif)
Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
None.
Inherited By:
None.
Purpose:
An object that forms an applicationŐs communication link from the Input system. It creates a thread in which a given event receiver executes.
TEventReceiverHandle is used by higher-level frameworks that need to provide a communication link from the Input system. These higher -level frameworks would likely be systems that provide application frameworks.
TEventReceiverHandle also guarantees to the client that the event receiver is running: the handle symmetrically allows clients to start event receivers and shut them down cleanly. Event receivers are started by constructing a TEventReceiverHandle with the event receiver object. As long as the client needs the event receiver to run the client must keep the TEventReceiverHandle. The client deletes the handle when it no longer needs the event receiver. TEventReceiverHandles can be copied within a task any number of times. Each copy provides a new handle onto the same event receiver. The event receiver is shut down when all handles to it are deleted.
Because TEventReceiverHandle is the communication link, it is also the source of the applicationŐs identity from the point of view of the Input system. This identity is carried through a TEventReceiverSurrogate, which is constructed from a TEventReceiverHandle. That is, if you want to specify an application to the Input system, you do so through a TEventReceiverSurrogate.
TEventReceiverHandle is responsible for (1) adopting an event receiver to handle messages from the Input system; and (2) shutting down the event receiver when the last TEventReceiverHandle to its event receiver is deleted.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
It is not likely that classes will ever derive from MEventReceiverHandle. All interesting behavior can be obtained by deriving from MEventReceiver and creating a TEventReceiverHandle for that event receiver.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- TEventReceiverHandle ()
- TEventReceiverHandle (MEventReceiver * adoptProcessor, bool seizeFocus =true)
- TEventReceiverHandle (const TEventReceiverHandle & copy)
Interface Category:
API.
Purpose:
- Default constructor.
- Creates a new event receiver handle for the specified event receiver. The new handle can become the user focus according to the specified Boolean flag. This constructor starts a thread for the event receiver.
- Copy constructor.
Calling Context:
- Called by the stream-in operators.
- Call this function directly.
- Called to copy an object.
Parameters:
- Takes no parameters.
- MEventReceiver * adoptProcessor -The event receiver for which to create the handle.
- bool seizeFocus =true -The flag indicating whether or not to become the user focus.
- const TEventReceiverHandle & copy -The object to be copied.
Return Value:
None
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ TEventReceiverHandle ()
Interface Category:
API.
Purpose:
Destructor. If this is the last remaining handle to the event receiver, this function shuts down the thread for the event receiver.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
TEventReceiverHandle & operator =(const TEventReceiverHandle & assign)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
Return Value:
Returns a const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
bool operator ==(const TEventReceiverHandle & other)
Interface Category:
API.
Purpose:
Determines whether this event receiver handle is equal to the one specified. Event receiver handles are equal if they are handles for the same event receiver.
Calling Context:
Call this function by using the operator in an expression.
Parameters:
Return Value:
Returns true if the two objects are equal; false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
bool operator != (const TEventReceiverHandle & other)
Interface Category:
API.
Purpose:
Determines whether this event receiver handle is not equal to the one specified. Event receiver handles are not equal if they are handles for different event receivers.
Calling Context:
Call this function by using the operator in an expression.
Parameters:
Return Value:
Returns true if the two objects are not equal; otherwise, returns false.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.