Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
VEventHandlerCast
Inherited By:
TInteractor
TTool
TCursorKeyFilter
TInputMethodKeyboardBehavior
TToolNegotiator
TView
Purpose:
MEventTargets are application objects that can process events. They are functors for the protocol that starts the dispatching dialogue between a MEventTarget and the event being dispatched.
Although MEventTarget is an application domain object, applications rarely or never inherit directly from MEventTarget. Instead they inherit from MEventTarget derived classes that add a particular targeting scheme to the definition of the class. The direct clients of MEventTarget are developers creating specific targeting schemes. Application developers generally override MEventTarget functions to provide delegation semantics, such as telling another object to handle events for the MEventTarget.
MEventTargets are objects that can process events. An MEventTarget can contain an ordered collection of other MEventTargets. Each MEventTarget has a protocol that starts the dispatching dialogue between an MEventTarget event target and the MEvent event being dispatched. When events are dispatched, they are first processed by the collection of MEventTarget behaviors and then they are processed by the root MEventTarget.
MEventTarget has three main responsibilities. It is responsible for managing a collection of MEventTarget behaviors. It is also responsible for dispatching a given MEvent event object to the its collection of behavior event targets and itself. Lastly, MEventTarget tells the caller whether or not the MEvent event was handled.
MEventTarget uses only abstract events.
Concrete event targets can commonly inherit from MEventTarget twice, but this will not cause problems to the client. By definition, MEventTarget has no state, so duplication of data in an object is not a problem.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
Classes deriving from MEventTarget should override DispatchEvent to implement specific targeting schemes. In addition, clients that want to change the order of insertion in the behavior collection can implement the AdoptBehavior member function in a derived class.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- MEventTarget ()
- MEventTarget (const MEventTarget & 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 MEventTarget & copy -The object to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ MEventTarget ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MEventTarget::operator=
MEventTarget & operator =(const MEventTarget & assign)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
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: MEventTarget::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:
Member Function: MEventTarget::operator<<=
virtual TStream & operator <<= (TStream & readFrom)
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: MEventTarget::DispatchEvent
virtual bool DispatchEvent (TEvent & theEvent)
Interface Category:
API.
Purpose:
Dispatches the specified event to this event target itself. The default implementation dispatches the event to its collection of behaviors, in the order in which they are kept, and then dispatches the event to itself. The dispatching stops when the event is handled by a behavior in the collection sequence.
Calling Context:
Call this function directly.
Parameters:
- TEvent & theEvent -The event to be dispatched.
Return Value:
Returns true if the dispatched event was handled; false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MEventTarget::AdoptLastBehavior
void AdoptLastBehavior (MEventTarget * aBehavior)
Interface Category:
API.
Purpose:
Adds the specified behavior to the end of the collection of behaviors.
Calling Context:
Call this function directly.
Parameters:
- MEventTarget * aBehavior -The behavior that is added to the end of this EventTargetŐs collection of behaviors.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MEventTarget::AdoptFirstBehavior
void AdoptFirstBehavior (MEventTarget * aBehavior)
Interface Category:
API.
Purpose:
Adds the specified behavior to the start of the collection of behaviors.
Calling Context:
Call this function directly.
Parameters:
- MEventTarget * aBehavior -The behavior that is added to the start of this EventTargetŐs collection of behaviors.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MEventTarget::OrphanBehavior
virtual MEventTarget * OrphanBehavior (MEventTarget * aBehavior)
Interface Category:
API.
Purpose:
Removes the behavior from the collection of behaviors for the EventTarget. This function does not deallocate storage that had been allocated for the behavior.
Calling Context:
Call this function directly.
Parameters:
- MEventTarget * aBehavior -The behavior that should be removed from the EventTargetŐs collection of behaviors.
Return Value:
Returns NIL if the given behavior is not found in the collection of behaviors; otherwise, returns the pointer to the behavior.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Storage that had been allocated for this behavior is not deallocated when this function removes the behavior from the collection. You should deallocate storage separately.
Member Function: MEventTarget::AdoptBehavior
virtual void AdoptBehavior (MEventTarget * aBehavior)
Interface Category:
API.
Purpose:
Adds the given behavior to the start of the collection of behaviors for the EventTarget. The EventTarget adopts the behavior when it is added to the collection. The EventTarget keeps this adopted behavior until the behavior is removed with OrphanBehavior or until the EventTarget is destroyed.
Calling Context:
Call this function directly.
Parameters:
- MEventTarget * aBehavior -The behavior that is added to the collection for the EventTarget.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Clients that wish to change the default order of insertion of behaviors into the collection should derive a class for this function. After adding a behavior, it is possible for a client to keep the aliased pointer to that behavior for later removal purposes.
Member Function: MEventTarget::DeregisterEventFilter
virtual void DeregisterEventFilter (TStandardEventReceiver & receiver)
Interface Category:
API.
Purpose:
Remove self from list of filters.
Calling Context:
Called when client no longer wants to filter events.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MEventTarget::RegisterEventFilter
virtual void RegisterEventFilter (TStandardEventReceiver & receiver)
Interface Category:
API.
Purpose:
Add self to list of event filters.
Calling Context:
Called when installing a new filter.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MEventTarget::DeregisterSimpleTarget
virtual void DeregisterSimpleTarget (TStandardEventReceiver & receiver)
Interface Category:
API.
Purpose:
Remove self from list of simple targets.
Calling Context:
Called when the client wishes the MEventTarget to stop receiving events.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MEventTarget::RegisterSimpleTarget
virtual void RegisterSimpleTarget (TStandardEventReceiver & receiver)
Interface Category:
API.
Purpose:
Add self from list of simple targets.
Calling Context:
Called when the client wishes the MEventTarget to start receiving events.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Class: MEventTarget::TBehaviorsIterator
Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
VEventHandlerCast
Inherited By:
TInteractor
TTool
TCursorKeyFilter
TInputMethodKeyboardBehavior
TToolNegotiator
TView
Purpose:
A protected class that provides an iterator over the behavior collection for MEventTarget. Classes deriving from TBehaviorsIterator can use this to customize the dispatching algorithm. This class is monomorphic. It provides a similar interface as a sequence iterator. This design, which has been chosen instead of a member function returning a TSequenceOfIterator pointer, provides a saving of one heap event for a deriving class.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
Deriving classes use this to customize the dispatching algorithm.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
Other Considerations:
None.
Member Function: TBehaviorsIterator::TBehaviorsIterator
TBehaviorsIterator (const MEventTarget & aTarget)
Interface Category:
API.
Purpose:
Default constructor.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TBehaviorsIterator::~TBehaviorsIterator
virtual ~ TBehaviorsIterator ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TBehaviorsIterator::First
virtual MEventTarget * First ()
Interface Category:
API.
Purpose:
Returns a reference to the first behavior in the behavior collection.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the MEventTarget object that is first in the behavior collection.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TBehaviorsIterator::Last
virtual MEventTarget * Last ()
Interface Category:
API.
Purpose:
Returns a reference to the last behavior in the behavior collection.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the MEventTarget object that is last in the behavior collection.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TBehaviorsIterator::Next
virtual MEventTarget * Next ()
Interface Category:
API.
Purpose:
Returns a reference to the next behavior in the behavior collection.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the next MEventTarget object in the behavior collection.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TBehaviorsIterator::Previous
virtual MEventTarget * Previous ()
Interface Category:
API.
Purpose:
Returns a reference to the previous behavior in the behavior collection.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the previous MEventTarget object in the behavior collection.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TBehaviorsIterator::Remove
virtual void Remove ()
Interface Category:
API.
Purpose:
Removes the current referenced behavior from the behavior collection.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
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.
Copyright©1995 Taligent,Inc. All rights reserved.