IMouseHandler

The IMouseHandler class processes a variety of mouse events. These events include button presses and releases, double-clicks, multiple button presses, mouse movement, and the appearance of the mouse pointer.

You can attach an IMouseHandler object to any kind of window. Although the control or window that the mouse is over is the first to receive a mouse event, any event other than a button click that is passed on for additional processing will likely be dispatched to the owner window.

A mouse event continues to travel up the owner window chain until either a handler stops it or the event is processed by the window itself. As a result, an IMouseHandler object should not stop the processing of any mouse event that it does not need to handle, because the event has the potential of being handled by another window in the owner chain, such as the frame window.

When an IMouseHandler object receives a mouse event, the IMouseHandler object creates either an IMouseEvent, an IMouseClickEvent, or an IEvent object and then routes it to a virtual function of the mouse handler. Override these virtual functions to supply your own processing of a mouse event.

The return value from the virtual function is interpreted as follows:

true
The mouse event requires no additional processing and is not passed to another handler or to the presentation system.
false
The mouse event is passed on for additional processing when the following situations occur:
  • If there is another handler for the window, the event is passed on to the next handler.
  • If this is the last handler for the window, the event is passed on a call to the window's defaultProcedure function. This could result in the event being dispatched to the window's owner window, where the processing of the mouse event starts again.


IMouseHandler - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


[view class]
~IMouseHandler
public:
virtual ~IMouseHandler()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IMouseHandler
public:
IMouseHandler(const Style& style = defaultStyle ( ))

You can specify an optional style when constructing objects of this class.

Exception

IInvalidParameter style contains an invalid combination of styles. style cannot contain more than one of the following style values: IMouseHandler::noMouseMoves, IMouseHandler::someMouseMoves, and IMouseHandler::allMouseMoves.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Dispatching

The Open Class Library dispatches events that have been sent or posted to a window to the handlers attached to that window. It does this by calling the event-dispatching function of the handler objects. An IMouseHandler object processes only mouse-related events.


[view class]
handleEventsFor
public:
virtual IMouseHandler& handleEventsFor(IWindow* window)

Attaches the handler to the specified IWindow object. The handler's dispatchHandlerEvent function is called to process all events sent or posted to the window.

If you specify any of the styles IMouseHandler::someMouseMoves, IMouseHandler::allMouseMoves, or IMouseHandler::mouseEntersLeaves when constructing the IMouseHandler object, this function calls IWindow::startHandling, passing the corresponding event mask.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stopHandlingEventsFor
public:
virtual IMouseHandler& stopHandlingEventsFor( IWindow* window )

Detaches the handler from the specified IWindow object. The handler's dispatchHandlerEvent function is no longer called to process events sent or posted to the window.

If you specify any of the styles IMouseHandler::someMouseMoves, IMouseHandler::allMouseMoves, or IMouseHandler::mouseEntersLeaves when constructing the IMouseHandler object, this function calls IWindow::stopHandling, passing the corresponding event mask.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dispatchHandlerEvent
protected:
virtual bool dispatchHandlerEvent(IEvent& event)

If a mouse-related event is received, this function calls the appropriate virtual function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Processing

A mouse handler contains event-processing members that you use to process mouse-related events. You should override at least one of these virtual functions in a derived class.


[view class]
mouseClicked
protected:
virtual bool mouseClicked(IMouseClickEvent& event)

Implemented by derived classes to process a mouse-click event.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
mouseEnter
protected:
virtual bool mouseEnter(IEvent& event)

Implemented by derived classes to process when the user moves the mouse pointer into the handled window. IMouseHandler::dispatchHandlerEvent calls this function when the mouse pointer crosses from another window into the handled window. The other window could be the parent window, a child window, a sibling window, or a window of another application.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
mouseLeave
protected:
virtual bool mouseLeave(IEvent& event)

Implemented by derived classes to process when the user moves the mouse pointer out of the handled window. IMouseHandler::dispatchHandlerEvent calls this function when the mouse pointer crosses from the handled window into another window, such as the parent window, a child window, a sibling window, or a window of another application.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
mouseMoved
protected:
virtual bool mouseMoved(IMouseEvent& event)

Implemented by derived classes to process a mouse-movement event. IMouseHandler::dispatchHandlerEvent calls this function any time the user moves the mouse pointer while it is over the handled window.
Note: Processing mouse move events can cause an override of IMouseHandler::mousePointerChange to not be called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
mousePointerChange
protected:
virtual bool mousePointerChange(IMousePointerEvent& event)

Implemented by derived classes to change the appearance of the mouse pointer when it is over the handled window. IMouseHandler::dispatchHandlerEvent calls this function when the mouse pointer is moved over the handled window.

You can also set the appearance of the mouse pointer for a window by calling IWindow::setMousePointer. Use IWindow::setMousePointer to use the same mouse pointer everywhere within the window. If you need the appearance of the mouse pointer to be dependent on where the pointer is over the window (for example, so that the mouse pointer looks different when it is over the edge of the window than over the rest of the window), use a handler overriding IMouseHandler::mousePointerChange.
Note: Do not use both the IWindow::setMousePointer function and a handler overriding IMouseHandler::mousePointerChange on the same window. Unpredictable results may occur.

For portability, attach the mouse handler directly to the window whose mouse pointer you want to change. Pointer-change events are not propagated up the owner window chain on AIX, as they are on OS/2 and Windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

For this callback function to be called each time the mouse is moved, you must create the IMouseHandler with the style IMouseHandler::allMouseMoves.

If you remove a handler overriding IMouseHandler::mousePointerChange, or that handler does not handle the pointer-change event, the mouse pointer is not automatically reset to the default pointer. Instead, when the mouse is over the window it will use the last pointer set by the handler.


Styles

Styles identify which mouse-movement events the mouse handler should process. This allows Open Class Library to potentially improve performance by not processing unnecessary mouse-movement events.

The styles, as ordered by from best to worst performance, are:

  1. noMouseMoves
  2. mouseEntersLeaves
  3. someMouseMoves
  4. allMouseMoves

AIX Considerations

Use of these styles has the greatest benefit on Motif.


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. The default style is someMouseMoves unless you have changed the style using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent mouse handlers.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you construct an IMouseHandler object do not specify a style in the constructor, the IMouseHandler constructor queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create mouse handlers are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify a style when constructing an IMouseHandler, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
allMouseMoves
public:
static const Style allMouseMoves

Allows IMouseHandler to call its virtual function mouseMoved when it detects a mouse-movement event. IMouseHandler will not call this virtual function if you do not specify either this style or IMouseHandler::someMouseMoves.

Additionally, use of this style causes IMouseHandler::handleEventsFor to call IWindow::startHandling, passing IWindow::allMouseMoves as the event mask.

This style does not control whether IMouseHandler calls mouseEnter or mouseLeave (see IMouseHandler::mouseEntersLeaves for more information).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Use of this style also allows the handler to call its mousePointerChange virtual function each time the mouse is moved over the window.

This style causes IMouseHandler to process more events than IMouseHandler::someMouseMoves. It causes the window to use the XLib PointerMotionMask event mask to receive mouse-motion events.

OS/2 Considerations

This style is equivalent to IMouseHandler::someMouseMoves.

Windows Considerations

This style is equivalent to IMouseHandler::someMouseMoves.


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Specifies the original default style for this class, which is IMouseHandler::someMouseMoves.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
mouseEntersLeaves
public:
static const Style mouseEntersLeaves

Causes IMouseHandler to call its virtual functions mouseEnter and mouseLeave when the mouse pointer crosses into or out of the window. IMouseHandler will not call these virtual functions if you do not specify this style.

Additionally, use of this style causes IMouseHandler::handleEventsFor to call IWindow::startHandling, passing IWindow::mouseEntersLeaves as the event mask.

This style does not control whether IMouseHandler calls mouseMoved (see IMouseHandler::noMouseMoves, IMouseHandler::someMouseMoves, and IMouseHandler::allMouseMoves, for more information).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noMouseMoves
public:
static const Style noMouseMoves

Causes IMouseHandler to not call its virtual function mouseMoved when it detects a mouse-movement event. This style does not control whether IMouseHandler calls mouseEnter or mouseLeave (see IMouseHandler::mouseEntersLeaves for more information).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
someMouseMoves
public:
static const Style someMouseMoves

Allows IMouseHandler to call its virtual function mouseMoved when it detects a mouse-movement event. IMouseHandler will not call this virtual functions if you do not specify either this style or IMouseHandler::allMouseMoves.

Additionally, use of this style causes IMouseHandler::handleEventsFor to call IWindow::startHandling, passing IWindow::someMouseMoves as the event mask.

This style does not control whether IMouseHandler calls mouseEnter or mouseLeave (see IMouseHandler::mouseEntersLeaves for more information).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This style causes IMouseHandler to process fewer events than IMouseHandler::allMouseMoves. It causes the window to use the XLib PointerMotionMask and PointerMotionHintMask event masks to receive mouse-motion events.

OS/2 Considerations

This style is equivalent to IMouseHandler::allMouseMoves.

Windows Considerations

This style is equivalent to IMouseHandler::allMouseMoves.


IMouseHandler - Inherited Member Functions and Data

Inherited Public Functions

IHandler

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data