Merge "Add BuildPickingRay to devel api" into devel/master
[platform/core/uifw/dali-core.git] / dali / public-api / object / handle.h
index b98df2f..1e4130a 100644 (file)
@@ -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.
@@ -74,7 +74,7 @@ public:
   /**
    * @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:
   /**
@@ -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<T>() is equal to GetPropertyType(index).
+   * @see GetProperty()
    */
   template<typename T>
   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<T>() is equal to GetPropertyType(index).
+   * @see GetCurrentProperty()
    */
   template<typename T>
   T GetCurrentProperty(Property::Index index) const