dali/devel-api/adaptor-framework/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) 2018 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/public-api/dali-adaptor-common.h>
  28
  29 namespace Dali
  30 {
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 namespace Adaptor
  35 {
  36 class DragAndDropDetector;
  37 }
  38 }
  39
  40 /**
  41  * @brief The DragAndDropDetector%s provides signals when draggable objects are dragged into our window.
  42  *
  43  * It provides signals for when the draggable object enters our window, moves around in our window,
  44  * leaves our window and when it is finally dropped into our window.
  45  *
  46  * The basic usage is shown below:
  47  *
  48  * @code
  49  *
  50  *  void Example()
  51  *  {
  52  *    DragAndDropDetector detector( window::GetDragAndDropDetector() );
  53  *
  54  *    // Get notifications when the draggable item enters our window
  55  *    detector.EnteredSignal().Connect( &OnEntered );
  56  *
  57  *    // Get notifications when the draggable item leaves our window
  58  *    detector.ExitedSignal().Connect( &OnExited );
  59  *
  60  *    // Get notifications when the draggable item is moved within our window
  61  *    detector.MovedSignal().Connect( &OnMoved );
  62  *
  63  *    // Get notifications when the draggable item is dropped
  64  *    detector.DroppedSignal().Connect( &OnDropped );
  65  *  }
  66  *
  67  *  void OnEntered( DragAndDropDetector detector )
  68  *  {
  69  *    // Change mode as required
  70  *  }
  71  *
  72  *  void OnExited( DragAndDropDetector detector )
  73  *  {
  74  *    // Change mode as required
  75  *  }
  76  *
  77  *  void OnMoved( DragAndDropDetector detector )
  78  *  {
  79  *    // Query the new values
  80  *    std::cout << "Position = " << detector.GetCurrentScreenPosition() << std::endl;
  81  *  }
  82  *
  83  *  void OnDropped( DragAndDropDetector detector )
  84  *  {
  85  *    // Query the new values
  86  *    std::cout << "Position = " << detector.GetCurrentScreenPosition() << ", Content = " << detector.GetContent() << std::endl;
  87  *  }
  88  *
  89  * @endcode
  90  */
  91 class DALI_ADAPTOR_API DragAndDropDetector : public BaseHandle
  92 {
  93 public:
  94
  95   // Typedefs
  96
  97   typedef Signal< void ( DragAndDropDetector ) > DragAndDropSignal; ///< Drag & Drop signal
  98
  99   /**
 100    * @brief Create an uninitialized handle.
 101    *
 102    * This can be initialized by calling getting the detector from Dali::Window.
 103    */
 104   DragAndDropDetector();
 105
 106   /**
 107    * @brief Destructor
 108    *
 109    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 110    */
 111   ~DragAndDropDetector();
 112
 113   /**
 114    * @brief Returns the dropped content.
 115    *
 116    * @return A reference to the string representing the dropped content.
 117    */
 118   const std::string& GetContent() const;
 119
 120   /**
 121    * @brief Returns the current position of the dragged object.
 122    *
 123    * This is the dropped position when an object is dropped.
 124    * @return The current screen position.
 125    */
 126   Vector2 GetCurrentScreenPosition() const;
 127
 128   // Signals
 129
 130   /**
 131    * @brief This is emitted when a dragged object enters a DALi window.
 132    *
 133    * A callback of the following type may be connected:
 134    * @code
 135    *   void YourCallback( DragAndDropDetector detector );
 136    * @endcode
 137    * @return The signal to connect to.
 138    */
 139   DragAndDropSignal& EnteredSignal();
 140
 141   /**
 142    * @brief This is emitted when a dragged object leaves a DALi window.
 143    *
 144    * A callback of the following type may be connected:
 145    * @code
 146    *   void YourCallback( DragAndDropDetector detector );
 147    * @endcode
 148    * @return The signal to connect to.
 149    */
 150   DragAndDropSignal& ExitedSignal();
 151
 152   /**
 153    * @brief This is emitted when a dragged object is moved within the DALi window.
 154    *
 155    * A callback of the following type may be connected:
 156    * @code
 157    *   void YourCallback( DragAndDropDetector detector );
 158    * @endcode
 159    * @return The signal to connect to.
 160    */
 161   DragAndDropSignal& MovedSignal();
 162
 163   /**
 164    * @brief This is emitted when a dragged object is dropped within a DALi window.
 165    *
 166    * A callback of the following type may be connected:
 167    * @code
 168    *   void YourCallback( DragAndDropDetector detector );
 169    * @endcode
 170    * @return The signal to connect to.
 171    */
 172   DragAndDropSignal& DroppedSignal();
 173
 174 public: // Not intended for application developers
 175
 176   /**
 177    * @brief This constructor is used by DragAndDropDetector::Get().
 178    *
 179    * @param[in] detector A pointer to the drag and drop detector.
 180    */
 181   explicit DALI_INTERNAL DragAndDropDetector( Internal::Adaptor::DragAndDropDetector* detector );
 182 };
 183
 184 } // namespace Dali
 185
 186 #endif // __DALI_DRAG_AND_DROP_DETECTOR_H__