X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fevents%2Fpan-gesture-detector.h;h=72f688e66787fbf6bd1f90163391d87bf809ddab;hb=refs%2Fchanges%2F16%2F83116%2F1;hp=734dc419fa7abafac2fddcbbb893565b738daf72;hpb=52d998719683ba91c5f7fbd2c9da544f51317891;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 734dc41..72f688e 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) 2015 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. @@ -20,9 +20,10 @@ // INTERNAL INCLUDES #include -#include +#include +#include -namespace Dali DALI_IMPORT_API +namespace Dali { struct Radian; @@ -35,6 +36,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. @@ -49,18 +55,41 @@ struct PanGesture; * detector.SetMaximumTouchesRequired(2); * @endcode * + * @SINCE_1_0.0 * @see PanGesture + * + * Signals + * | %Signal Name | Method | + * |--------------|-----------------------| + * | panDetected | @ref DetectedSignal() | */ -class PanGestureDetector : public GestureDetector +class DALI_IMPORT_API PanGestureDetector : public GestureDetector { public: + /** + * @brief An enumeration of properties belonging to the PanGestureDetector class. + * @SINCE_1_0.0 + */ + struct Property + { + enum + { + 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 SignalV2< void (Actor, PanGesture) > DetectedSignalV2; ///< 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). @@ -71,45 +100,32 @@ public: static const Radian DEFAULT_THRESHOLD; ///< The default threshold is PI * 0.25 radians (or 45 degrees). - /// @name Properties - /** @{ */ - static const Property::Index SCREEN_POSITION; ///< name "screen-position", type VECTOR2 - static const Property::Index SCREEN_DISPLACEMENT; ///< name "screen-displacement", type VECTOR2 - static const Property::Index SCREEN_VELOCITY; ///< name "screen-velocity", type VECTOR2 - static const Property::Index LOCAL_POSITION; ///< name "local-position", type VECTOR2 - static const Property::Index LOCAL_DISPLACEMENT; ///< name "local-displacement", type VECTOR2 - static const Property::Index LOCAL_VELOCITY; ///< name "local-velocity", type VECTOR2 - static const Property::Index PANNING; ///< name "panning", type BOOLEAN - /** @} */ - - /// @name Signals - /** @{ */ - static const char* const SIGNAL_PAN_DETECTED; ///< name "pan-detected", @see DetectedSignal() - /** @} */ - public: // Creation & Destruction /** * @brief Create 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. * + * @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 Downcast 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 + * @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 ); @@ -117,12 +133,14 @@ public: // Creation & Destruction * @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. * + * @SINCE_1_0.0 * @param [in] handle A reference to the copied handle */ PanGestureDetector(const PanGestureDetector& handle); @@ -130,26 +148,18 @@ public: // Creation & Destruction /** * @brief This assignment operator is required for (smart) pointer semantics. * + * @SINCE_1_0.0 * @param [in] rhs A reference to the copied handle * @return A reference to this */ PanGestureDetector& operator=(const PanGestureDetector& rhs); - /** - * @brief This method is defined to allow assignment of the NULL value, - * and will throw an exception if passed any other value. - * - * Assigning to NULL is an alias for Reset(). - * @param [in] rhs A NULL pointer - * @return A reference to this handle - */ - PanGestureDetector& operator=(BaseHandle::NullType* rhs); - public: // Setters /** * @brief This is the minimum number of touches required for the pan gesture to be detected. * + * @SINCE_1_0.0 * @param[in] minimum Minimum touches required. * @pre The gesture detector has been initialized. * @note The default minimum is '1'. @@ -159,6 +169,7 @@ public: // Setters /** * @brief This is the maximum number of touches required for the pan gesture to be detected. * + * @SINCE_1_0.0 * @param[in] maximum Maximum touches required. * @pre The gesture detector has been initialized. * @note The default maximum is '1'. @@ -170,6 +181,7 @@ public: // Getters /** * @brief Retrieves the minimum number of touches required for the pan gesture to be detected. * + * @SINCE_1_0.0 * @return The minimum touches required. * @pre The gesture detector has been initialized. */ @@ -178,6 +190,7 @@ public: // Getters /** * @brief Retrieves the maximum number of touches required for the pan gesture to be detected. * + * @SINCE_1_0.0 * @return The maximum touches required. * @pre The gesture detector has been initialized. */ @@ -203,9 +216,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. * + * @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. @@ -215,7 +230,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 ); @@ -225,34 +239,47 @@ 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. * + * @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. * @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. * @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. + * + * @SINCE_1_0.0 + * @return The count. + * @pre The gesture detector has been initialized. + */ + size_t GetAngleCount() const; + + /** + * @brief Returns the angle by index that this pan gesture detector emits a signal. * - * @return a const reference to the container of all the angles. + * @SINCE_1_0.0 + * @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() */ - const AngleContainer& GetAngles() const; + 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(); @@ -260,6 +287,7 @@ public: // Directional Panning /** * @brief Removes the angle specified from the container. * + * @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. @@ -271,6 +299,7 @@ public: // Directional Panning /** * @brief Removes the two angles that make up the direction from the container. * + * @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 @@ -285,34 +314,41 @@ public: // Signals * * A callback of the following type may be connected: * @code - * void YourCallbackName(Actor actor, PanGesture gesture); + * void YourCallbackName( Actor actor, const PanGesture& gesture ); * @endcode - * @pre The gesture detector has been initialized. + * @SINCE_1_0.0 * @return The signal to connect to. + * @pre The gesture detector has been initialized. */ - DetectedSignalV2& DetectedSignal(); + DetectedSignalType& DetectedSignal(); public: // Pan Properties Setters /** * @brief Allows setting of the pan properties that are returned in constraints. * + * @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. + * @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 /** - * @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); }; +/** + * @} + */ + } // namespace Dali #endif // __DALI_PAN_GESTURE_DETECTOR_H__