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:
You can construct and destruct objects of this class.
![]() |
public:
virtual ~IMouseHandler()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IMouseHandler(const Style& style = defaultStyle ( ))
You can specify an optional style when constructing objects of this class.
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. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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.
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool dispatchHandlerEvent(IEvent& event)
If a mouse-related event is received, this function calls the appropriate virtual function.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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.
![]() |
protected:
virtual bool mouseClicked(IMouseClickEvent& event)
Implemented by derived classes to process a mouse-click event.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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:
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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 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:
Use of these styles has the greatest benefit on Motif.
![]() |
public:
static Style defaultStyle()
Returns the default style. The default style is someMouseMoves unless you have changed the style using setDefaultStyle.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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).
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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.
This style is equivalent to IMouseHandler::someMouseMoves.
This style is equivalent to IMouseHandler::someMouseMoves.
![]() |
public:
static const Style classDefaultStyle
Specifies the original default style for this class, which is IMouseHandler::someMouseMoves.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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).
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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).
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
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).
Windows | OS/2 | AIX |
Yes | Yes | Yes |
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.
This style is equivalent to IMouseHandler::allMouseMoves.
This style is equivalent to IMouseHandler::allMouseMoves.
virtual ~IHandler()
virtual IString asDebugInfo() const
virtual IString asString() const
virtual IHandler& disable()
virtual IHandler& enable(bool enable = true)
virtual IHandler& handleEventsFor(IWindow* window)
IHandler()
bool isEnabled() const
virtual IHandler& stopHandlingEventsFor(IWindow* window)
virtual IEventResult defaultProcedure(IEvent& event)
virtual bool dispatchHandlerEvent(IEvent& event) = 0