X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fobject%2Fhandle.h;h=e72e6ee091f53b8f043a11490d723ead2fab1b48;hb=72a164cbdc5629c7fc137bf2986b948bd7552cc1;hp=cdee86186d64711f50a7d6bef122193c5a446dc6;hpb=41a8779a0c72ec5efd6e902828ea3a718852b662;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/object/handle.h b/dali/public-api/object/handle.h index cdee861..e72e6ee 100644 --- a/dali/public-api/object/handle.h +++ b/dali/public-api/object/handle.h @@ -2,7 +2,7 @@ #define __DALI_HANDLE_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. @@ -29,9 +29,14 @@ #include #include -namespace Dali DALI_IMPORT_API +namespace Dali { +/** + * @addtogroup dali_core_object + * @{ + */ +class Constraint; class PropertyNotification; class PropertyCondition; @@ -41,14 +46,16 @@ 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. + * @SINCE_1_0.0 */ -class Handle : public BaseHandle +class DALI_IMPORT_API Handle : public BaseHandle { public: /** - * @brief An Handle's capabilities can be queried using Handle::Supports() + * @brief Enumeration for Handle's capabilities that can be queried using Handle::Supports(). + * @SINCE_1_0.0 */ enum Capability { @@ -56,6 +63,7 @@ public: * @brief Some objects support dynamic property creation at run-time. * * New properties are registered by calling RegisterProperty() with an unused property name. + * @SINCE_1_0.0 */ DYNAMIC_PROPERTIES = 0x01, }; @@ -65,9 +73,10 @@ public: /** * @brief This constructor is used by Dali New() methods. * - * @param [in] handle A pointer to a newly allocated Dali resource + * @SINCE_1_0.0 + * @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. @@ -81,168 +90,211 @@ public: * handle = SomeClass::New(); // now initialized * handle.SomeMethod(); // safe * @endcode + * @SINCE_1_0.0 */ Handle(); /** - * @brief Dali::Handle is intended as a base class + * @brief Creates a new object. + * + * @SINCE_1_0.0 + * @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. + * @SINCE_1_0.0 */ ~Handle(); /** * @brief This copy constructor is required for (smart) pointer semantics. * - * @param [in] handle A reference to the copied handle + * @SINCE_1_0.0 + * @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. * - * @param [in] rhs A reference to the copied handle + * @SINCE_1_0.0 + * @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. + * @brief Downcasts to a handle. * - * If not the returned handle is left uninitialized. + * If not, the returned handle is left uninitialized. + * @SINCE_1_0.0 * @param[in] handle to An object * @return handle or an uninitialized handle */ static Handle DownCast( BaseHandle handle ); -public: - /** - * @brief Query whether an handle supports a given capability. + * @brief Queries whether an handle supports a given capability. * - * @param[in] capability The queried capability. - * @return True if the capability is supported. + * @SINCE_1_0.0 + * @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. + * @brief Queries how many properties are provided by an handle. * * This may vary between instances of a class, if dynamic properties are supported. - * @return The number of properties. + * @SINCE_1_0.0 + * @return The number of properties */ unsigned int GetPropertyCount() const; /** - * @brief Query the name of a property. + * @brief Queries the name of a property. * - * @param [in] index The index of the property. - * @return The name of the property. + * @SINCE_1_0.0 + * @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. + * @brief Queries the index of a property. * - * @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. + * Returns the first property index that matches the given name exactly. + * + * @SINCE_1_0.0 + * @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(). + * @brief Queries whether a property can be set using SetProperty(). * + * @SINCE_1_0.0 + * @param[in] index The index of the property + * @return True if the property is writable * @pre Property::INVALID_INDEX < index. - * @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. + * @brief Queries whether a writable property can be the target of an animation or constraint. * - * @param [in] index The index of the property. - * @return True if the property is animatable. + * @SINCE_1_0.0 + * @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. + * @brief Queries whether a property can be used as in input to a constraint. * - * @param [in] index The index of the property. - * @return True if the property can be used as a constraint input. + * @SINCE_1_0.0 + * @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. + * @brief Queries the type of a property. * - * @param [in] index The index of the property. - * @return The type of the property. + * @SINCE_1_0.0 + * @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. + * @brief Sets 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. + * @SINCE_1_0.0 + * @param[in] index The index of the property + * @param[in] propertyValue The new value of the property * @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 property. + * @brief Registers 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. - * @param [in] name The name of the property. - * @param [in] propertyValue The new value of the property. - * @return The index of the property + * @SINCE_1_0.0 + * @param[in] name The name of the property + * @param[in] propertyValue The new value of the property + * @return The index of the property or Property::INVALID_INDEX if registration failed + * @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 + * - Property::INTEGER + * - Property::VECTOR2 + * - Property::VECTOR3 + * - Property::VECTOR4 + * - Property::MATRIX3 + * - Property::MATRIX + * - Property::ROTATION + * @note If a property with the desired name already exists, then the value given is just set. */ - 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. + * @brief Registers a new property. * * Properties can be set as non animatable using property attributes. + * @SINCE_1_0.0 + * @param[in] name The name of the property + * @param[in] propertyValue The new value of the property + * @param[in] accessMode The property access mode (writable, animatable etc) + * @return The index of the 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. - * @param [in] name The name of the property. - * @param [in] propertyValue The new value of the property. - * @param [in] accessMode The property access mode (writable, animatable etc). - * @return The index of the property + * @note Only the following types can be animated: + * - Property::BOOLEAN + * - Property::FLOAT + * - Property::INTEGER + * - Property::VECTOR2 + * - Property::VECTOR3 + * - Property::VECTOR4 + * - Property::MATRIX3 + * - Property::MATRIX + * - Property::ROTATION + * @note If a property with the desired name already exists, then the value given is just set. */ - 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. + * @brief Retrieves a property value. * - * @param [in] index The index of the property. - * @return The property value. + * @SINCE_1_0.0 + * @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. * + * @SINCE_1_0.0 + * @param[in] index The index of the property + * @return The property value * @pre The property types match i.e. PropertyTypes::Get() is equal to GetPropertyType(index). - * @param [in] index The index of the property. - * @return The property value. */ template - T GetProperty(Property::Index index) const + T GetProperty( Property::Index index ) const { Property::Value value = GetProperty(index); @@ -250,51 +302,91 @@ public: } /** - * @brief Retrieve all the property indices for this object (including custom properties). + * @brief Retrieves all the property indices for this object (including custom properties). * - * @param[out] indices A container of property indices for this object. - * @note the added container is cleared + * @SINCE_1_0.0 + * @param[out] indices A container of property indices for this object + * @note The added container is cleared. */ void GetPropertyIndices( Property::IndexContainer& indices ) const; /** - * @brief Add a property notification to this object. - * - * @param [in] index The index of the property. - * @param [in] condition The notification will be triggered when this condition is satisfied. + * @brief Adds a property notification to this object. * + * @SINCE_1_0.0 + * @param[in] index The index of the property + * @param[in] condition The notification will be triggered when this condition is satisfied * @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. - * - * @param [in] index The index of the property. - * @param [in] componentIndex Index to the component of a complex property such as a Vector - * @param [in] condition The notification will be triggered when this condition is satisfied. + * @brief Adds a property notification to this object. * + * @SINCE_1_0.0 + * @param[in] index The index of the property + * @param[in] componentIndex Index to the component of a complex property such as a Vector + * @param[in] condition The notification will be triggered when this condition is satisfied * @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. + * @brief Removes a property notification from this object. * - * @param [in] propertyNotification The propertyNotification to be removed. + * @SINCE_1_0.0 + * @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. + * @brief Removes all property notifications from this object. + * @SINCE_1_0.0 */ void RemovePropertyNotifications(); + // Constraints + + /** + * @brief Removes all constraints from an Object. + * + * @SINCE_1_0.0 + * @pre The object has been initialized. + */ + void RemoveConstraints(); + + /** + * @brief Removes all the constraint from the Object with a matching tag. + * + * @SINCE_1_0.0 + * @param[in] tag The tag of the constraints which will be removed + * @pre The Object has been initialized. + */ + 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. + * + * @SINCE_1_0.0 + * @return A handle to a newly allocated object + */ +DALI_IMPORT_API Handle New(); + +} // namespace WeightObject + +/** + * @} + */ } // namespace Dali #endif // __DALI_HANDLE_H__