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