[3.0] Exclude internal tag module in Public API reference

[platform/core/uifw/dali-core.git] / dali / public-api / animation / linear-constrainer.h

diff --git a/dali/public-api/animation/linear-constrainer.h b/dali/public-api/animation/linear-constrainer.h
index 037533d..4ca5a40 100644 (file)
--- a/dali/public-api/animation/linear-constrainer.h
+++ b/dali/public-api/animation/linear-constrainer.h
@@ -38,12 +38,21 @@ namespace Internal DALI_INTERNAL
 }
 
 /**
- * @brief
+ * @brief LinearConstrainer applies constraints to objects given a linear map.
  *
- * LinearConstrainer applies constraints to objects given a linear map.
  * A linear map is defined by a set of value-progress pairs.
  * Progress must be normalized between [0,1]. If no progress is defined, the values
  * are considered to be equally spaced along the x axis.
+ *
+ * Basically, a linear constrainer allows constraining a property to another property
+ * with the changes mapped over a certain range. For example, if you want to change the
+ * opacity of an actor depending on its position along the X-axis, so that it’s fully
+ * transparent on the edges and fully opaque in the center. To do this, an array with
+ * values, 0.0f, 1.0f, 0.0f, is created, which means that there are 3 control points.
+ * You can add as many control points as you want, but they will be linearly spaced.
+ * Then you can apply the linear constrainer by using the alpha of the actor as the
+ * target and the source as the actor’s position.
+ * @SINCE_1_0.0
  */
 class DALI_IMPORT_API LinearConstrainer : public Handle
 {
@@ -51,38 +60,42 @@ public:
 
   /**
    * @brief An enumeration of properties belonging to the LinearConstrainer class.
+   * @SINCE_1_0.0
    */
   struct Property
   {
     enum
     {
-      VALUE     = DEFAULT_OBJECT_PROPERTY_START_INDEX,  ///< name "value" type Array of float
-      PROGRESS,                                         ///< name "progress" type Array of float
+      VALUE     = DEFAULT_OBJECT_PROPERTY_START_INDEX,  ///< name "value" type Array of float @SINCE_1_0.0
+      PROGRESS,                                         ///< name "progress" type Array of float @SINCE_1_0.0
     };
   };
 
   /**
    * @brief Create an initialized LinearConstrainer handle.
    *
-   * @return a handle to a newly allocated Dali resource.
+   * @SINCE_1_0.0
+   * @return A handle to a newly allocated Dali resource.
    */
   static LinearConstrainer New();
 
   /**
-   * @brief Downcast an Object handle to LinearConstrainer handle.
+   * @brief Downcast a handle to LinearConstrainer handle.
    *
    * If handle points to a LinearConstrainer object the downcast produces
    * valid handle. If not the returned handle is left uninitialized.
-   * @param[in] handle to An object
-   * @return handle to a LinearConstrainer object or an uninitialized handle
+   * @SINCE_1_0.0
+   * @param[in] handle Handle to an object
+   * @return Handle to a LinearConstrainer object or an uninitialized handle
    */
   static LinearConstrainer DownCast( BaseHandle handle );
 
   /**
    * @brief Create an uninitialized LinearConstrainer handle.
    *
-   * This can be initialized with PathConstrainer::New(). Calling member
-   * functions with an uninitialized Dali::Object is not allowed.
+   * This can be initialized with @ref LinearConstrainer::New
+   * Calling member functions with an uninitialized LinearConstrainer handle is not allowed.
+   * @SINCE_1_0.0
    */
   LinearConstrainer();
 
@@ -90,12 +103,14 @@ public:
    * @brief Destructor
    *
    * This is non-virtual since derived Handle types must not contain data or virtual methods.
+   * @SINCE_1_0.0
    */
   ~LinearConstrainer();
 
   /**
    * @brief This copy constructor is required for (smart) pointer semantics.
    *
+   * @SINCE_1_0.0
    * @param [in] handle A reference to the copied handle
    */
   LinearConstrainer(const LinearConstrainer& handle);
@@ -103,6 +118,7 @@ public:
   /**
    * @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
    */
@@ -111,27 +127,31 @@ public:
   /**
    * @brief Applies the linear constraint to the target property
    *
+   * @SINCE_1_0.0
    * @param[in] target Property to be constrained
-   * @param[in] source Property used as parameter for the path
+   * @param[in] source Property used as parameter for the linear map
    * @param[in] range The range of values in the source property which will be mapped to [0,1]
-   * @param[in] wrap Wrapping domain. Source property will be wrapped in the domain [wrap.x,wrap.y] before mapping to [0,1]
+   * @param[in] wrap Wrapping domain. Source property will be wrapped in the domain [wrap.x,wrap.y] before mapping to [0,1]. See cfloat.h for FLT_MAX
    */
   void Apply( Dali::Property target, Dali::Property source, const Vector2& range, const Vector2& wrap = Vector2(-FLT_MAX, FLT_MAX) );
 
   /**
    * @brief Removes the linear constraint in the target object
    *
+   * @SINCE_1_0.0
    * @param[in] target A handle to an object constrained by the LinearConstrainer
    */
   void Remove( Dali::Handle& target );
 
 public: // Not intended for application developers
   /**
-   * @brief This constructor is used by Dali::New() methods.
+   * @internal
+   * @brief This constructor is used by LinearConstrainer::New() methods.
    *
-   * @param[in] pathConstrainer A pointer to an internal PathConstrainer resource
+   * @SINCE_1_0.0
+   * @param[in] internal A pointer to an internal LinearConstrainer resource
    */
-  explicit DALI_INTERNAL LinearConstrainer(Internal::LinearConstrainer* pathConstrainer);
+  explicit DALI_INTERNAL LinearConstrainer(Internal::LinearConstrainer* internal);
 };
 
 /**