X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=dali%2Fpublic-api%2Fobject%2Fhandle.h;h=1e4130a534bb55fc4788a3ffdb895e09973623bc;hb=c4750afbf79f15bf71e2aa8ef54f84750463aae2;hp=d7dc63f42e8aaa18cc4bc44bf855e432396c2b80;hpb=444ee3f60f12a23aca07059c5e1109f26613e44e;p=platform%2Fcore%2Fuifw%2Fdali-core.git diff --git a/dali/public-api/object/handle.h b/dali/public-api/object/handle.h index d7dc63f..1e4130a 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) 2020 Samsung Electronics Co., Ltd. + * Copyright (c) 2022 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. @@ -156,7 +156,7 @@ public: * @SINCE_1_9.22 * @param[in] rhs A reference to the moved handle */ - Handle(Handle&& rhs); + Handle(Handle&& rhs) noexcept; /** * @brief Move assignment operator. @@ -165,7 +165,7 @@ public: * @param[in] rhs A reference to the moved handle * @return A reference to this handle */ - Handle& operator=(Handle&& rhs); + Handle& operator=(Handle&& rhs) noexcept; /** * @brief Downcasts to a handle. @@ -266,6 +266,16 @@ public: void SetProperty(Property::Index index, Property::Value propertyValue); /** + * @brief Reserves a number of custom properties + * + * Saves automatic re-allocation of vectors for properties when we know in advance how many there + * will be. + * + * @param[in] propertyCount The total number of initial properties. + */ + void ReserveCustomProperties(int propertyCount); + + /** * @brief Registers a new animatable property. * * @SINCE_1_0.0 @@ -289,7 +299,37 @@ public: * - 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(std::string_view name, Property::Value propertyValue); + + /** + * @brief Registers a new animatable property. + * + * @SINCE_2_1.6 + * @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 DEFINITELY not enforced. It is up to the + * caller to enforce uniqueness. + * + * 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 this creates a secondary + * entry to a different scene graph property; Access by index works as expected, but uniform + * values will use the last registered version, not the existing version, so things may break. + */ + Property::Index RegisterUniqueProperty(std::string_view name, Property::Value propertyValue); /** * @brief Register a new animatable property with an integer key. @@ -305,6 +345,7 @@ public: * 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. + * @todo CHECK THIS! * * @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 @@ -329,9 +370,58 @@ public: * - Property::ROTATION * @note If a property with the desired name already exists, then the value given is just set. */ - Property::Index RegisterProperty(Property::Index key, - std::string name, - Property::Value propertyValue); + Property::Index RegisterProperty(Property::Index key, + std::string_view name, + Property::Value propertyValue); + + /** + * @brief Register a new animatable property with an integer key. + * + * @SINCE_2_1.6 + * @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 + * It is up to the caller to guarantee that the property is unique. This allows many + * checks to be skipped. + * + * @pre The object supports dynamic properties + * i.e. Supports(Handle::DYNAMIC_PROPERTIES) returns true. Property names and keys + * are expected to be unique, and are therefore just added without any checks. + * 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 this will create a second entry with + * the same name, and may cause problems. It is up to the caller to prevent this happening. Possible side + * effects are: lookup by name always finds the first such property, not the second; whereas, writing + * uniform value to shader will use the second, not the first; + * Using the returned Property::Index for future reference will always access the correct property. + */ + Property::Index RegisterUniqueProperty(Property::Index key, + std::string_view name, + Property::Value propertyValue); /** * @brief Registers a new property. @@ -356,7 +446,7 @@ public: * - 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(std::string_view name, Property::Value propertyValue, Property::AccessMode accessMode); /** * @brief Retrieves a property value. @@ -364,6 +454,8 @@ public: * @SINCE_1_0.0 * @param[in] index The index of the property * @return The property value + * @note This returns the value set by SetProperty() or the animation target value if it is being animated. + * @note To get the current value on the scene-graph, use GetCurrentProperty(). */ Property::Value GetProperty(Property::Index index) const; @@ -374,6 +466,7 @@ public: * @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). + * @see GetProperty() */ template T GetProperty(Property::Index index) const @@ -389,6 +482,9 @@ public: * @SINCE_1_2.41 * @param[in] index The index of the property * @return The property value + * @note This returns the value of the property in the last rendered frame so can be different to that + * set by SetProperty() if the set-message has not been processed by the scene-graph yet. + * @note To retrieve the value set by SetProperty(), use GetProperty(). */ Property::Value GetCurrentProperty(Property::Index index) const; @@ -399,6 +495,7 @@ public: * @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). + * @see GetCurrentProperty() */ template T GetCurrentProperty(Property::Index index) const