X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fobject%2Fhandle.h;h=eb65c5a2157f14a1e59ef986bf3e9dafa693f49b;hb=75cd170d0e46bbb1294f19bd8a247f5c73b18c61;hp=6a7963a213b876c409c816645e26ff222dbf41ab;hpb=f468c03113e03c0d23564032fd5e39d82947f18a;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/object/handle.h b/dali/public-api/object/handle.h index 6a7963a..eb65c5a 100644 --- a/dali/public-api/object/handle.h +++ b/dali/public-api/object/handle.h @@ -1,8 +1,8 @@ -#ifndef __DALI_HANDLE_H__ -#define __DALI_HANDLE_H__ +#ifndef DALI_HANDLE_H +#define DALI_HANDLE_H /* - * Copyright (c) 2014 Samsung Electronics Co., Ltd. + * Copyright (c) 2020 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. @@ -19,18 +19,26 @@ */ // EXTERNAL INCLUDES +#include // uint32_t #include // INTERNAL INCLUDES #include #include +#include +#include +#include #include #include -#include #include +#include namespace Dali { +/** + * @addtogroup dali_core_object + * @{ + */ class Constraint; class PropertyNotification; @@ -43,13 +51,14 @@ class 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 DALI_IMPORT_API Handle : public BaseHandle +class DALI_CORE_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 { @@ -57,18 +66,24 @@ 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, }; -public: + /** + * @brief PropertySetSignal function prototype for signal handler. Called when a property is set on this object. + */ + using PropertySetSignalType = Signal; +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. @@ -82,128 +97,181 @@ public: * handle = SomeClass::New(); // now initialized * handle.SomeMethod(); // safe * @endcode + * @SINCE_1_0.0 */ Handle(); /** - * @brief Create a new object. + * @brief Creates a new object. * - * @return A handle to a newly allocated 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 + * @brief Template to create a derived handle and set properties on it. + * + * Marked as DALI_NO_EXPORT_API to prevent internal usage exporting symbols. + * @SINCE_1_9.27 + * @tparam T The derived class to create + * @param[in] properties The properties to set + */ + template + static DALI_NO_EXPORT_API Type New(const Property::Map& properties) + { + Type handle = Type::New(); + handle.SetProperties(properties); + return handle; + } + + /** + * @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 ); + Handle& operator=(const Handle& rhs); + + /** + * @brief Move constructor. + * + * @SINCE_1_9.22 + * @param[in] rhs A reference to the moved handle + */ + Handle(Handle&& rhs); + + /** + * @brief Move assignment operator. + * + * @SINCE_1_9.22 + * @param[in] rhs A reference to the moved handle + * @return A reference to this handle + */ + Handle& operator=(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 ); + static Handle DownCast(BaseHandle handle); /** - * @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; + uint32_t 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 */ - 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. + * @brief Query the index of a property using the given key. * - * @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. + * @SINCE_1_9.27 + * @param[in] key The key of the property to search for. (The name or integer key provided to + * RegisterProperty()). + * @return the matching property index of the key, or Property::INVALID_INDEX if no + * property matches the given key. */ - Property::Index GetPropertyIndex( const std::string& name ) const; + Property::Index GetPropertyIndex(Property::Key key) 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. * * 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, const Property::Value& propertyValue ); + void SetProperty(Property::Index index, Property::Value propertyValue); /** - * @brief Register a new animatable property. + * @brief Registers a new animatable 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. @@ -219,16 +287,61 @@ public: * - Property::MATRIX3 * - Property::MATRIX * - Property::ROTATION - * @param [in] name The name of the property. - * @param [in] propertyValue The new value of the property. + * @note If a property with the desired name already exists, then the value given is just set. + */ + Property::Index RegisterProperty(std::string_view name, Property::Value propertyValue); + + /** + * @brief Register a new animatable property with an integer key. + * + * @SINCE_1_9.27 + * @param[in] key The integer key of the property. + * @param[in] name The text key 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 and keys + * are expected to be unique, but this is not enforced. Property indices are unique + * to each registered custom property in a given object. + * + * @note 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 The returned property index is not the same as the integer key (though it + * shares a type) + * + * This version of RegisterProperty associates both an integer key and the text key + * with the property, allowing for lookup of the property index by either key or name + * ( which is useful when other classes know the key but not the name ) + * + * @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( const std::string& name, const Property::Value& propertyValue ); + Property::Index RegisterProperty(Property::Index key, + std::string_view name, + 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. * @note Only the following types can be animated: @@ -241,112 +354,206 @@ public: * - Property::MATRIX3 * - Property::MATRIX * - Property::ROTATION - * @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 If a property with the desired name already exists, then the value given is just set. */ - Property::Index RegisterProperty( const std::string& name, const Property::Value& propertyValue, Property::AccessMode accessMode ); + Property::Index RegisterProperty(std::string_view name, 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 + template + T GetProperty(Property::Index index) const { Property::Value value = GetProperty(index); - return T( value.Get() ); + return T(value.Get()); } /** - * @brief Retrieve all the property indices for this object (including custom properties). + * @brief Retrieves the latest value of the property from the scene-graph. * - * @param[out] indices A container of property indices for this object. - * @note the added container is cleared + * @SINCE_1_2.41 + * @param[in] index The index of the property + * @return The property value */ - void GetPropertyIndices( Property::IndexContainer& indices ) const; + Property::Value GetCurrentProperty(Property::Index index) const; /** - * @brief Add a property notification to this object. + * @brief Convenience function for obtaining the current value of a property of a known type. * - * @param [in] index The index of the property. - * @param [in] condition The notification will be triggered when this condition is satisfied. + * @SINCE_1_2.41 + * @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). + */ + template + T GetCurrentProperty(Property::Index index) const + { + Property::Value value = GetCurrentProperty(index); + + return T(value.Get()); + } + + /** + * @brief Sets all the properties in the given property map. * - * @return A handle to the newly created PropertyNotification + * @SINCE_1_9.27 + * @param[in] properties The properties to set */ - PropertyNotification AddPropertyNotification( Property::Index index, - const PropertyCondition& condition ); + void SetProperties(const Property::Map& properties); /** - * @brief Add a property notification to this object. + * @brief Retrieves all the properties and the values for this object + * + * @SINCE_1_9.27 + * @param[out] properties A map which is populated with the index-value pairs * - * @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. + * @note The properties map will be cleared by this method first. + */ + void GetProperties(Property::Map& properties); + + /** + * @brief Retrieves all the property indices for this object (including custom properties). + * + * @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 Determine if the custom property index exists on this object without throwing a Dali::Exception. + * + * @SINCE_1_9.27 + * @note This does not check default properties. + * @param[in] index The index of the property to test for + */ + bool DoesCustomPropertyExist(Property::Index index); + + /** + * @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); + + /** + * @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 Remove all constraints from an Object. + * @brief Removes all constraints from an Object. * + * @SINCE_1_0.0 * @pre The object has been initialized. */ void RemoveConstraints(); /** - * @brief Remove all the constraint from the Object with a matching tag. + * @brief Removes all the constraint from the Object with a matching tag. * - * @pre The Object has been initialized. + * @SINCE_1_0.0 * @param[in] tag The tag of the constraints which will be removed + * @pre The Object has been initialized. + */ + void RemoveConstraints(uint32_t tag); + + /** + * @brief Index operator, using integer lookup. + * + * Returns an object that can be assigned to or cast from, enabling + * the indexed property to be either read or written. + * + * @param[in] index The index of the property to access. + * @return indirect value. Should have shorter scope than the handle */ - void RemoveConstraints( unsigned int tag ); + IndirectValue operator[](Property::Index index); + + /** + * @brief Index operator, using name lookup. + * + * Returns an object that can be assigned to or cast from, enabling + * the named property to be either read or written. + * + * @param[in] name The name of the property to access. + * @return indirect value. Should have shorter scope than the handle + */ + IndirectValue operator[](const std::string& name); + +public: // Signals + /** + * @brief Get a signal when a property is set on this object through the API (i.e. not when animating) + * + * @SINCE_1_9.27 + * @return The signal to attach a connection to. + */ + PropertySetSignalType& PropertySetSignal(); }; +/** + * @brief This namespace provides a convenient function to create an object with a custom "weight" property. + * @SINCE_1_0.0 + */ namespace WeightObject { - -DALI_IMPORT_API extern const Property::Index WEIGHT; ///< name "weight", type FLOAT +DALI_CORE_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. + * @SINCE_1_0.0 + * @return A handle to a newly allocated object */ -DALI_IMPORT_API Handle New(); +DALI_CORE_API Handle New(); } // namespace WeightObject +/** + * @} + */ } // namespace Dali -#endif // __DALI_HANDLE_H__ +#endif // DALI_HANDLE_H