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