Class: MEventDistributor

Declaration: Input.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TSimpleEventDistributor

Purpose:

MEventDistributors are objects that can take an event and match it with the event target that should handle the event. MEventDistributor is essentially a functor for protocol that provides this matching and distribution ability. Framework developers provide MEventDistributor derived classes to encapsulate a given style of event distribution. For example, the View system can provide a ViewEventDistributor that knows how to distribute an event through the view hierarchy given a TGPoint to guide the distribution algorithm. TInputDevices use these derived classes of MEventDistributor to send their events. Thus, a mouse input device might use a ViewEventDistributor object to send its mouse events to the proper view. MEventDistributor is responsible for distributing an event to the appropriate event target. MEventDistributor uses events and input devices. The base MEventDistributor has only basic distribution semantics; that is, it tries to send the event to an interactor bound to the input device. Classes deriving from MEventDistributor are able to provide additional semantics by overriding the virtual function HandleDistributeEvent. The HandleDistributeEvent virtual function is called from the non-virtual DistributeEvent function, which in turn is called by clients. MEventDistributor objects are not generic engines which take in all the data needed for event distribution at one time. Instead, a given MEventDistributor object can distribute any event for a given set of parameters.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

Classes deriving from MEventDistributor must override the pure virtual function HandleDistributeEvent.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MEventDistributor::MEventDistributor

MEventDistributor ()
MEventDistributor (const MEventDistributor & copy)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

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

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

MEventDistributor is an abstract base class. Do not instantiate an MEventDistributor, but rather one of its derived classes.

Member Function: MEventDistributor::~MEventDistributor

virtual ~ MEventDistributor ()

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

MEventDistributor & operator =(const MEventDistributor & assign)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const MEventDistributor & 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: MEventDistributor::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: MEventDistributor::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: MEventDistributor::DistributeEvent

bool DistributeEvent (TEvent & theEvent)

Interface Category:

API.

Purpose:

Distributes the specified event to the appropriate target. This function first attempts to distribute the event to the event filters registered with the event's event receiver. If the event filters don't handle the event, this function then attempts to distribute the event to the interactor bound to the event's input device. If the interactor does not handle the event, this function finally calls HandleDistributeEvent, which gives derived classes an opportunity to implement their own distribution policy.

Calling Context:

Call this function directly.

Parameters:

TEvent & theEvent -The event to be distributed.

Return Value:

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

Exceptions:

An assertion is raised if the event's input device, or the event's event receiver, is NIL. Also, an assertion is raised if the interactor bound to the input device is changed during the execution of this function.

Concurrency:

Not multithread safe.

Other Considerations:

You shouldn't override this function; override HandleDistributeEvent instead.

Member Function: MEventDistributor::HandleDistributeEvent

virtual bool HandleDistributeEvent (TEvent & theEvent)

Interface Category:

API.

Purpose:

Handles event distribution if DistributeEvent did not successfully distribute the specified event. This function is provided so that classes deriving from MEventDistributor can add value by defining their own distribution behavior. For example, a derived class which wanted to distribute events using the View system as a targeting mechanism would implement that policy in this function.

Calling Context:

Called from DistributeEvent after attempting and failing to distribute the event to various objects.

Parameters:

TEvent & theEvent -The event to be distributed.

Return Value:

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

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 MEventDistributor.