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) 2017 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 protected:
 120
 121   /**
 122    * @brief Constructor to create Metadata for a property.
 123    * @param[in] propertyValue       The value of the property (this is used by the event thread)
 124    * @param[in] sceneGraphProperty  A pointer to the scene-graph owned property
 125    * @param[in] writable            Whether the property is writable
 126    */
 127   PropertyMetadata( const Property::Value& propertyValue,
 128                     const SceneGraph::PropertyBase* sceneGraphProperty,
 129                     bool writable )
 130   : value( mStoredValue ),
 131     componentIndex( Property::INVALID_COMPONENT_INDEX ),
 132     mStoredValue( propertyValue ),
 133     mSceneGraphProperty( sceneGraphProperty ),
 134     mWritable( writable )
 135   {
 136   }
 137
 138   /**
 139    * @brief Constructor to create Metadata for a component of another property.
 140    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 141    * @param[in] writable                Whether the property is writable
 142    * @param[in] baseValueRef            A reference to the metadata of the base animatable property
 143    * @param[in] propertyComponentIndex  The component index of the property
 144    */
 145   PropertyMetadata( const SceneGraph::PropertyBase* sceneGraphProperty, bool writable, Property::Value& baseValueRef, int propertyComponentIndex )
 146   : value( baseValueRef ),
 147     componentIndex( propertyComponentIndex ),
 148     mStoredValue(),
 149     mSceneGraphProperty( sceneGraphProperty ),
 150     mWritable( writable )
 151   {
 152   }
 153
 154 private:
 155
 156   // Not implemented
 157   PropertyMetadata( const PropertyMetadata& );
 158   PropertyMetadata& operator=( const PropertyMetadata& );
 159
 160 public: // Data
 161
 162   /**
 163    * @brief The value of this property used to read/write by the event thread.
 164    *
 165    * If a component index, then refers to the value in the PropertyMetatdata of the base property
 166    * to ensure the components are kept in sync with the overall value on the event thread.
 167    * Otherwise, this just refers to the storedValue.
 168    */
 169   Property::Value& value;
 170
 171   /**
 172    * @brief The index of the property component.
 173    */
 174   int componentIndex;
 175
 176 private:
 177
 178   Property::Value mStoredValue;                         ///< The stored property value used to read/write by the event thread
 179   const SceneGraph::PropertyBase* mSceneGraphProperty;  ///< A pointer to a scene-graph property; should not be modified from actor-thread
 180   bool mWritable:1;                                     ///< Whether the property is writable
 181 };
 182
 183 /**
 184  * @brief Metadata for a registered animatable property.
 185  */
 186 class AnimatablePropertyMetadata : public PropertyMetadata
 187 {
 188 public:
 189
 190   /**
 191    * @brief Constructs metadata for a registered animatable property.
 192    * @param[in] propertyIndex           The index of the animatable property
 193    * @param[in] propertyComponentIndex  The component index of the animatable property
 194    * @param[in] propertyValue           The value of the property (this is used by the event thread)
 195    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 196    *
 197    * @note The base animatable property MUST be created before the component animatable property.
 198    */
 199   AnimatablePropertyMetadata( Property::Index propertyIndex,
 200                               const Property::Value& propertyValue,
 201                               const SceneGraph::PropertyBase* sceneGraphProperty )
 202   : PropertyMetadata( propertyValue, sceneGraphProperty, true ),
 203     index( propertyIndex )
 204   {
 205     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 206   }
 207
 208   /**
 209    * @brief Constructs metadata for a registered animatable component of another property.
 210    * @param[in] propertyIndex           The index of the animatable property
 211    * @param[in] propertyComponentIndex  The component index of the animatable property
 212    * @param[in] baseValueRef            A reference to the metadata of the base animatable property
 213    * @param[in] sceneGraphProperty      A pointer to the scene-graph owned property
 214    *
 215    * @note The base animatable property MUST be created before the component animatable property.
 216    */
 217   AnimatablePropertyMetadata( Property::Index propertyIndex,
 218                               int propertyComponentIndex,
 219                               Property::Value& baseValueRef,
 220                               const SceneGraph::PropertyBase* sceneGraphProperty )
 221   : PropertyMetadata( sceneGraphProperty, true, baseValueRef, propertyComponentIndex ),
 222     index( propertyIndex )
 223   {
 224     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 225   }
 226
 227   /**
 228    * @brief Destructor.
 229    */
 230   virtual ~AnimatablePropertyMetadata()
 231   {
 232   }
 233
 234 private:
 235
 236   // Not implemented
 237   AnimatablePropertyMetadata();
 238   AnimatablePropertyMetadata( const AnimatablePropertyMetadata& );
 239   AnimatablePropertyMetadata& operator=( const AnimatablePropertyMetadata& );
 240
 241 public: // Data
 242
 243   Property::Index   index;    ///< The index of the property.
 244 };
 245
 246 class CustomPropertyMetadata : public PropertyMetadata
 247 {
 248 public:
 249
 250   /**
 251    * Constructs Metadata for scene-graph-based custom properties, i.e. animatable custom properties.
 252    * @param[in] propertyName        The name of the custom property
 253    * @param[in] propertyKey         The key of the custom property
 254    * @param[in] propertyValue       The value of the property (this is used by the event thread)
 255    * @param[in] sceneGraphProperty  A pointer to the scene-graph owned property
 256    *
 257    * @note A valid sceneGraphProperty is mandatory otherwise this will debug assert.
 258    */
 259   CustomPropertyMetadata( const std::string& propertyName,
 260                           Property::Index propertyKey,
 261                           const Property::Value& propertyValue,
 262                           const SceneGraph::PropertyBase* sceneGraphProperty )
 263   : PropertyMetadata( propertyValue, sceneGraphProperty, true ),
 264     name( propertyName ),
 265     key( propertyKey ),
 266     childPropertyIndex( Property::INVALID_INDEX )
 267   {
 268     DALI_ASSERT_DEBUG( sceneGraphProperty && "Uninitialized scene-graph property" );
 269   }
 270
 271   /**
 272    * Constructs metadata for event side only custom properties.
 273    * @param[in] propertyName   The name of the custom property
 274    * @param[in] propertyValue  The value of the property (this is used by the event thread)
 275    * @param[in] accessMode     The access mode of the custom property (writable, animatable etc)
 276    *
 277    * @note The access mode MUST NOT be animatable otherwise this will debug assert.
 278    */
 279   CustomPropertyMetadata( const std::string& propertyName,
 280                           const Property::Value& propertyValue,
 281                           Property::AccessMode accessMode )
 282   : PropertyMetadata( propertyValue, NULL, ( accessMode != Property::READ_ONLY ) ),
 283     name( propertyName ),
 284     key( Property::INVALID_KEY ),
 285     childPropertyIndex( Property::INVALID_INDEX )
 286   {
 287     DALI_ASSERT_DEBUG( accessMode != Property::ANIMATABLE && "Event side only properties should not be animatable" );
 288   }
 289
 290   /**
 291    * @brief Destructor.
 292    */
 293   virtual ~CustomPropertyMetadata()
 294   {
 295   }
 296
 297 private:
 298
 299   // Not implemented
 300   CustomPropertyMetadata();
 301   CustomPropertyMetadata( const CustomPropertyMetadata& );
 302   CustomPropertyMetadata& operator=( const CustomPropertyMetadata& );
 303
 304 public: // Data
 305
 306   std::string       name;                 ///< The name of the property.
 307   Property::Index   key;                  ///< The key of the property.
 308   Property::Index   childPropertyIndex;   ///< The index as a child property.
 309 };
 310
 311 } // namespace Internal
 312
 313 } // namespace Dali
 314
 315 #endif // __DALI_INTERNAL_PROPERTY_METADATA_H__