#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.
/**
* @brief PropertySetSignal function prototype for signal handler. Called when a property is set on this object.
*/
- using PropertySetSignalType = Signal<void(Handle& handle, Property::Index index, Property::Value value)>;
+ using PropertySetSignalType = Signal<void(Handle& handle, Property::Index index, const Property::Value& value)>;
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.
* @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.
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
* - 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.
* 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
* - 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.
* - 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.
* @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;
* @param[in] index The index of the property
* @return The property value
* @pre The property types match i.e. PropertyTypes::Get<T>() is equal to GetPropertyType(index).
+ * @see GetProperty()
*/
template<typename T>
T GetProperty(Property::Index index) const
* @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;
* @param[in] index The index of the property
* @return The property value
* @pre The property types match i.e. PropertyTypes::Get<T>() is equal to GetPropertyType(index).
+ * @see GetCurrentProperty()
*/
template<typename T>
T GetCurrentProperty(Property::Index index) const
projects / platform / core / uifw / dali-core.git / blobdiff