Class: TInputDevice

Declaration: Input.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TMouseInputDevice

Purpose:

A representative of a specific input device that lives in a task outside the device driverÕs task. Typically, it is an application task. Its purpose is twofold. First, classes deriving from TInputDevice are written by the input device writer. They execute within an applicationÕs task, thus allowing the input device to create events inside an application. This also provides a convenient context for an input device to store the state of the input device that stays in sync with the event stream. Second, TInputDevice gives the applicationÕs event handling objects an entity that represents the input device to the application. This allows the application to interact with the input device directly. Both applications and input device writers are clients of TInputDevice. Input device writers derive from TInputDevice to provide specific message-handling behavior, turning messages into specific events. Higher-level device frameworks can also create specific TInputDevice derived classes to complement their driver-side TEventSender-like classes. Applications do not derive from TInputDevice, but use the protocol of TInputDevices to attach interactors. TInputDevice is responsible for (1) turning messages from its driver into specific events; (2) storing the state of the input device as it sees changes to that state come through its event stream; (3) creating a representation of the state of the input device that can be read by another input device of the same type; (4) updating the state of the input device to be the state that exactly matches another input device of the same type; and (5) managing an interactor that can be bound to the input device.

Instantiation:

Allocate on the heap or the stack. Abstract class; do not instantiate.

Deriving Classes:

Derived classes should override SendEventFromMessage, UpdateInternalStateFromMessage, CreateInternalStateDelta, and UpdateInternalStateFromDelta.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TInputDevice::TInputDevice

TInputDevice ()
TInputDevice (const TInputDevice & copy)

Interface Category:

API.

Purpose:

Default constructor. This constructor initializes the new input device's bound interactor to NIL.
Copy constructor. This constructor does not clone the interactor of the copied object--interactors can only be bound to a single input device. The interactor for the new input device is initialized to NIL.

Calling Context:

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

Parameters:

Takes no parameters.
const TInputDevice & 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: TInputDevice::~TInputDevice

virtual ~ TInputDevice ()

Interface Category:

API.

Purpose:

Destructor. This function deletes this device's bound interactor.

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

TInputDevice & operator =(const TInputDevice & assign)

Interface Category:

API.

Purpose:

Assignment operator. This constructor does not clone the interactor of the copied object--interactors can only be bound to a single input device. The interactor for the new input device is initialized to NIL.

Calling Context:

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

Parameters:

const TInputDevice & 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: TInputDevice::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: TInputDevice::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: TInputDevice::SendEventFromMessage

virtual void SendEventFromMessage (TRandomAccessStream & message, TStandardEventReceiver & receiver, const TEventSynchronizer& sync)

Interface Category:

API.

Purpose:

Creates the appropriate event from the specified message and distributes it. Distribution is handled via whatever distribution policy is appropriate for that event. As an example, a mouse input device that might take the following steps to distribute an event: (1) create a MouseDown, MouseUp, or MouseMoved event, as appropriate, (2) attach the receiver to the event, (3) create an event distributor, and (4) call DistributeEvent on that distributor. TInputDevice's implementation of this function does nothing.

Calling Context:

Called from TransmitEventMessage in the event receiver.

Parameters:

TRandomAccessStream & message -The message from which the event is to be created.
TStandardEventReceiver & receiver -The receiver to which the event is to be distributed.
const TEventSynchronizer& sync -The event synchronizer for synchronizing events and improving performance.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Classes deriving from TInputDevice should override this function.

Member Function: TInputDevice::AfterEventHandled

void AfterEventHandled( const TEventSynchronizer& sync ) const;

Interface Category:

API.

Purpose:

Returns notification to the caller that the event has been handled, and facilitates the callerÕs process resumption.

Calling Context:

Called after SendEventFromMessage in the event receiver.

Parameters:

const TEventSynchronizer& sync -The event synchronizer for synchronizing events and improving performance.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInputDevice::UpdateInternalStateFromMessage

virtual void UpdateInternalStateFromMessage (TRandomAccessStream & message)

Interface Category:

API.

Purpose:

Updates the state of this input device according to the specified message. TInputDevice's implementation of this function does nothing.

Calling Context:

Called from the Input system framework.

Parameters:

TRandomAccessStream & message -The message from which the new state is to be determined.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Classes deriving from TInputDevice should override this function.

Member Function: TInputDevice::CreateInternalStateDelta

virtual void CreateInternalStateDelta (TRandomAccessStream & putDeltaHere) const

Interface Category:

API.

Purpose:

Creates a representation of this input device's state. This function along with UpdateInternalStateFromDelta allows the Input system to synchronize two different TInputDevice objects to have the same state. TInputDevice's implementation of this function does nothing.

Calling Context:

Called from the Input system framework.

Parameters:

TRandomAccessStream & putDeltaHere -The representation of this input device's state as returned by this function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Classes deriving from TInputDevice should override this function.

Member Function: TInputDevice::UpdateInternalStateFromDelta

virtual void UpdateInternalStateFromDelta (TRandomAccessStream & delta)

Interface Category:

API.

Purpose:

Updates this input device's state to be the same as that represented by the specified delta. This function along with CreateInternalStateDelta allows the Input system to synchronize two different TInputDevice objects to have the same state. TInputDevice's implementation of this function does nothing.

Calling Context:

Called from within the Input system framework.

Parameters:

TRandomAccessStream & delta -The delta from which this input device sets its state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Classes deriving from TInputDevice should override this function.

Member Function: TInputDevice::AdoptInteractor

virtual void AdoptInteractor (TInteractor * interactor)

Interface Category:

API.

Purpose:

Adopts the specified interactor. This function deletes the previously adopted interactor and activates the newly adopted one.

Calling Context:

Calling this function directly is not intended; use TEvent::AdoptInteractor instead.

Parameters:

TInteractor * interactor -The interactor to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInputDevice::GetInteractor

TInteractor * GetInteractor () const

Interface Category:

API.

Purpose:

Returns the current interactor for this input device. It's possible for this function to return NIL.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the current interactor for this input device.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInputDevice::OrphanInteractor

virtual TInteractor * OrphanInteractor ()

Interface Category:

API.

Purpose:

Orphans the current interactor. This function deactivates the orphaned interactor. The caller is responsible for deleting the orphaned interactor.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the orphaned interactor.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInputDevice::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns the hash value that uniquely identifies this object within its type. Hash values are used to build dictionaries of objects.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value that uniquely identifies this object within its type.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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