Class: TEventReceiverHandle

Declaration: Input.h

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.

Member Function: TEventReceiverHandle::TEventReceiverHandle

  1. TEventReceiverHandle ()
  2. TEventReceiverHandle (MEventReceiver * adoptProcessor, bool seizeFocus =true)
  3. TEventReceiverHandle (const TEventReceiverHandle & copy)

Interface Category:

API.

Purpose:

  1. Default constructor.
  2. 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.
  3. Copy constructor.

Calling Context:

  1. Called by the stream-in operators.
  2. Call this function directly.
  3. Called to copy an object.

Parameters:

Return Value:

None

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverHandle::~TEventReceiverHandle

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.

Member Function: TEventReceiverHandle::operator=

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.

Member Function: TEventReceiverHandle::operator==

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.

Member Function: TEventReceiverHandle::operator!=

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.