X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fevents%2Fpan-gesture-detector.h;h=3f6449de284b8f12b651b1d435fb2d28f995b869;hb=646f736e77b085c86e982c0d1d4b895c2a431330;hp=e75a214672d896c968a182cef06bc852c8eb84a3;hpb=c7044bf0978b26e21b8cef8bc88aa4c6a55d5539;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/events/pan-gesture-detector.h b/dali/public-api/events/pan-gesture-detector.h index e75a214..3f6449d 100644 --- a/dali/public-api/events/pan-gesture-detector.h +++ b/dali/public-api/events/pan-gesture-detector.h @@ -2,7 +2,7 @@ #define __DALI_PAN_GESTURE_DETECTOR_H__ /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2018 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. @@ -18,6 +18,9 @@ * */ +// EXTERNAL INCLUDES +#include // uint32_t + // INTERNAL INCLUDES #include #include @@ -36,6 +39,11 @@ class PanGestureDetector; struct PanGesture; /** + * @addtogroup dali_core_events + * @{ + */ + +/** * @brief This class looks for panning (or dragging) gestures. * * The user will be pressing one or more fingers on an actor while they pan it. @@ -50,40 +58,45 @@ struct PanGesture; * detector.SetMaximumTouchesRequired(2); * @endcode * + * @SINCE_1_0.0 * @see PanGesture * * Signals * | %Signal Name | Method | * |--------------|-----------------------| - * | pan-detected | @ref DetectedSignal() | + * | panDetected | @ref DetectedSignal() | */ -class DALI_IMPORT_API PanGestureDetector : public GestureDetector +class DALI_CORE_API PanGestureDetector : public GestureDetector { public: /** - * @brief An enumeration of properties belonging to the PanGestureDetector class. + * @brief Enumeration for the instance of properties belonging to the PanGestureDetector class. + * @SINCE_1_0.0 */ struct Property { + /** + * @brief Enumeration for the instance of properties belonging to the PanGestureDetector class. + * @SINCE_1_0.0 + */ enum { - SCREEN_POSITION = DEFAULT_GESTURE_DETECTOR_PROPERTY_START_INDEX, ///< name "screen-position", type Vector2 - SCREEN_DISPLACEMENT, ///< name "screen-displacement", type Vector2 - SCREEN_VELOCITY, ///< name "screen-velocity", type Vector2 - LOCAL_POSITION, ///< name "local-position", type Vector2 - LOCAL_DISPLACEMENT, ///< name "local-displacement", type Vector2 - LOCAL_VELOCITY, ///< name "local-velocity", type Vector2 - PANNING, ///< name "panning", type bool + SCREEN_POSITION = DEFAULT_GESTURE_DETECTOR_PROPERTY_START_INDEX, ///< name "screenPosition", type Vector2 @SINCE_1_0.0 + SCREEN_DISPLACEMENT, ///< name "screenDisplacement", type Vector2 @SINCE_1_0.0 + SCREEN_VELOCITY, ///< name "screenVelocity", type Vector2 @SINCE_1_0.0 + LOCAL_POSITION, ///< name "localPosition", type Vector2 @SINCE_1_0.0 + LOCAL_DISPLACEMENT, ///< name "localDisplacement", type Vector2 @SINCE_1_0.0 + LOCAL_VELOCITY, ///< name "localVelocity", type Vector2 @SINCE_1_0.0 + PANNING, ///< name "panning", type bool @SINCE_1_0.0 }; }; // Typedefs - typedef Signal< void ( Actor, const PanGesture& ) > DetectedSignalType; ///< Pan gesture detected signal type + typedef Signal< void ( Actor, const PanGesture& ) > DetectedSignalType; ///< Pan gesture detected signal type @SINCE_1_0.0 // Directional Pan - typedef std::pair< Radian, Radian > AngleThresholdPair; ///< Range of angles for a direction - typedef std::vector< AngleThresholdPair > AngleContainer; ///< Group of angular thresholds for all directions + typedef std::pair< Radian, Radian > AngleThresholdPair; ///< Range of angles for a direction @SINCE_1_0.0 static const Radian DIRECTION_LEFT; ///< For a left pan (-PI Radians). static const Radian DIRECTION_RIGHT; ///< For a right pan (0 Radians). @@ -97,47 +110,53 @@ public: public: // Creation & Destruction /** - * @brief Create an uninitialized PanGestureDetector; this can be initialized with PanGestureDetector::New(). + * @brief Creates an uninitialized PanGestureDetector; this can be initialized with PanGestureDetector::New(). * - * Calling member functions with an uninitialized Dali::Object is not allowed. + * Calling member functions with an uninitialized PanGestureDetector handle is not allowed. + * @SINCE_1_0.0 */ PanGestureDetector(); /** - * @brief Create an initialized PanGestureDetector. + * @brief Creates an initialized PanGestureDetector. * - * @return A handle to a newly allocated Dali resource. + * @SINCE_1_0.0 + * @return A handle to a newly allocated Dali resource */ static PanGestureDetector New(); /** - * @brief Downcast an Object handle to PanGestureDetector handle. + * @brief Downcasts a handle to PanGestureDetector handle. * - * If handle points to a PanGestureDetector object the - * downcast produces valid handle. If not the returned handle is left uninitialized. - * @param[in] handle to An object - * @return handle to a PanGestureDetector object or an uninitialized handle + * If handle points to a PanGestureDetector object, the + * downcast produces valid handle. If not, the returned handle is left uninitialized. + * @SINCE_1_0.0 + * @param[in] handle Handle to an object + * @return Handle to a PanGestureDetector object or an uninitialized handle */ static PanGestureDetector DownCast( BaseHandle handle ); /** - * @brief Destructor + * @brief Destructor. * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~PanGestureDetector(); /** * @brief This copy constructor is required for (smart) pointer semantics. * - * @param [in] handle A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] handle A reference to the copied handle */ PanGestureDetector(const PanGestureDetector& handle); /** * @brief This assignment operator is required for (smart) pointer semantics. * - * @param [in] rhs A reference to the copied handle + * @SINCE_1_0.0 + * @param[in] rhs A reference to the copied handle * @return A reference to this */ PanGestureDetector& operator=(const PanGestureDetector& rhs); @@ -147,38 +166,42 @@ public: // Setters /** * @brief This is the minimum number of touches required for the pan gesture to be detected. * - * @param[in] minimum Minimum touches required. + * @SINCE_1_0.0 + * @param[in] minimum Minimum touches required * @pre The gesture detector has been initialized. * @note The default minimum is '1'. */ - void SetMinimumTouchesRequired(unsigned int minimum); + void SetMinimumTouchesRequired(uint32_t minimum); /** * @brief This is the maximum number of touches required for the pan gesture to be detected. * - * @param[in] maximum Maximum touches required. + * @SINCE_1_0.0 + * @param[in] maximum Maximum touches required * @pre The gesture detector has been initialized. * @note The default maximum is '1'. */ - void SetMaximumTouchesRequired(unsigned int maximum); + void SetMaximumTouchesRequired(uint32_t maximum); public: // Getters /** * @brief Retrieves the minimum number of touches required for the pan gesture to be detected. * - * @return The minimum touches required. + * @SINCE_1_0.0 + * @return The minimum touches required * @pre The gesture detector has been initialized. */ - unsigned int GetMinimumTouchesRequired() const; + uint32_t GetMinimumTouchesRequired() const; /** * @brief Retrieves the maximum number of touches required for the pan gesture to be detected. * - * @return The maximum touches required. + * @SINCE_1_0.0 + * @return The maximum touches required * @pre The gesture detector has been initialized. */ - unsigned int GetMaximumTouchesRequired() const; + uint32_t GetMaximumTouchesRequired() const; public: // Directional Panning @@ -200,9 +223,11 @@ public: // Directional Panning * If an angle of 0.0 degrees is specified and the threshold is 45 degrees then the acceptable * direction range is from -45 to 45 degrees. * - * @param[in] angle The angle that pan should be allowed. - * @param[in] threshold The threshold around that angle. + * @SINCE_1_0.0 + * @param[in] angle The angle that pan should be allowed + * @param[in] threshold The threshold around that angle * + * @pre The gesture detector has been initialized. * @note The angle added using this API is only checked when the gesture first starts, after that, * this detector will emit the gesture regardless of what angle the pan is moving. * @note The user can add as many angles as they require. @@ -212,7 +237,6 @@ public: // Directional Panning * @note If no threshold is provided, then the default threshold (PI * 0.25) is used. * @note If the threshold is greater than PI, then PI will be used as the threshold. * - * @pre The gesture detector has been initialized. */ void AddAngle( Radian angle, Radian threshold = DEFAULT_THRESHOLD ); @@ -222,8 +246,11 @@ public: // Directional Panning * In other words, if 0 is requested, then PI will also be added so that we have both left and * right scrolling. * - * @param[in] direction The direction of panning required. - * @param[in] threshold The threshold. + * @SINCE_1_0.0 + * @param[in] direction The direction of panning required + * @param[in] threshold The threshold + * + * @pre The gesture detector has been initialized. * * @note If a direction outside the range above is given, then it is wrapped within the range, i.e. * 190 degrees becomes -170 degrees and 370 degrees becomes 10 degrees. @@ -231,25 +258,36 @@ public: // Directional Panning * @note If the threshold is greater than PI, then PI will be used as the threshold. * @note As long as you specify the type, you can also pass in a Dali::Degree to this method. * - * @pre The gesture detector has been initialized. - * * @see AddAngle */ void AddDirection( Radian direction, Radian threshold = DEFAULT_THRESHOLD ); /** - * @brief Returns the container of all the angles this pan gesture detector emits a signal. + * @brief Returns the count of angles that this pan gesture detector emits a signal. * - * @return a const reference to the container of all the angles. + * @SINCE_1_0.0 + * @return The count * @pre The gesture detector has been initialized. */ - const AngleContainer& GetAngles() const; + size_t GetAngleCount() const; + + /** + * @brief Returns the angle by index that this pan gesture detector emits a signal. + * + * @SINCE_1_0.0 + * @param[in] index The angle's index + * @return An angle threshold pair, or a zero valued angle pair when index is invalid + * @pre The gesture detector has been initialized. + * @pre The index is less than GetAngleCount() + */ + AngleThresholdPair GetAngle(size_t index) const; /** * @brief Clears any directional angles that are used by the gesture detector. * * After this, the pan gesture * will be emitted for a pan in ANY direction. + * @SINCE_1_0.0 * @pre The gesture detector has been initialized. */ void ClearAngles(); @@ -257,7 +295,8 @@ public: // Directional Panning /** * @brief Removes the angle specified from the container. * - * @param[in] angle The angle to remove. + * @SINCE_1_0.0 + * @param[in] angle The angle to remove * @pre The gesture detector has been initialized. * @note This will only remove the first instance of the angle found from the container. * @note If an angle outside the range in AddAngle() is given, then the value is wrapped within @@ -268,7 +307,8 @@ public: // Directional Panning /** * @brief Removes the two angles that make up the direction from the container. * - * @param[in] direction The direction to remove. + * @SINCE_1_0.0 + * @param[in] direction The direction to remove * @pre The gesture detector has been initialized. * @note If a direction outside the range in AddAngle() is given, then the value is wrapped within * the range and that is removed. @@ -284,8 +324,9 @@ public: // Signals * @code * void YourCallbackName( Actor actor, const PanGesture& gesture ); * @endcode + * @SINCE_1_0.0 + * @return The signal to connect to * @pre The gesture detector has been initialized. - * @return The signal to connect to. */ DetectedSignalType& DetectedSignal(); @@ -294,22 +335,30 @@ public: // Pan Properties Setters /** * @brief Allows setting of the pan properties that are returned in constraints. * - * @param[in] pan The pan gesture to set. - *@note If a normal pan is taking place, then any value set is ignored. + * @SINCE_1_0.0 + * @param[in] pan The pan gesture to set + * @note If a normal pan is taking place, then any value set is ignored. */ static void SetPanGestureProperties( const PanGesture& pan ); public: // Not intended for Application developers + /// @cond internal /** - * @brief This constructor is used by Dali New() methods. + * @brief This constructor is used by PanGestureDetector::New() methods. * - * @param [in] internal A pointer to a newly allocated Dali resource. + * @SINCE_1_0.0 + * @param[in] internal A pointer to a newly allocated Dali resource */ explicit DALI_INTERNAL PanGestureDetector(Internal::PanGestureDetector* internal); + /// @endcond }; +/** + * @} + */ + } // namespace Dali #endif // __DALI_PAN_GESTURE_DETECTOR_H__