added wxMouseEventsManager

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@60463 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/mousemanager.h

@@ -0,0 +1,148 @@
+///////////////////////////////////////////////////////////////////////////////
+// Name:        wx/mousemanager.h
+// Purpose:     wxMouseEventsManager class declaration
+// Author:      Vadim Zeitlin
+// Created:     2009-04-20
+// RCS-ID:      $Id$
+// Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
+// Licence:     wxWindows licence
+///////////////////////////////////////////////////////////////////////////////
+
+#ifndef _WX_MOUSEMANAGER_H_
+#define _WX_MOUSEMANAGER_H_
+
+#include "wx/event.h"
+
+// ----------------------------------------------------------------------------
+// wxMouseEventsManager
+// ----------------------------------------------------------------------------
+
+/*
+    This class handles mouse events and synthesizes high-level notifications
+    such as clicks and drag events from low level mouse button presses and
+    mouse movement events. It is useful because handling the mouse events is
+    less obvious than might seem at a first glance: for example, clicks on an
+    object should only be generated if the mouse was both pressed and released
+    over it and not just released (so it requires storing the previous state)
+    and dragging shouldn't start before the mouse moves away far enough.
+
+    This class encapsulates all these dull details for controls containing
+    multiple items which can be identified by a positive integer index and you
+    just need to implement its pure virtual functions to use it.
+ */
+class WXDLLIMPEXP_CORE wxMouseEventsManager : public wxEvtHandler
+{
+public:
+    // a mouse event manager is always associated with a window and must be
+    // deleted by the window when it is destroyed
+    wxMouseEventsManager(wxWindow *win);
+
+    virtual ~wxMouseEventsManager();
+
+protected:
+    // called to find the item at the given position: return wxNOT_FOUND (-1)
+    // if there is no item here
+    virtual int MouseHitTest(const wxPoint& pos) = 0;
+
+    // called when the user clicked (i.e. pressed and released mouse over the
+    // same item), should normally generate a notification about this click and
+    // return true if it was handled or false otherwise, determining whether
+    // the original mouse event is skipped or not
+    virtual bool MouseClicked(int item) = 0;
+
+    // called to start dragging the given item, should generate the appropriate
+    // BEGIN_DRAG event and return false if dragging this item was forbidden
+    virtual bool MouseDragBegin(int item, const wxPoint& pos) = 0;
+
+    // called while the item is being dragged, should normally update the
+    // feedback on screen (usually using wxOverlay)
+    virtual void MouseDragging(int item, const wxPoint& pos) = 0;
+
+    // called when the mouse is released after dragging the item
+    virtual void MouseDragEnd(int item, const wxPoint& pos) = 0;
+
+    // called when mouse capture is lost while dragging the item, should remove
+    // the visual feedback drawn by MouseDragging()
+    virtual void MouseDragCancelled(int item) = 0;
+
+
+    // you don't need to override those but you will want to do if it your
+    // control renders pressed items differently
+
+    // called when the item is becomes pressed, can be used to change its
+    // appearance
+    virtual void MouseClickBegin(int WXUNUSED(item)) { }
+
+    // called if the mouse capture was lost while the item was pressed, can be
+    // used to restore the default item appearance if it was changed in
+    // MouseClickBegin()
+    virtual void MouseClickCancelled(int WXUNUSED(item)) { }
+
+private:
+    /*
+        Here is a small diagram explaining the switches between different
+        states:
+
+
+                /---------->NORMAL<--------------- Drag end
+               /     /   /    |                      event
+              /     /    |    |                        ^
+             /     /     |    |                        |
+           Click  /    N |    | mouse                  | mouse up
+           event /       |    | down                   |
+             |  /        |    |                     DRAGGING
+             | /         |    |                        ^
+            Y|/ N        \    v                        |Y
+      +-------------+     +--------+           N +-----------+
+      |On same item?|     |On item?|  -----------|Begin drag?|
+      +-------------+     +--------+ /           +-----------+
+             ^                |     /                  ^
+             |                |    /                   |
+              \      mouse    |   /   mouse moved      |
+                \     up      v  v     far enough     /
+                  \--------PRESSED-------------------/
+
+
+        There are also transitions from PRESSED and DRAGGING to NORMAL in case
+        the mouse capture is lost or Escape key is pressed which are not shown.
+     */
+    enum State
+    {
+        State_Normal,   // initial, default state
+        State_Pressed,  // mouse was pressed over an item
+        State_Dragging  // the item is being dragged
+    };
+
+
+    // various event handlers
+    void OnCaptureLost(wxMouseCaptureLostEvent& event);
+    void OnLeftDown(wxMouseEvent& event);
+    void OnLeftUp(wxMouseEvent& event);
+    void OnMove(wxMouseEvent& event);
+
+
+    // the associated window, never NULL
+    wxWindow * const m_win;
+
+    // the current state
+    State m_state;
+
+    // the details of the operation currently in progress, only valid if
+    // m_state is not normal
+
+    // the item being pressed or dragged (always valid, i.e. != wxNOT_FOUND if
+    // m_state != State_Normal)
+    int m_item;
+
+    // the position of the last mouse event of interest: either mouse press in
+    // State_Pressed or last movement event in State_Dragging
+    wxPoint m_posLast;
+
+
+    DECLARE_EVENT_TABLE()
+
+    wxDECLARE_NO_COPY_CLASS(wxMouseEventsManager);
+};
+
+#endif // _WX_MOUSEMANAGER_H_
+