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

~IMouseHandler

      public:
      virtual ~IMouseHandler()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

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

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.

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

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

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

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

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.

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

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

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.

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

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

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

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

  -     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)

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IHandler

  -     virtual IEventResult defaultProcedure(IEvent& event)

  -     virtual bool dispatchHandlerEvent(IEvent& event) = 0

#### Inherited Protected Data

  - None