Merge "Add BuildPickingRay to devel api" into devel/master
[platform/core/uifw/dali-core.git] / dali / public-api / events / pan-gesture.h
index 00b5baa..93d1535 100644 (file)
@@ -1,8 +1,8 @@
-#ifndef __DALI_PAN_GESTURE_H__
-#define __DALI_PAN_GESTURE_H__
+#ifndef DALI_PAN_GESTURE_H
+#define DALI_PAN_GESTURE_H
 
 /*
- * Copyright (c) 2014 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2020 Samsung Electronics Co., Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
 
 namespace Dali
 {
+namespace Internal DALI_INTERNAL
+{
+class PanGesture;
+}
+
+/**
+ * @addtogroup dali_core_events
+ * @{
+ */
 
 /**
  * @brief A PanGesture is emitted when the user moves one or more fingers in a particular direction.
  *
- * This gesture can be in one of three states, when the pan gesture is first detected: "Started";
- * when the pan gesture is continuing: "Continuing"; and finally, when the pan gesture ends:
- * "Finished".
+ * This gesture can be in one of three states, when the pan gesture is first detected: GestureState::STARTED
+ * when the pan gesture is continuing: GestureState::CONTINUING and finally, when the pan gesture ends:
+ * GestureState::FINISHED.
  *
  * A pan gesture will end in the following ways:
  * - User releases the primary finger (the first touch).
@@ -39,39 +48,54 @@ namespace Dali
  * - Cancelled by the system.
  *
  * A pan gesture will continue to be sent to the actor under than initial pan until it ends.
+ * @SINCE_1_9.28
  */
-struct DALI_IMPORT_API PanGesture: public Gesture
+class DALI_CORE_API PanGesture : public Gesture
 {
-  // Construction & Destruction
-
+public:
   /**
-   * @brief Default Constructor.
+   * @brief Creates an uninitialized PanGesture handle.
+   *
+   * Calling member functions with an uninitialized Actor handle is not allowed.
+   * @SINCE_1_9.28
    */
   PanGesture();
 
   /**
-   * @brief Constructor.
-   *
-   * @param[in]  state  The state of the gesture
+   * @brief Copy constructor.
+   * @SINCE_1_9.28
+   * @param[in] rhs A reference to the copied handle
    */
-  PanGesture(Gesture::State state);
+  PanGesture(const PanGesture& rhs);
 
   /**
-   * @brief Copy constructor.
+   * @brief Move constructor.
+   * @SINCE_1_9.28
+   * @param[in] rhs A reference to the moved handle
    */
-  PanGesture( const PanGesture& rhs );
+  PanGesture(PanGesture&& rhs) noexcept;
 
   /**
    * @brief Assignment operator.
+   * @SINCE_1_9.28
+   * @param[in] rhs A reference to the copied handle
+   * @return A reference to this
    */
-  PanGesture& operator=( const PanGesture& rhs );
+  PanGesture& operator=(const PanGesture& rhs);
 
   /**
-   * @brief Virtual destructor.
+   * @brief Move assignment operator.
+   * @SINCE_1_9.28
+   * @param[in] rhs A reference to the moved handle
+   * @return A reference to this
    */
-  virtual ~PanGesture();
+  PanGesture& operator=(PanGesture&& rhs) noexcept;
 
-  // Data
+  /**
+   * @brief Non virtual destructor.
+   * @SINCE_1_9.28
+   */
+  ~PanGesture();
 
   /**
    * @brief The velocity at which the user is moving their fingers.
@@ -80,8 +104,10 @@ struct DALI_IMPORT_API PanGesture: public Gesture
    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
    * A positive y value shows that the user is panning downwards, a negative y values means upwards.
    * This value represents the local coordinates of the actor attached to the PanGestureDetector.
+   * @SINCE_1_9.28
+   * @return The velocity of the pan
    */
-  Vector2 velocity;
+  const Vector2& GetVelocity() const;
 
   /**
    * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or,
@@ -91,13 +117,17 @@ struct DALI_IMPORT_API PanGesture: public Gesture
    * A positive y value shows that the user is panning downwards, a negative y value means upwards.
    * This value is in local actor coordinates, the actor being the one attached to the
    * PanGestureDetector.
+   * @SINCE_1_9.28
+   * @return The displacement of the pan
    */
-  Vector2 displacement;
+  const Vector2& GetDisplacement() const;
 
   /**
    * @brief This current touch position of the primary touch point in local actor coordinates.
+   * @SINCE_1_9.28
+   * @return The current position of the pan (in local actor coordinates)
    */
-  Vector2 position;
+  const Vector2& GetPosition() const;
 
   /**
    * @brief The velocity at which the user is moving their fingers.
@@ -106,8 +136,10 @@ struct DALI_IMPORT_API PanGesture: public Gesture
    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
    * A positive y value shows that the user is panning downwards, a negative y values means upwards.
    * This value represents the screen coordinates.
+   * @SINCE_1_9.28
+   * @return The velocity of the pan (in screen coordinates)
    */
-  Vector2 screenVelocity;
+  const Vector2& GetScreenVelocity() const;
 
   /**
    * @brief This is a Vector2 showing how much the user has panned (dragged) since the last pan gesture or,
@@ -116,18 +148,24 @@ struct DALI_IMPORT_API PanGesture: public Gesture
    * A positive x value shows that the user is panning to the right, a negative x value means the opposite.
    * A positive y value shows that the user is panning downwards, a negative y value means upwards.
    * This value is in screen coordinates.
+   * @SINCE_1_9.28
+   * @return The displacement of the pan (in screen coordinates)
    */
-  Vector2 screenDisplacement;
+  const Vector2& GetScreenDisplacement() const;
 
   /**
    * @brief This current touch position of the primary touch point in screen coordinates.
+   * @SINCE_1_9.28
+   * @return The current position of the pan (in screen coordinates)
    */
-  Vector2 screenPosition;
+  const Vector2& GetScreenPosition() const;
 
   /**
    * @brief The total number of fingers touching the screen in a pan gesture.
+   * @SINCE_1_9.28
+   * @return The number of touches in the pan
    */
-  unsigned int numberOfTouches;
+  uint32_t GetNumberOfTouches() const;
 
   // Convenience Methods
 
@@ -135,7 +173,8 @@ struct DALI_IMPORT_API PanGesture: public Gesture
    * @brief Returns the speed at which the user is moving their fingers.
    *
    * This is the pixel movement per millisecond.
-   * @return The speed of the pan (in pixels per millisecond).
+   * @SINCE_1_9.28
+   * @return The speed of the pan (in pixels per millisecond)
    */
   float GetSpeed() const;
 
@@ -144,7 +183,8 @@ struct DALI_IMPORT_API PanGesture: public Gesture
    * if the gesture has just started, then the distance moved since the user touched the screen.
    *
    * This is always a positive value.
-   * @return The distance, as a float, a user's finger has panned.
+   * @SINCE_1_9.28
+   * @return The distance, as a float, a user's finger has panned
    */
   float GetDistance() const;
 
@@ -152,7 +192,8 @@ struct DALI_IMPORT_API PanGesture: public Gesture
    * @brief Returns the speed at which the user is moving their fingers relative to screen coordinates.
    *
    * This is the pixel movement per millisecond.
-   * @return The speed of the pan (in pixels per millisecond).
+   * @SINCE_1_9.28
+   * @return The speed of the pan (in pixels per millisecond)
    */
   float GetScreenSpeed() const;
 
@@ -162,11 +203,26 @@ struct DALI_IMPORT_API PanGesture: public Gesture
    * since the user touched the screen.
    *
    * This is always a positive value.
-   * @return The distance, as a float, a user's finger has panned.
+   * @SINCE_1_9.28
+   * @return The distance, as a float, a user's finger has panned
    */
   float GetScreenDistance() const;
+
+public: // Not intended for application developers
+  /// @cond internal
+  /**
+   * @brief This constructor is used internally to Create an initialized PanGesture handle.
+   *
+   * @param[in] panGesture A pointer to a newly allocated Dali resource
+   * @SINCE_1_9.28
+   */
+  explicit DALI_INTERNAL PanGesture(Internal::PanGesture* panGesture);
+  /// @endcond
 };
 
+/**
+ * @}
+ */
 } // namespace Dali
 
-#endif // __DALI_PAN_GESTURE_H__
+#endif // DALI_PAN_GESTURE_H