Class: MMouseEventHandler

Declaration: MouseInput.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

VEventHandlerCast

Inherited By:

TPrimitiveFrameView TSelectTextInteractor TToolNegotiator TCanvasInteractor TCursorKeyFilter TDelegatingMouseTool TFrameEmbedderDragInteractor TFrameInteractor TGUIEmbedderModelView THighlightTextToolInteractor TMouseDragAndDropInteractor TSimpleMouseTool TSimpleTextToolInteractor TStandardWindowBorder TBooleanControl TMediaView TMenu TMomentaryControl TSliderControl TSpinListControl TTableView TTextControl TTextView

Purpose:

A class that is used as a building block for handling mouse events. MouseEventHandler is a mixin class which provides protocol for handling each of the mouse events developers might want to handle. While MMouseEventHandler provides protocol for handling mouse events, the preferred method is for developers to use MEventTarget(Behaviors). Derive classes from this class to receive mouse events. If you want to handle all the button events, then override MouseButtonUp and MouseButtonDown functions. If you override MouseUp and MouseDown functions, then you will get called only if the button number is one. (Mouse button numbering starts with 1, not 0.). Support for MouseUp and MouseDown functions is only provided for backward compatibility. In any case, do not override both MouseUp/Down and MouseButtonUp/Down function pairs.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

MMouseEventHandler is a mixin class--it cannot be instantiated and must be derived from.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MMouseEventHandler::MMouseEventHandler

MMouseEventHandler ()
MMouseEventHandler (const TViewHandle & coordinateView)
MMouseEventHandler (const MMouseEventHandler & copy)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new mouse event handler with the specified view as its coordinate view.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to create a new mouse event handler for the specified view.
Called to copy an object.

Parameters:

Takes no parameters.
const TViewHandle & coordinateView -The view for which the new handler is created.
const MMouseEventHandler & 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: MMouseEventHandler::~MMouseEventHandler

virtual ~ MMouseEventHandler ()

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

MMouseEventHandler & operator =(const MMouseEventHandler & assign)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

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

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

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: MMouseEventHandler::SetCoordinateView

virtual void SetCoordinateView (const TViewHandle & coordinateView)

Interface Category:

API.

Purpose:

Specifies that all mouse events are given in the specified view's coordinate system. If a handle to a NIL view is specified, MMouseEvents are given in global coordinates.

Calling Context:

Derived classes can call this function directly.

Parameters:

const TViewHandle & coordinateView -The TViewHandle object that specifies the viewÕs coordinate system for mouse events.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MMouseEventHandler::MouseDown

virtual bool MouseDown (TMouseDownEvent & mouseDown)

Interface Category:

API.

Purpose:

Called when a mouse button has been pressed. The coordinates of the mouse click are given in the handler's view's coordinate system. New clients should override MouseButtonDown instead of this function.

Calling Context:

Derived classes can call this function directly.

Parameters:

TMouseDownEvent & mouseDown -The mouse-down event that caused this function to be called.

Return Value:

Returns true if the event was handled; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should override this function to implement specific mouse-down handling behavior.

Member Function: MMouseEventHandler::MouseUp

virtual bool MouseUp (TMouseUpEvent & mouseUp)

Interface Category:

API.

Purpose:

Called when a mouse button has been released. The coordinates of the mouse are given in the handler's view's coordinate system. New clients should override MouseButtonUp instead of this function.

Calling Context:

Derived classes can call this function directly.

Parameters:

TMouseUpEvent & mouseUp -The mouse-up event that caused this function to be called.

Return Value:

Returns true if the event was handled; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should override this function to implement specific mouse-up handling behavior.

Member Function: MMouseEventHandler::MouseButtonDown

virtual bool MouseButtonDown (TMouseDownEvent & mouseDown, short buttonNumber)

Interface Category:

API.

Purpose:

Called when any button is pressed. If the mouse event is for the default button, then it calls MouseDown function for backward-compatibility. The coordinates of the mouse click are given in the handler's view's coordinate system.

Calling Context:

Derived classes can call this function directly.

Parameters:

TMouseDownEvent & mouseDown -The mouse-down event that caused this function to be called.
short buttonNumber -A value that specifies a particular mouse button. Mouse button numbering starts with 1, not 0.

Return Value:

Returns true if the event was handled; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should override this function to implement specific mouse-down handling behavior.

Member Function: MMouseEventHandler::MouseButtonUp

virtual bool MouseButtonUp (TMouseUpEvent & mouseUp, short buttonNumber)

Interface Category:

API.

Purpose:

Called when any button is released. If the mouse event is for the default button, then it calls MouseUp function for backward-compatibility. The coordinates of the mouse are given in the handler's view's coordinate system.

Calling Context:

Derived classes can call this function directly.

Parameters:

TMouseUpEvent & mouseUp -The mouse-up event that caused this function to be called.
short buttonNumber -A value that specifies a particular mouse button. Mouse button numbering starts with 1, not 0.

Return Value:

Returns true if the event was handled; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should override this function to implement specific mouse-up handling behavior.

Member Function: MMouseEventHandler::MouseEntered

virtual bool MouseEntered (TMouseMovedEvent & mouseEnter)

Interface Category:

API.

Purpose:

Called by the framework when a mouse has entered the MMouseEventHandler's view. As with any event-handling function, this function should return true if the object has used the event, indicating that no further object should get the event.

Calling Context:

Derived classes can call this function directly.

Parameters:

TMouseMovedEvent & mouseEnter -The mouse-moved event that caused this function to be called.

Return Value:

Returns true if the event was handled; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should override this function to implement specific mouse-moved handling behavior.

Member Function: MMouseEventHandler::MouseExited

virtual bool MouseExited (TMouseMovedEvent & mouseExit)

Interface Category:

API.

Purpose:

Called by the framework when a mouse has exited the MMouseEventHandler's view. As with any event-handling function, this function should return true if the object has used the event, indicating that no further object should get the event.

Calling Context:

Derived classes can call this function directly.

Parameters:

TMouseMovedEvent & mouseExit -The event to get parameters from.

Return Value:

Returns true if the event was handled.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should override this function to implement specific mouse-exited handling behavior.

Member Function: MMouseEventHandler::StartMouseEntryEvents

virtual void StartMouseEntryEvents ()

Interface Category:

API.

Purpose:

Called by the developer to start detecting mouse entry and exit. If the object is already watching its view, calling StartMouseEntryEvents changes nothing. If no view has been set, then calling this member function is a no-op.

Calling Context:

Derived classes can 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: MMouseEventHandler::StopMouseEntryEvents

virtual void StopMouseEntryEvents ()

Interface Category:

API.

Purpose:

Called by the developer when the object is through detecting mouse entry and exit. If the object is not currently getting mouse-entry events, this function does nothing.

Calling Context:

Derived classes can 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: MMouseEventHandler::MouseMoved

virtual bool MouseMoved (TMouseMovedEvent & mouseMoved)

Interface Category:

API.

Purpose:

Called when the mouse moves and if mouse-moved events are turned on. The coordinates of the mouse are given in the handler's view's coordinate system.

Calling Context:

Derived classes can call this function directly.

Parameters:

TMouseMovedEvent & mouseMoved -The mouse-moved event that caused this function to be called.

Return Value:

Returns true if the event was handled; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should override this function to implement specific mouse-moved handling behavior.

Member Function: MMouseEventHandler::StartMouseMovedEvents

virtual void StartMouseMovedEvents (TMouseInputDevice & mouseToWatch)

Interface Category:

API.

Purpose:

Called by the developer to start detecting the motion of the given mouse in the coordinate system of the MMouseEventHandlerÕs coordinate view. If no view has been set, then calling this member function is a no-op.

Calling Context:

Derived classes can call this function directly.

Parameters:

TMouseInputDevice & mouseToWatch -The input device to watch.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MMouseEventHandler::StopMouseMovedEvents

virtual void StopMouseMovedEvents ()

Interface Category:

API.

Purpose:

Called by the developer to stop detecting the motion of the given mouse in the coordinate system of the MMouseEventHandlerÕs coordinate view.

Calling Context:

Derived classes can 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.

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