dali/public-api/object/constrainable.h

   1 #ifndef __DALI_CONSTRAINABLE_H__
   2 #define __DALI_CONSTRAINABLE_H__
   3
   4 /*
   5  * Copyright (c) 2014 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 // INTERNAL INCLUDES
  22 #include <dali/public-api/object/handle.h>
  23 #include <dali/public-api/animation/active-constraint.h>
  24 #include <dali/public-api/animation/constraint.h>
  25
  26 namespace Dali DALI_IMPORT_API
  27 {
  28
  29 namespace Internal
  30 {
  31 class Object;
  32 }
  33
  34 class Constraint;
  35
  36 /**
  37  * @brief Dali::Constrainable is a handle to an internal property owning Dali object that
  38  * can have constraints applied to it.
  39  */
  40 class DALI_IMPORT_API Constrainable : public Handle
  41 {
  42 public:
  43
  44   /**
  45    * @brief Create a constrainable object.
  46    *
  47    * @return A handle to a newly allocated object.
  48    */
  49   static Constrainable New();
  50
  51   /**
  52    * @brief This constructor provides an uninitialized Dali::Constrainable.
  53    *
  54    * This should be initialized with a Dali New() method before use.
  55    * Methods called on an uninitialized Dali::Constrainable will assert.
  56    * @code
  57    * Constrainable handle; // uninitialized
  58    * handle.SomeMethod(); // unsafe! This will assert
  59    *
  60    * handle = SomeClass::New(); // now initialized
  61    * handle.SomeMethod(); // safe
  62    * @endcode
  63    */
  64   Constrainable();
  65
  66   /**
  67    * @brief Downcast a handle to a custom object.
  68    *
  69    * @param[in] handle The handle to cast.
  70    * @return A handle to a custom object or an empty handle.
  71    */
  72   static Constrainable DownCast( BaseHandle handle );
  73
  74   /**
  75    * @brief Dali::Constrainable is intended as a base class
  76    *
  77    * This is non-virtual since derived Handle types must not contain data or virtual methods.
  78    */
  79   ~Constrainable();
  80
  81   /**
  82    * @brief This copy constructor is required for (smart) pointer semantics.
  83    *
  84    * @param [in] handle A reference to the copied handle
  85    */
  86   Constrainable(const Constrainable& handle);
  87
  88   /**
  89    * @brief This assignment operator is required for (smart) pointer semantics.
  90    *
  91    * @param [in] rhs  A reference to the copied handle
  92    * @return A reference to this
  93    */
  94   Constrainable& operator=(const Constrainable& rhs);
  95
  96   /**
  97    * @brief This method is defined to allow assignment of the NULL value,
  98    * and will throw an exception if passed any other value.
  99    *
 100    * Assigning to NULL is an alias for Reset().
 101    * @param [in] rhs  A NULL pointer
 102    * @return A reference to this handle
 103    */
 104   Constrainable& operator=(BaseHandle::NullType* rhs);
 105
 106   /**
 107    * @brief Constrain one of the properties of an Actor.
 108    *
 109    * @note The constraint will be copied by the Actor. This means that modifying the apply-time etc.
 110    * of the constraint, will not affect actors which are already being constrained.
 111    * @pre The Actor has been initialized.
 112    * @param[in] constraint The constraint to apply.
 113    * @return The active-constraint being applied to the actor.
 114    */
 115   ActiveConstraint ApplyConstraint( Constraint constraint );
 116
 117   /**
 118    * @brief Constrain one of the properties of an Actor, using a custom weight property.
 119    *
 120    * This overload is intended to allow a single weight property to be shared by many constraints
 121    * e.g. call WeightObject::New() once, and pass the return value into every call to ApplyConstraint().
 122    * @pre The Actor has been initialized.
 123    * @param[in] constraint The constraint to apply.
 124    * @param[in] weightObject An object which is expected to have a float property named "weight".
 125    * @return The active-constraint being applied to the actor.
 126    */
 127   ActiveConstraint ApplyConstraint( Constraint constraint, Constrainable weightObject );
 128
 129   /**
 130    * @brief Remove one constraint from an Object.
 131    *
 132    * @pre The Object has been intialized.
 133    * @param[in] activeConstraint The active-constraint to remove.
 134    */
 135   void RemoveConstraint(ActiveConstraint activeConstraint);
 136
 137   /**
 138    * @brief Remove all constraints from an Object.
 139    *
 140    * @pre The object has been initialized.
 141    */
 142   void RemoveConstraints();
 143
 144   /**
 145    * @brief Remove all the constraint from the Object with a matching tag.
 146    *
 147    * @pre The Object has been intialized.
 148    * @param[in] tag The tag of the constraints which will be removed
 149    */
 150   void RemoveConstraints( unsigned int tag );
 151
 152 public:
 153
 154   /**
 155    * @brief This constructor is used by Dali New() methods.
 156    *
 157    * @param [in] handle A pointer to a newly allocated Dali resource
 158    */
 159   explicit DALI_INTERNAL Constrainable(Dali::Internal::Object* handle);
 160 };
 161
 162 namespace WeightObject
 163 {
 164
 165 DALI_IMPORT_API extern const Property::Index WEIGHT; ///< name "weight", type FLOAT
 166
 167 /**
 168  * @brief Convenience function to create an object with a custom "weight" property.
 169  *
 170  * @return A handle to a newly allocated object.
 171  */
 172 DALI_IMPORT_API Constrainable New();
 173
 174 } // namespace WeightObject
 175
 176 } // namespace Dali
 177
 178 #endif // __DALI_CONSTRAINABLE_H__