dali/internal/event/common/property-metadata.h

   1 #ifndef DALI_INTERNAL_PROPERTY_METADATA_H
   2 #define DALI_INTERNAL_PROPERTY_METADATA_H
   3
   4 /*
   5  * Copyright (c) 2019 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <algorithm>
  23 #include <utility>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/common/constants.h>
  27 #include <dali/public-api/object/property.h>
  28 #include <dali/public-api/object/property-value.h>
  29
  30 namespace Dali
  31 {
  32
  33 namespace Internal
  34 {
  35
  36 namespace SceneGraph
  37 {
  38 class PropertyBase;
  39 }
  40
  41 /**
  42  * @brief Base class for the Metadata required by custom and registered animatable properties.
  43  *
  44  * The value type field should be queried, before accessing the scene-graph property:
  45  *
  46  * @code
  47  * void Example(PropertyEntry entry)
  48  * {
  49  *   if (entry.value.GetType() == Property::VECTOR3)
  50  *   {
  51  *     SceneGraph::AnimatableProperty<Vector3>* property = dynamic_cast< SceneGraph::AnimatableProperty<Vector3>* >( entry.property );
  52  *     ...
  53  *   }
  54  * @endcode
  55  *
  56  */
  57 class PropertyMetadata
  58 {
  59 public:
  60
  61   /**
  62    * @brief Virtual Destructor.
  63    */
  64   virtual ~PropertyMetadata()
  65   {
  66   }
  67
  68   /**
  69    * @brief Returns whether the property is animatable (i.e. if its a scene graph property).
  70    * @return True if animatable, false otherwise
  71    */
  72   bool IsAnimatable( void ) const
  73   {
  74     return NULL != mSceneGraphProperty;
  75   }
  76
  77   /**
  78    * @brief Whether the property can be written to.
  79    * @return True if the property can be written to, false otherwise
  80    */
  81   bool IsWritable( void ) const
  82   {
  83     return mWritable;
  84   }
  85
  86   /**
  87    * @brief Retrieves the scene-graph property.
  88    * @return The scene graph property
  89    *
  90    * @note Should only be called if the scene-graph property was passed in originally. Will debug assert if the stored property is NULL.
  91    */
  92   const SceneGraph::PropertyBase* GetSceneGraphProperty() const
  93   {
  94     DALI_ASSERT_DEBUG( mSceneGraphProperty && "Accessing uninitialized SceneGraph property" );
  95     return mSceneGraphProperty;
  96   }
  97
  98   /**
  99    * @brief Retrieve the type of the property.
 100    * @return Type of the held property value
 101    */
 102   inline Property::Type GetType() const
 103   {
 104     return value.GetType();
 105   }
 106
 107   /**
 108    * Set the cached value of the property.
 109    * @param[in] value The propertyValue to set.
 110    */
 111   void SetPropertyValue( const Property::Value& propertyValue );
 112
 113   /**
 114    * Get the cached value of a the property.
 115    * @return The cached value of the property.
 116    */
 117   Property::Value GetPropertyValue() const;
 118
 119   /**
 120    * Modifies the stored value by the relativeValue.
 121    * @param[in] relativeValue The value to change by.
 122    */
 123   void AdjustPropertyValueBy( const Property::Value& relativeValue );
 124
 125 protected:
 126
 127   /**
 128    * @brief Constructor to create Metadata for a property.
 129    * @param[in] propertyValue       The value of the property (this is used by the event thread)
 130    * @param[in] sceneGraphProperty  A pointer to the scene-graph owned property
 131    * @param[in] writable            Whether the property is writable
 132    */
 133   PropertyMetadata( const Property::Value& propertyValue,
 134                     const SceneGraph::PropertyBase* sceneGraphProperty,
 135                     bool writable )
 136   : value( mStoredValue ),
 137     componentIndex( Property::INVALID_COMPONENT_INDEX ),
 138     mStoredValue( propertyValue ),
 139     mSceneGraphProperty( sceneGraphProperty ),
 140     mWritable( writable )
 141   {
 142   }
 143
 144   /**
 145    * @brief Constructor to create Metadata for a component of another property.
 146    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 147    * @param[in] writable                Whether the property is writable
 148    * @param[in] baseValueRef            A reference to the metadata of the base animatable property
 149    * @param[in] propertyComponentIndex  The component index of the property
 150    */
 151   PropertyMetadata( const SceneGraph::PropertyBase* sceneGraphProperty, bool writable, Property::Value& baseValueRef, int32_t propertyComponentIndex )
 152   : value( baseValueRef ),
 153     componentIndex( propertyComponentIndex ),
 154     mStoredValue(),
 155     mSceneGraphProperty( sceneGraphProperty ),
 156     mWritable( writable )
 157   {
 158   }
 159
 160 private:
 161
 162   // Not implemented
 163   PropertyMetadata( const PropertyMetadata& );
 164   PropertyMetadata& operator=( const PropertyMetadata& );
 165
 166 public: // Data
 167
 168   /**
 169    * @brief The value of this property used to read/write by the event thread.
 170    *
 171    * If this PropertyMetadata is for property component, then refers to the value in the PropertyMetadata of the base property
 172    * to ensure the components are kept in sync with the overall value on the event thread.
 173    * Otherwise, this refers to mStoredValue.
 174    */
 175   Property::Value& value;
 176
 177   /**
 178    * @brief The index of the property component.
 179    */
 180   int32_t componentIndex;
 181
 182 private:
 183
 184   Property::Value mStoredValue;                         ///< The cached property value used to read/write by the event thread
 185   const SceneGraph::PropertyBase* mSceneGraphProperty;  ///< A pointer to a scene-graph property; should not be modified from actor-thread
 186   bool mWritable:1;                                     ///< Whether the property is writable
 187 };
 188
 189 /**
 190  * @brief Metadata for a registered animatable property.
 191  */
 192 class AnimatablePropertyMetadata : public PropertyMetadata
 193 {
 194 public:
 195
 196   /**
 197    * @brief Constructs metadata for a registered animatable property.
 198    * @param[in] propertyIndex           The index of the animatable property
 199    * @param[in] propertyComponentIndex  The component index of the animatable property
 200    * @param[in] propertyValue           The value of the property (this is used by the event thread)
 201    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 202    *
 203    * @note The base animatable property MUST be created before the component animatable property.
 204    */
 205   AnimatablePropertyMetadata( Property::Index propertyIndex,
 206                               const Property::Value& propertyValue,
 207                               const SceneGraph::PropertyBase* sceneGraphProperty )
 208   : PropertyMetadata( propertyValue, sceneGraphProperty, true ),
 209     index( propertyIndex )
 210   {
 211     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 212   }
 213
 214   /**
 215    * @brief Constructs metadata for a registered animatable component of another property.
 216    * @param[in] propertyIndex           The index of the animatable property
 217    * @param[in] propertyComponentIndex  The component index of the animatable property
 218    * @param[in] baseValueRef            A reference to the metadata of the base animatable property
 219    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 220    *
 221    * @note The base animatable property MUST be created before the component animatable property.
 222    */
 223   AnimatablePropertyMetadata( Property::Index propertyIndex,
 224                               int propertyComponentIndex,
 225                               Property::Value& baseValueRef,
 226                               const SceneGraph::PropertyBase* sceneGraphProperty )
 227   : PropertyMetadata( sceneGraphProperty, true, baseValueRef, propertyComponentIndex ),
 228     index( propertyIndex )
 229   {
 230     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 231   }
 232
 233   /**
 234    * @brief Destructor.
 235    */
 236   ~AnimatablePropertyMetadata() override
 237   {
 238   }
 239
 240 private:
 241
 242   // Not implemented
 243   AnimatablePropertyMetadata();
 244   AnimatablePropertyMetadata( const AnimatablePropertyMetadata& );
 245   AnimatablePropertyMetadata& operator=( const AnimatablePropertyMetadata& );
 246
 247 public: // Data
 248
 249   Property::Index   index;    ///< The index of the property.
 250 };
 251
 252 class CustomPropertyMetadata : public PropertyMetadata
 253 {
 254 public:
 255
 256   /**
 257    * Constructs Metadata for scene-graph-based custom properties, i.e. animatable custom properties.
 258    * @param[in] propertyName        The name of the custom property
 259    * @param[in] propertyKey         The key of the custom property
 260    * @param[in] propertyValue       The value of the property (this is used by the event thread)
 261    * @param[in] sceneGraphProperty  A pointer to the scene-graph owned property
 262    *
 263    * @note A valid sceneGraphProperty is mandatory otherwise this will debug assert.
 264    */
 265   CustomPropertyMetadata( const std::string& propertyName,
 266                           Property::Index propertyKey,
 267                           const Property::Value& propertyValue,
 268                           const SceneGraph::PropertyBase* sceneGraphProperty )
 269   : PropertyMetadata( propertyValue, sceneGraphProperty, true ),
 270     name( propertyName ),
 271     key( propertyKey ),
 272     childPropertyIndex( Property::INVALID_INDEX )
 273   {
 274     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 275   }
 276
 277   /**
 278    * Constructs metadata for event side only custom properties.
 279    * @param[in] propertyName   The name of the custom property
 280    * @param[in] propertyValue  The value of the property (this is used by the event thread)
 281    * @param[in] accessMode     The access mode of the custom property (writable, animatable etc)
 282    *
 283    * @note The access mode MUST NOT be animatable otherwise this will debug assert.
 284    */
 285   CustomPropertyMetadata( const std::string& propertyName,
 286                           const Property::Value& propertyValue,
 287                           Property::AccessMode accessMode )
 288   : PropertyMetadata( propertyValue, NULL, ( accessMode != Property::READ_ONLY ) ),
 289     name( propertyName ),
 290     key( Property::INVALID_KEY ),
 291     childPropertyIndex( Property::INVALID_INDEX )
 292   {
 293     DALI_ASSERT_DEBUG( accessMode != Property::ANIMATABLE && "Event side only properties should not be animatable" );
 294   }
 295
 296   /**
 297    * @brief Destructor.
 298    */
 299   ~CustomPropertyMetadata() override
 300   {
 301   }
 302
 303 private:
 304
 305   // Not implemented
 306   CustomPropertyMetadata();
 307   CustomPropertyMetadata( const CustomPropertyMetadata& );
 308   CustomPropertyMetadata& operator=( const CustomPropertyMetadata& );
 309
 310 public: // Data
 311
 312   std::string       name;                 ///< The name of the property.
 313   Property::Index   key;                  ///< The key of the property.
 314   Property::Index   childPropertyIndex;   ///< The index as a child property.
 315 };
 316
 317 } // namespace Internal
 318
 319 } // namespace Dali
 320
 321 #endif // DALI_INTERNAL_PROPERTY_METADATA_H