Class: TInteractor

Declaration: Input.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MEventTarget

Inherited By:

TDragAndDropInteractor TToolInteractor TFrameEmbedderDragInteractor TFrameInteractor TSelectTextInteractor TTypingInteractor

Purpose:

TInteractors provide developers with a methodology for breaking down complex user gestures into components that can be easily parsed. These structures are represented as sets of objects which can be driven by an event stream. Many user gestures can be broken down into multiple interactions. TInteractor represents a single state within the state machine model of interactions; it is the fundamental unit of composition of a user gesture. As an example, consider a complex user gesture that breaks down into multiple interactions. In something resembling the Macintosh Finder, the user clicks on an icon representing a file. This click selects the file. Holding down the mouse button, the user then moves the mouse into the auto scroll area of the folderÕs window, causing the window to scroll. Still holding down the mouse button, the user then moves the mouse back into the window and releases the mouse, thus completing the gesture. The end result is a selected file that has been moved within the folderÕs window. In this example, this user gesture is comprised of three interactions: select, move, and auto scroll. Developers that needs to parse a stream of events in order to determine a user's intention derive classes from TInteractor to implement specific interactions. Higher-level systems are expected to provide a set of interactors for the various elements of their user interface. For example, a GUI tool kit will likely provide interactors that implement the various aspects of a direct manipulation interface. Developers would then use those interactors to construct complex direct manipulation interfaces. Developers who need to compose a user gesture use TInteractors or classes deriving from TInteractor. For example, when a GUI application receives a mouse-down event, that application developer creates an object that represents all possible outcomes of a gesture initiated by a mouse-down event. That object is an interactor, and will likely be composed of several other interactors, each representing a part of the overall interactor. TInteractor has protocol for (1) dispatching a given event to itself and telling the caller whether the event was handled or not; (2) labeling itself as being completed; (3) querying the completion state of the object; (4) being activated and deactivated; and (5) querying the activation state of the object. TInteractor inherits from MEventTarget, from which it gets its event dispatching behavior. Although an interactor can set itself to be done, the interactor does not terminate the sequence of the user gesture. However, an interactor in a done state rejects any and all events that it is asked to distribute. It is up to some object which holds the interactor to take note of the completion of the interactor and end the gesture, if appropriate. In the case of the root interactor, this detection and cleanup is done by the input device to which the interactor is bound. Similarly, the activation and deactivation of an interactor is the responsibility of the object that holds it. The object holding an interactor must activate it some time before the interactor is sent its first event, as inactive interactors reject all events. Similarly, the object holding an interactor must deactivate it when the interactor is no longer a part of the gesture. This is provided as a convenience, both to the interactor and its container, because it allows the interactor to effectively turn itself off when it is clear that the user is not following the gesture represented by the interactor.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Classes deriving from TInteractor should override HandleActivate and HandleDeactivate to implement a specific activation policy.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TInteractor::TInteractor

TInteractor ()
TInteractor (const TInteractor & copy)

Interface Category:

API.

Purpose:

Default constructor. This constructor initializes the interactor to be inactive and not done.
Copy constructor. This constructor initializes the interactor to be inactive and not done.

Calling Context:

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

Parameters:

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

virtual ~ TInteractor ()

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

TInteractor & operator =(const TInteractor & assign)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TInteractor & 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: TInteractor::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: TInteractor::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: TInteractor::SetDone

virtual void SetDone (bool isDone =true)

Interface Category:

API.

Purpose:

Sets this interactor's done state according to the specified Boolean flag. An interactor sets itself to done when it has completed handling the event. An interactor set to done rejects any and all events that it is asked to distribute.

Calling Context:

Called this function with care. In general, it should only be called by classes which inherit from TInteractor. The significance of this is that the interactor object itself knows when it is done. If SetDone is called at a time at which the interactor is not expecting it, bad things could happen.

Parameters:

bool isDone =true -The Boolean flag indicating whether or not this interactor is done.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInteractor::IsDone

bool IsDone () const

Interface Category:

API.

Purpose:

Determines whether this interactor is done. An interactor that is done rejects any and all events that it is asked to distribute.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this interactor is done; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInteractor::Activate

void Activate ()

Interface Category:

API.

Purpose:

Activates this interactor. It is the responsibility of the object containing this interactor to activate and deactivate this interactor at the appropriate time. This function calls HandleActivate. Classes deriving from TInteractor should override HandleActivate, rather than overriding this function, to provide a specific activation policy.

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:

None.

Member Function: TInteractor::Deactivate

void Deactivate ()

Interface Category:

API.

Purpose:

Deactivates this interactor. Inactive interactors reject all events. It is the responsibility of the object containing this interactor to activate and deactivate this interactor at the appropriate time. This function calls HandleDeactivate. Classes deriving from TInteractor should override HandleDeactivate, rather than overriding this function, to provide a specific activation policy.

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:

None.

Member Function: TInteractor::IsActive

bool IsActive () const

Interface Category:

API.

Purpose:

Determines whether this interactor is active.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this interactor is active; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInteractor::DispatchEvent

virtual bool DispatchEvent (TEvent & theEvent)

Interface Category:

API.

Purpose:

Dispatches the specified event to itself and tells the caller whether the event was handled.

Calling Context:

Call this function directly.

Parameters:

TEvent & theEvent -The event to be dispatched to this interactor.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TInteractor::HandleActivate

virtual void HandleActivate ()

Interface Category:

API.

Purpose:

Handles activation of this interactor. This function provides derived classes an opportunity to implement a specific activation policy without overriding Activate. TInteractor's implementation of this function does nothing.

Calling Context:

Called from Activate.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TInteractor::HandleDeactivate

virtual void HandleDeactivate ()

Interface Category:

API.

Purpose:

Handles deactivation of this interactor. This function provides derived classes an opportunity to implement a specific activation policy without overriding Deactivate. TInteractor's implementation of this function does nothing.

Calling Context:

Called from Deactivate.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

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