dali-toolkit/devel-api/drag-drop-detector/drag-and-drop-detector.h

   1 #ifndef DALI_DRAG_AND_DROP_DETECTOR_H
   2 #define DALI_DRAG_AND_DROP_DETECTOR_H
   3
   4 /*
   5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <dali/public-api/object/base-handle.h>
  23 #include <dali/public-api/signals/dali-signal.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/public-api/dali-toolkit-common.h>
  27
  28 #include <dali-toolkit/public-api/controls/control.h>
  29
  30 namespace Dali
  31 {
  32 namespace Toolkit
  33 {
  34 namespace Internal DALI_INTERNAL
  35 {
  36 class DragAndDropDetector;
  37 }
  38
  39 /**
  40  * @brief The DragAndDropDetector%s provides signals when draggable objects are dragged into other object.
  41  *
  42  * It provides signals for when the draggable object start drag, draggable object enters other object, moves around in other object,
  43  * leaves other object, dropped into other object and finally when the drag ended.
  44  *
  45  * The basic usage is shown below:
  46  *
  47  * @code
  48  *
  49  *  void Example()
  50  *  {
  51  *    DragAndDropDetector detector = DragAndDropDetector::New();
  52  *
  53  *    // Get notifications when the draggable item start drag
  54  *    detector.StartedSignal().Connect( &OnStarted );
  55  *
  56  *    // Get notifications when the draggable item enters other item
  57  *    detector.EnteredSignal().Connect( &OnEntered );
  58  *
  59  *    // Get notifications when the draggable item leaves other item
  60  *    detector.ExitedSignal().Connect( &OnExited );
  61  *
  62  *    // Get notifications when the draggable item is moved within other item
  63  *    detector.MovedSignal().Connect( &OnMoved );
  64  *
  65  *    // Get notifications when the draggable item is dropped
  66  *    detector.DroppedSignal().Connect( &OnDropped );
  67  *
  68  *    // Get notifications when the draggable object drag ended
  69  *    detector.EndedSignal().Connect( &OnEnded );
  70  *  }
  71  *
  72  *  void OnStarted( Control control, DragAndDropDetector detector )
  73  *  {
  74  *    // Query the new values
  75  *    std::cout << "Position = " << detector.GetCurrentScreenPosition() << std::endl;
  76  *  }
  77  *
  78  *  void OnEntered( Control control, DragAndDropDetector detector )
  79  *  {
  80  *    // Change mode as required
  81  *  }
  82  *
  83  *  void OnExited( Control control, DragAndDropDetector detector )
  84  *  {
  85  *    // Change mode as required
  86  *  }
  87  *
  88  *  void OnMoved( Control control, DragAndDropDetector detector )
  89  *  {
  90  *    // Query the new values
  91  *    std::cout << "Position = " << detector.GetCurrentScreenPosition() << std::endl;
  92  *  }
  93  *
  94  *  void OnDropped( Control control, DragAndDropDetector detector )
  95  *  {
  96  *    // Query the new values
  97  *    std::cout << "Position = " << detector.GetCurrentScreenPosition() << ", Content = " << detector.GetContent() << std::endl;
  98  *  }
  99  *
 100  *  void OnEnded( Control control, DragAndDropDetector detector )
 101  *  {
 102  *    // Change mode as required
 103  *  }
 104  *
 105  * @endcode
 106  */
 107 class DALI_TOOLKIT_API DragAndDropDetector : public BaseHandle
 108 {
 109 public:
 110   // Typedefs
 111
 112   using DragAndDropSignal = Signal<void(Control, DragAndDropDetector)>; ///< Drag & Drop signal
 113
 114   /**
 115    * @brief Create an initialized DragAndDropDetector.
 116    *
 117    * @return A handle to a newly allocated Dali DragAndDropDetector
 118    */
 119   static DragAndDropDetector New();
 120
 121   /**
 122    * @brief Create an uninitialized handle.
 123    *
 124    * This can be initialized with DragAndDropDetector::New().
 125    */
 126   DragAndDropDetector();
 127
 128   /**
 129    * @brief Destructor
 130    *
 131    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 132    */
 133   ~DragAndDropDetector();
 134
 135   /**
 136    * @brief Returns the dropped content.
 137    *
 138    * @return A reference to the string representing the dropped content.
 139    */
 140   const std::string& GetContent() const;
 141
 142   /**
 143    * @brief Attaches a Control to the detector.
 144    *
 145    * @note You can attach several controls to a DragAndDropDetector.
 146    * DragAndDropDetector will keep a handle to the control and keep it alive as long as
 147    * DragAndDropDetector is deleted or Detach is called.
 148    */
 149   void Attach(Control control);
 150
 151   /**
 152    * @brief Detaches the attached control from the detector.
 153    *
 154    * @pre The specified control has been attached to the DragAndDropDetector.
 155    */
 156   void Detach(Control control);
 157
 158   /**
 159    * @brief Detaches all attached control from the detector.
 160    *
 161    * @pre At least one control has been attached to the DragAndDropDetector.
 162    */
 163   void DetachAll();
 164
 165   /**
 166    * @brief Returns the number of controls attached to the DragAndDropDetector.
 167    *
 168    * @pre The DragAndDropDetector has been initialized.
 169    */
 170   uint32_t GetAttachedControlCount() const;
 171
 172   /**
 173    * @brief Returns a control by index. An empty handle if the index is not valid.
 174    *
 175    * @pre The DragAndDropDetector has been initialized.
 176    */
 177   Control GetAttachedControl(uint32_t index) const;
 178
 179   /**
 180    * @brief Returns the current position of the dragged object.
 181    *
 182    * This is the dropped position when an object is dropped.
 183    * @return The current screen position.
 184    */
 185   const Vector2& GetCurrentScreenPosition() const;
 186
 187   // Signals
 188   /**
 189    * @brief This is emitted when a dragged object start drag.
 190    *
 191    * A callback of the following type may be connected:
 192    * @code
 193    *   void YourCallback( Control control, DragAndDropDetector detector );
 194    * @endcode
 195    * @return The signal to connect to.
 196    */
 197   DragAndDropSignal& StartedSignal();
 198
 199   /**
 200    * @brief This is emitted when a dragged object enters other object.
 201    *
 202    * A callback of the following type may be connected:
 203    * @code
 204    *   void YourCallback( Control control, DragAndDropDetector detector );
 205    * @endcode
 206    * @return The signal to connect to.
 207    */
 208   DragAndDropSignal& EnteredSignal();
 209
 210   /**
 211    * @brief This is emitted when a dragged object leaves other object.
 212    *
 213    * A callback of the following type may be connected:
 214    * @code
 215    *   void YourCallback( Control control, DragAndDropDetector detector );
 216    * @endcode
 217    * @return The signal to connect to.
 218    */
 219   DragAndDropSignal& ExitedSignal();
 220
 221   /**
 222    * @brief This is emitted when a dragged object is moved within other object.
 223    *
 224    * A callback of the following type may be connected:
 225    * @code
 226    *   void YourCallback( Control control, DragAndDropDetector detector );
 227    * @endcode
 228    * @return The signal to connect to.
 229    */
 230   DragAndDropSignal& MovedSignal();
 231
 232   /**
 233    * @brief This is emitted when a dragged object is dropped within other object.
 234    *
 235    * A callback of the following type may be connected:
 236    * @code
 237    *   void YourCallback( Control control, DragAndDropDetector detector );
 238    * @endcode
 239    * @return The signal to connect to.
 240    */
 241   DragAndDropSignal& DroppedSignal();
 242
 243   /**
 244    * @brief This is emitted when a dragged object drag ended.
 245    *
 246    * A callback of the following type may be connected:
 247    * @code
 248    *   void YourCallback( Control control, DragAndDropDetector detector );
 249    * @endcode
 250    * @return The signal to connect to.
 251    */
 252   DragAndDropSignal& EndedSignal();
 253
 254 public: // Not intended for application developers
 255   /**
 256    * @brief This constructor is used by DragAndDropDetector::Get().
 257    *
 258    * @param[in] detector A pointer to the drag and drop detector.
 259    */
 260   explicit DALI_INTERNAL DragAndDropDetector(Internal::DragAndDropDetector* detector);
 261 };
 262
 263 } // namespace Toolkit
 264
 265 } // namespace Dali
 266
 267 #endif // DALI_DRAG_AND_DROP_DETECTOR_H