X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fobject%2Fhandle.h;h=0dd7eb36fc31cffed00ce206755c0f70baad3f67;hb=44ee0cc4fac620903fdf198867f645a2d5dbf075;hp=a0b9e3207d27f8902f6b8ae112be841e5f06502a;hpb=d731255c514247b1cb4a5f60e3d841b072e2d464;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/object/handle.h b/dali/public-api/object/handle.h index a0b9e32..0dd7eb3 100644 --- a/dali/public-api/object/handle.h +++ b/dali/public-api/object/handle.h @@ -32,6 +32,8 @@ namespace Dali { +class ActiveConstraint; +class Constraint; class PropertyNotification; class PropertyCondition; @@ -41,7 +43,7 @@ class Object; } /** - * @brief Dali::Handle is a handle to an internal property owning Dali object. + * @brief Dali::Handle is a handle to an internal property owning Dali object that can have constraints applied to it. */ class DALI_IMPORT_API Handle : public BaseHandle { @@ -67,7 +69,7 @@ public: * * @param [in] handle A pointer to a newly allocated Dali resource */ - Handle(Dali::Internal::Object* handle); + Handle( Dali::Internal::Object* handle ); /** * @brief This constructor provides an uninitialized Dali::Handle. @@ -85,6 +87,13 @@ public: Handle(); /** + * @brief Create a new object. + * + * @return A handle to a newly allocated object. + */ + static Handle New(); + + /** * @brief Dali::Handle is intended as a base class * * This is non-virtual since derived Handle types must not contain data or virtual methods. @@ -96,7 +105,7 @@ public: * * @param [in] handle A reference to the copied handle */ - Handle(const Handle& handle); + Handle( const Handle& handle ); /** * @brief This assignment operator is required for (smart) pointer semantics. @@ -104,17 +113,7 @@ public: * @param [in] rhs A reference to the copied handle * @return A reference to this */ - Handle& operator=(const Handle& 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 - */ - Handle& operator=(BaseHandle::NullType* rhs); + Handle& operator=( const Handle& rhs ); /** * @brief Downcast to a handle. @@ -125,15 +124,15 @@ public: */ static Handle DownCast( BaseHandle handle ); -public: - /** * @brief Query whether an handle supports a given capability. * * @param[in] capability The queried capability. * @return True if the capability is supported. */ - bool Supports(Capability capability) const; + bool Supports( Capability capability ) const; + + // Properties /** * @brief Query how many properties are provided by an handle. @@ -149,15 +148,16 @@ public: * @param [in] index The index of the property. * @return The name of the property. */ - const std::string& GetPropertyName(Property::Index index) const; + std::string GetPropertyName( Property::Index index ) const; /** * @brief Query the index of a property. + * Returns the first property index that matches the given name exactly. * * @param [in] name The name of the property. * @return The index of the property, or Property::INVALID_INDEX if no property exists with the given name. */ - Property::Index GetPropertyIndex(std::string name) const; + Property::Index GetPropertyIndex( const std::string& name ) const; /** * @brief Query whether a property can be set using SetProperty(). @@ -166,7 +166,7 @@ public: * @param [in] index The index of the property. * @return True if the property is writable. */ - bool IsPropertyWritable(Property::Index index) const; + bool IsPropertyWritable( Property::Index index ) const; /** * @brief Query whether a writable property can be the target of an animation or constraint. @@ -174,7 +174,7 @@ public: * @param [in] index The index of the property. * @return True if the property is animatable. */ - bool IsPropertyAnimatable(Property::Index index) const; + bool IsPropertyAnimatable( Property::Index index ) const; /** * @brief Query whether a property can be used as in input to a constraint. @@ -182,7 +182,7 @@ public: * @param [in] index The index of the property. * @return True if the property can be used as a constraint input. */ - bool IsPropertyAConstraintInput(Property::Index index) const; + bool IsPropertyAConstraintInput( Property::Index index ) const; /** * @brief Query the type of a property. @@ -190,23 +190,26 @@ public: * @param [in] index The index of the property. * @return The type of the property. */ - Property::Type GetPropertyType(Property::Index index) const; + Property::Type GetPropertyType( Property::Index index ) const; /** * @brief Set the value of an existing property. * - * @pre Handle::IsPropertyWritable(index) returns true. + * Property should be write-able. Setting a read-only property is a no-op. * @pre The property types match i.e. propertyValue.GetType() is equal to GetPropertyType(index). * @param [in] index The index of the property. * @param [in] propertyValue The new value of the property. */ - void SetProperty(Property::Index index, Property::Value propertyValue); + void SetProperty( Property::Index index, const Property::Value& propertyValue ); /** * @brief Register a new animatable property. * - * @pre The handle supports dynamic properties i.e. Supports(Handle::DYNAMIC_PROPERTIES) returns true. - * @pre name is unused i.e. GetPropertyIndex(name) returns PropertyIndex::INVALID. + * @pre The object supports dynamic properties i.e. Supports(Handle::DYNAMIC_PROPERTIES) returns true. + * Property names are expected to be unique, but this is not enforced. + * Property indices are unique to each registered custom property in a given object. + * returns Property::INVALID_INDEX if registration failed. This can happen if you try to register + * animatable property on an object that does not have scene graph object. * @note Only the following types can be animated: * - Property::BOOLEAN * - Property::FLOAT @@ -219,9 +222,9 @@ public: * - Property::ROTATION * @param [in] name The name of the property. * @param [in] propertyValue The new value of the property. - * @return The index of the property + * @return The index of the property or Property::INVALID_INDEX if registration failed */ - Property::Index RegisterProperty(std::string name, Property::Value propertyValue); + Property::Index RegisterProperty( const std::string& name, const Property::Value& propertyValue ); /** * @brief Register a new property. @@ -244,7 +247,7 @@ public: * @param [in] accessMode The property access mode (writable, animatable etc). * @return The index of the property */ - Property::Index RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode); + Property::Index RegisterProperty( const std::string& name, const Property::Value& propertyValue, Property::AccessMode accessMode ); /** * @brief Retrieve a property value. @@ -252,7 +255,7 @@ public: * @param [in] index The index of the property. * @return The property value. */ - Property::Value GetProperty(Property::Index index) const; + Property::Value GetProperty( Property::Index index ) const; /** * @brief Convenience function for obtaining a property of a known type. @@ -262,7 +265,7 @@ public: * @return The property value. */ template - T GetProperty(Property::Index index) const + T GetProperty( Property::Index index ) const { Property::Value value = GetProperty(index); @@ -285,8 +288,8 @@ public: * * @return A handle to the newly created PropertyNotification */ - PropertyNotification AddPropertyNotification(Property::Index index, - const PropertyCondition& condition); + PropertyNotification AddPropertyNotification( Property::Index index, + const PropertyCondition& condition ); /** * @brief Add a property notification to this object. @@ -297,24 +300,85 @@ public: * * @return A handle to the newly created PropertyNotification */ - PropertyNotification AddPropertyNotification(Property::Index index, - int componentIndex, - const PropertyCondition& condition); + PropertyNotification AddPropertyNotification( Property::Index index, + int componentIndex, + const PropertyCondition& condition ); /** * @brief Remove a property notification from this object. * * @param [in] propertyNotification The propertyNotification to be removed. */ - void RemovePropertyNotification(Dali::PropertyNotification propertyNotification); + void RemovePropertyNotification( Dali::PropertyNotification propertyNotification ); /** * @brief Remove all property notifications from this object. */ void RemovePropertyNotifications(); + // Constraints + + /** + * @brief Constrain one of the properties of an Actor. + * + * @note The constraint will be copied by the Actor. This means that modifying the apply-time etc. + * of the constraint, will not affect actors which are already being constrained. + * @pre The Actor has been initialized. + * @param[in] constraint The constraint to apply. + * @return The active-constraint being applied to the actor. + */ + ActiveConstraint ApplyConstraint( Constraint constraint ); + + /** + * @brief Constrain one of the properties of an Actor, using a custom weight property. + * + * This overload is intended to allow a single weight property to be shared by many constraints + * e.g. call WeightObject::New() once, and pass the return value into every call to ApplyConstraint(). + * @pre The Actor has been initialized. + * @param[in] constraint The constraint to apply. + * @param[in] weightObject An object which is expected to have a float property named "weight". + * @return The active-constraint being applied to the actor. + */ + ActiveConstraint ApplyConstraint( Constraint constraint, Handle weightObject ); + + /** + * @brief Remove one constraint from an Object. + * + * @pre The Object has been initialized. + * @param[in] activeConstraint The active-constraint to remove. + */ + void RemoveConstraint( ActiveConstraint activeConstraint ); + + /** + * @brief Remove all constraints from an Object. + * + * @pre The object has been initialized. + */ + void RemoveConstraints(); + + /** + * @brief Remove all the constraint from the Object with a matching tag. + * + * @pre The Object has been intialized. + * @param[in] tag The tag of the constraints which will be removed + */ + void RemoveConstraints( unsigned int tag ); }; +namespace WeightObject +{ + +DALI_IMPORT_API extern const Property::Index WEIGHT; ///< name "weight", type FLOAT + +/** + * @brief Convenience function to create an object with a custom "weight" property. + * + * @return A handle to a newly allocated object. + */ +DALI_IMPORT_API Handle New(); + +} // namespace WeightObject + } // namespace Dali #endif // __DALI_HANDLE_H__