juce/source/src/gui/components/mouse/juce_ComponentDragger.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_COMPONENTDRAGGER_JUCEHEADER__
  27 #define __JUCE_COMPONENTDRAGGER_JUCEHEADER__
  28
  29 #include "juce_MouseEvent.h"
  30 #include "../layout/juce_ComponentBoundsConstrainer.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     An object to take care of the logic for dragging components around with the mouse.
  36
  37     Very easy to use - in your mouseDown() callback, call startDraggingComponent(),
  38     then in your mouseDrag() callback, call dragComponent().
  39
  40     When starting a drag, you can give it a ComponentBoundsConstrainer to use
  41     to limit the component's position and keep it on-screen.
  42
  43     e.g. @code
  44     class MyDraggableComp
  45     {
  46         ComponentDragger myDragger;
  47
  48         void mouseDown (const MouseEvent& e)
  49         {
  50             myDragger.startDraggingComponent (this, e);
  51         }
  52
  53         void mouseDrag (const MouseEvent& e)
  54         {
  55             myDragger.dragComponent (this, e, nullptr);
  56         }
  57     };
  58     @endcode
  59 */
  60 class JUCE_API  ComponentDragger
  61 {
  62 public:
  63     //==============================================================================
  64     /** Creates a ComponentDragger. */
  65     ComponentDragger();
  66
  67     /** Destructor. */
  68     virtual ~ComponentDragger();
  69
  70     //==============================================================================
  71     /** Call this from your component's mouseDown() method, to prepare for dragging.
  72
  73         @param componentToDrag      the component that you want to drag
  74         @param e                    the mouse event that is triggering the drag
  75         @see dragComponent
  76     */
  77     void startDraggingComponent (Component* componentToDrag,
  78                                  const MouseEvent& e);
  79
  80     /** Call this from your mouseDrag() callback to move the component.
  81
  82         This will move the component, but will first check the validity of the
  83         component's new position using the checkPosition() method, which you
  84         can override if you need to enforce special positioning limits on the
  85         component.
  86
  87         @param componentToDrag      the component that you want to drag
  88         @param e                    the current mouse-drag event
  89         @param constrainer          an optional constrainer object that should be used
  90                                     to apply limits to the component's position. Pass
  91                                     null if you don't want to contrain the movement.
  92         @see startDraggingComponent
  93     */
  94     void dragComponent (Component* componentToDrag,
  95                         const MouseEvent& e,
  96                         ComponentBoundsConstrainer* constrainer);
  97
  98 private:
  99     //==============================================================================
 100     Point<int> mouseDownWithinTarget;
 101
 102     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ComponentDragger);
 103 };
 104
 105 #endif   // __JUCE_COMPONENTDRAGGER_JUCEHEADER__