Class: MEventReceiver

Declaration: Input.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TStandardEventReceiver

Purpose:

An abstract base class that provides protocol for handling messages from the Input system. Any client that needs to handle messages from the Input system implements derived classes of MEventReceiver. Clients thus become application frameworks by definition--programs that receive and process events are applications. MEventReceiver 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) transmitting an event message to a given input device from that deviceÕs driver; (4) recording that the event receiver has become the user focus and updating its input devices internal states; and (5) recording that it has ceased being the user focus.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

Classes deriving from MEventReceiver must override all of the important member functions listed above--they are all pure virtual functions.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MEventReceiver::MEventReceiver

MEventReceiver ()
MEventReceiver (const MEventReceiver & copy)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and derived classes' constructors.
Called to copy an object.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

MEventReceiver is an abstract base class; do not instantiate.

Member Function: MEventReceiver::~MEventReceiver

virtual ~ MEventReceiver ()

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

MEventReceiver & operator =(const MEventReceiver & assign)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const MEventReceiver & 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: MEventReceiver::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 the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MEventReceiver::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 the object streams itself in from.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MEventReceiver::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 records that the input device has been added to the system.

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 is a pure virtual function and must be overridden by classes deriving from MEventReceiver.

Member Function: MEventReceiver::DeleteInputDevice

virtual void DeleteInputDevice (const TEventSenderSurrogate & fromSurrogate)

Interface Category:

API.

Purpose:

Deletes the input device associated with the specified event sender surrogate. This records that the input device has been removed from the system.

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 is a pure virtual function and must be overridden by classes deriving from MEventReceiver.

Member Function: MEventReceiver::TransmitEventMessage

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

Interface Category:

API.

Purpose:

Transmits the specified event message to the input device associated with the specified surrogate.

Calling Context:

Call this function directly.

Parameters:

TRandomAccessStream & message -The message to be sent.
const TEventSenderSurrogate & fromSurrogate -The surrogate for the input device to which to send the message.
const TEventSynchronizer & sync -The event synchronizer that permits the caller to block for only as long as required to send the message.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from MEventReceiver.

Member Function: MEventReceiver::UpdateInputDeviceStates

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

Interface Category:

API.

Purpose:

Updates the state of each input device associated with the event sender surrogates in the specified dictionary to that 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 is a pure virtual function and must be overridden by classes deriving from MEventReceiver.

Member Function: MEventReceiver::BecomeUserFocus

virtual void BecomeUserFocus ()

Interface Category:

API.

Purpose:

Notifies this event receiver that it has become the user focus. This function is called after the event receiver has become the user focus.

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 is a pure virtual function and must be overridden by classes deriving from MEventReceiver.

Member Function: MEventReceiver::SurrenderUserFocus

virtual void SurrenderUserFocus ()

Interface Category:

API.

Purpose:

Notifies this event receiver that it is no longer the user focus. This function is called after the event receiver has relinquished the user focus.

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 is a pure virtual function and must be overridden by classes deriving from MEventReceiver.

Click the icon to mail questions or corrections about this material to Taligent personnel.