Class: TStandardEventReceiver

Declaration: Input.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MEventReceiver

Inherited By:

None.

Purpose:

Derived from MEventReceiver, which provides abstract protocol for dealing with messages from the Input system, this class builds on the MEventReceiver protocol and implements a strict standard behavior that is followed in response to Input system messages. This behavior fulfills the event delivery contracts that the Input system provides to objects like MEventTargets. TStandardEventReceiver is responsible for (1) recording that a new input device has been added to the system; (2) recording that an input device has been removed from the system; (3) returning the input device corresponding to a given TEventSenderSurrogate; (4) transmitting an event message from that deviceÕs driver to a given input device ; (5) recording that it has become the user focus and updating the internal states for its input devices; and (6) recording that it has ceased to become the user focus.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Classes will probably never derive from TStandardEventReceiver, though they could. Derived classes would give incremental behavior to the standard processing behavior that TStandardEventReceiver provides. More often, TStandardEventReceiver will be used concretely by application frameworks that need to provide standard event processing behavior.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStandardEventReceiver::TStandardEventReceiver

TStandardEventReceiver ()
TStandardEventReceiver (const TStandardEventReceiver & copy)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to copy an object.

Parameters:

Takes no parameters.
const TStandardEventReceiver & copy -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEventReceiver::~TStandardEventReceiver

virtual ~ TStandardEventReceiver ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEventReceiver::operator=

TStandardEventReceiver & operator =(const TStandardEventReceiver & assign)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TStandardEventReceiver & assign -The object to be copied.

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: TStandardEventReceiver::operator>>=

virtual TStream & operator >>=(TStream & writeTo) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & writeTo -The stream to which the object streams itself out.

Return Value:

Returns a reference to the stream to which the object streams itself out.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEventReceiver::operator<<=

virtual TStream & operator <<= (TStream & readFrom)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & readFrom -The stream from which the object streams itself in.

Return Value:

Returns a reference to the stream from which the object streams itself in.

Exceptions:

Throws a TInvalidVersionError if the version of the object on the stream is unknown to the version of the shared library that is installed.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEventReceiver::AdoptInputDevice

virtual void AdoptInputDevice (TInputDevice * device, const TEventSenderSurrogate & fromSurrogate)

Interface Category:

API.

Purpose:

Adopts the specified input device and associates it with the specified event sender surrogate. This action records that the input device has been added to the system. This function stores the input device in a collection.

Calling Context:

Called when an input device is added to the system.

Parameters:

TInputDevice * device -The input device to be adopted.
const TEventSenderSurrogate & fromSurrogate -The surrogate used to identify the adopted input device in this event receiver's task.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides the MEventReceiver function of the same name.

Member Function: TStandardEventReceiver::DeleteInputDevice

virtual void DeleteInputDevice (const TEventSenderSurrogate & fromSurrogate)

Interface Category:

API.

Purpose:

Deletes the input device associated with the specified event sender surrogate. This action records that the input device has been removed from the system. This function also removes the input device from a collection.

Calling Context:

Called when an input device is removed from the system.

Parameters:

const TEventSenderSurrogate & fromSurrogate -The surrogate associated with the input device that is to be deleted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides the MEventReceiver function of the same name.

Member Function: TStandardEventReceiver::UpdateInputDeviceStates

virtual void UpdateInputDeviceStates (TDictionaryOf < TEventSenderSurrogate, TRandomAccessStream >& deviceStates)

Interface Category:

API.

Purpose:

Updates the state of each input device that is associated with the event sender surrogates in the specified dictionary to the state represented by the specified random access stream.

Calling Context:

Call this function directly.

Parameters:

TDictionaryOf < TEventSenderSurrogate -The dictionary containing surrogates for all the input devices whose states are to be updated.
TRandomAccessStream >& deviceStates -The new states for the input devices.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides the MEventReceiver function of the same name.

Member Function: TStandardEventReceiver::BecomeUserFocus

virtual void BecomeUserFocus ()

Interface Category:

API.

Purpose:

Notifies this event receiver that it has become the user focus. TStandardEventReceiver's implementation of this function does nothing.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides the MEventReceiver function of the same name.

Member Function: TStandardEventReceiver::SurrenderUserFocus

virtual void SurrenderUserFocus ()

Interface Category:

API.

Purpose:

Notifies this event receiver that it is no longer the user focus. TStandardEventReceiver's implementation of this function does nothing.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides the MEventReceiver function of the same name.

Member Function: TStandardEventReceiver::GetInputDevice

virtual TInputDevice * GetInputDevice (const TEventSenderSurrogate & surrogate) const

Interface Category:

API.

Purpose:

Returns the input device associated with the specified event sender surrogate.

Calling Context:

Call this function directly.

Parameters:

const TEventSenderSurrogate & surrogate -The surrogate whose event sender will be retrieved.

Return Value:

Returns the input device associated with the specified event sender surrogate.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardEventReceiver::TransmitEventMessage

virtual void TransmitEventMessage (TRandomAccessStream & message, const TEventSenderSurrogate & fromSurrogate, const TEventSynchronizer & sync)

Interface Category:

API.

Purpose:

Send event to input device for discrimination and distribution.

Calling Context:

Called internally when a new event arrives.

Parameters:

TRandomAccessStream & message -Event information.
const TEventSenderSurrogate & fromSurrogate -Event sender.
const TEventSynchronizer & sync -Synchronization controller.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.