dali/internal/event/common/object-impl.h

   1 #ifndef DALI_INTERNAL_OBJECT_H
   2 #define DALI_INTERNAL_OBJECT_H
   3
   4 /*
   5  * Copyright (c) 2022 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 <cstdint> // uint32_t
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/devel-api/common/owner-container.h>
  26 #include <dali/devel-api/object/handle-devel.h>
  27 #include <dali/internal/common/const-string.h>
  28 #include <dali/internal/event/animation/animation-impl.h>
  29 #include <dali/internal/event/common/event-thread-services.h>
  30 #include <dali/internal/event/common/property-input-impl.h>
  31 #include <dali/internal/event/common/property-metadata.h>
  32 #include <dali/internal/update/common/property-base.h>
  33 #include <dali/public-api/animation/constraint.h>
  34 #include <dali/public-api/common/dali-vector.h>
  35 #include <dali/public-api/common/vector-wrapper.h>
  36 #include <dali/public-api/object/base-object.h>
  37 #include <dali/public-api/object/handle.h>
  38 #include <dali/public-api/object/property-index-ranges.h>
  39 #include <dali/public-api/object/property-input.h>
  40 #include <dali/public-api/object/property-map.h>
  41 #include <dali/public-api/object/property-notification.h>
  42 #include <dali/public-api/object/property.h>
  43
  44 namespace Dali
  45 {
  46 class PropertyNotification;
  47
  48 namespace Internal
  49 {
  50 class ConstraintBase;
  51 class EventThreadServices;
  52 class PropertyCondition;
  53 class PropertyInputImpl;
  54 class Stage;
  55 class TypeInfo;
  56
  57 namespace SceneGraph
  58 {
  59 class PropertyBase;
  60 class PropertyOwner;
  61 } // namespace SceneGraph
  62
  63 using ConstraintContainer = std::vector<Dali::Constraint>;
  64 using ConstraintIter      = ConstraintContainer::iterator;
  65 using ConstraintConstIter = ConstraintContainer::const_iterator;
  66
  67 class KeyRef
  68 {
  69 public:
  70   KeyRef(const Property::Key& key)
  71   : mType(key.type)
  72   {
  73     if(mType == Property::Key::STRING)
  74     {
  75       mString = ConstString(key.stringKey);
  76     }
  77     else
  78     {
  79       mIndex = key.indexKey;
  80     }
  81   }
  82   KeyRef(ConstString str)
  83   : mType(Property::Key::STRING)
  84   {
  85     mString = str;
  86   }
  87   KeyRef(Property::Index index)
  88   : mType(Property::Key::INDEX)
  89   {
  90     mIndex = index;
  91   }
  92   Property::Key::Type mType;
  93   Property::Index     mIndex{Property::INVALID_INDEX};
  94   ConstString         mString;
  95 };
  96
  97 /**
  98  * A base class for objects which optionally provide properties.
  99  * The concrete derived class is responsible for implementing the property system methods.
 100  * Classes may derive from Dali::BaseObject, until any properties are required.
 101  *
 102  * An object for a property-owning object in the scene-graph.
 103  * This provides an interface for observing the addition/removal of scene-objects.
 104  *
 105  * The derived class should either:
 106  *   a) Create their own scene-graph object and pass it to Object constructor.
 107  *   b) pass nullptr to Object constructor, in this case Object will create default scene object for property handling
 108  */
 109 class Object : public Dali::BaseObject
 110 {
 111 public:
 112   using Capability = Dali::Handle::Capability;
 113
 114   class Observer
 115   {
 116   public:
 117     /**
 118      * Called immediately after the object has created & passed ownership of a scene-graph object.
 119      * @param[in] object The object object.
 120      */
 121     virtual void SceneObjectAdded(Object& object) = 0;
 122
 123     /**
 124      * Called shortly before the object sends a message to remove its scene object.
 125      * @param[in] object The object object.
 126      */
 127     virtual void SceneObjectRemoved(Object& object) = 0;
 128
 129     /**
 130      * Called shortly before the object itself is destroyed; no further callbacks will be received.
 131      * @param[in] object The object object.
 132      */
 133     virtual void ObjectDestroyed(Object& object) = 0;
 134
 135   protected:
 136     /**
 137      * Virtual destructor
 138      */
 139     virtual ~Observer() = default;
 140   };
 141
 142   /**
 143    * Creates a new object
 144    *
 145    * @return an smart pointer to the object
 146    */
 147   static IntrusivePtr<Object> New();
 148
 149   /**
 150    * Add an observer to the object.
 151    * @param[in] observer The observer to add.
 152    */
 153   void AddObserver(Observer& observer);
 154
 155   /**
 156    * Remove an observer from the object
 157    * @pre The observer has already been added.
 158    * @param[in] observer The observer to remove.
 159    */
 160   void RemoveObserver(Observer& observer);
 161
 162   /**
 163    * @copydoc Dali::Handle::Supports()
 164    */
 165   bool Supports(Capability capability) const;
 166
 167   /**
 168    * @copydoc Dali::Handle::GetPropertyCount()
 169    */
 170   uint32_t GetPropertyCount() const;
 171
 172   /**
 173    * @copydoc Dali::Handle::GetPropertyName()
 174    */
 175   std::string_view GetPropertyName(Property::Index index) const;
 176
 177   /**
 178    * @copydoc Dali::Handle::GetPropertyIndex()
 179    */
 180   Property::Index GetPropertyIndex(KeyRef key) const;
 181
 182   /**
 183    * @copydoc Dali::Handle::IsPropertyWritable()
 184    */
 185   bool IsPropertyWritable(Property::Index index) const;
 186
 187   /**
 188    * @copydoc Dali::Handle::IsPropertyAnimatable()
 189    */
 190   bool IsPropertyAnimatable(Property::Index index) const;
 191
 192   /**
 193    * @copydoc Dali::Handle::IsPropertyAConstraintInput()
 194    */
 195   bool IsPropertyAConstraintInput(Property::Index index) const;
 196
 197   /**
 198    * @copydoc Dali::Handle::GetPropertyType()
 199    */
 200   Property::Type GetPropertyType(Property::Index index) const;
 201
 202   /**
 203    * @copydoc Dali::Handle::SetProperty()
 204    */
 205   void SetProperty(Property::Index index, Property::Value propertyValue);
 206
 207   /**
 208    * @copydoc Dali::Handle::GetProperty()
 209    */
 210   Property::Value GetProperty(Property::Index index) const;
 211
 212   /**
 213    * @brief Retrieves the latest value of the property on the scene-graph.
 214    * @param[in]  index  The index of the property required.
 215    * @return The latest value of the property on the scene-graph.
 216    */
 217   Property::Value GetCurrentProperty(Property::Index index) const;
 218
 219   /**
 220    * @copydoc Dali::Handle::GetPropertyIndices()
 221    */
 222   void GetPropertyIndices(Property::IndexContainer& indices) const;
 223
 224   /**
 225    * @copydoc Dali::DevelHandle::SetProperties()
 226    */
 227   void SetProperties(const Property::Map& properties);
 228
 229   /**
 230    * @copydoc Dali::DevelHandle::GetProperties()
 231    */
 232   void GetProperties(Property::Map& properties);
 233
 234   /**
 235    * @copydoc Dali::Handle::ReserveCustomProperties()
 236    */
 237   void ReserveCustomProperties(int propertyCount);
 238
 239   /**
 240    * @copydoc Dali::Handle::RegisterProperty()
 241    */
 242   Property::Index RegisterProperty(std::string_view name, Property::Value propertyValue);
 243
 244   /**
 245    * @copydoc Dali::Handle::RegisterProperty()
 246    */
 247   Property::Index RegisterProperty(std::string_view name, Property::Index key, Property::Value propertyValue, bool checkForUniqueName);
 248
 249   /**
 250    * @copydoc Dali::Handle::RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode)
 251    */
 252   Property::Index RegisterProperty(std::string_view name, Property::Value propertyValue, Property::AccessMode accessMode);
 253
 254   /**
 255    * @brief Implementing method for this override
 256    */
 257   Property::Index RegisterProperty(std::string_view     name,
 258                                    Property::Index      key,
 259                                    Property::Value      propertyValue,
 260                                    Property::AccessMode accessMode,
 261                                    bool                 checkForUniqueName);
 262
 263   /**
 264    * @brief returns true if the custom property exists on this object.
 265    *
 266    * @note The property may be defined for a type within the type registry, but it isn't explicity
 267    * defined in every consequent instantiation. It can be automatically added, e.g. parenting an actor
 268    * automatically registers it's parent container's child properties.
 269    *
 270    * @param[in] handle The handle of the object to test
 271    * @param[in] index The property index to look for.
 272    * @return true if the property exists on the object, false otherwise.
 273    */
 274   bool DoesCustomPropertyExist(Property::Index index);
 275
 276   /**
 277    * @copydoc Dali::Handle::AddPropertyNotification()
 278    */
 279   Dali::PropertyNotification AddPropertyNotification(Property::Index                index,
 280                                                      int32_t                        componentIndex,
 281                                                      const Dali::PropertyCondition& condition);
 282
 283   /**
 284    * @copydoc Dali::Handle::RemovePropertyNotification()
 285    */
 286   void RemovePropertyNotification(Dali::PropertyNotification propertyNotification);
 287
 288   /**
 289    * @copydoc Dali::Handle::RemovePropertyNotifications()
 290    */
 291   void RemovePropertyNotifications();
 292
 293   /**
 294    * Notifies that a property is being animated.
 295    * @param[in] animation The animation animating the property.
 296    * @param[in] index The index of the property.
 297    * @param[in] value The value of the property after the animation.
 298    * @param[in] animationType Whether the property value given is the target or a relative value.
 299    */
 300   void NotifyPropertyAnimation(Animation& animation, Property::Index index, const Property::Value& value, Animation::Type animationType);
 301
 302   /******************************** Uniform Mappings ********************************/
 303
 304   /**
 305    * Adds uniform mapping for given property
 306    * @param propertyIndex index of the property
 307    * @param uniformName name of the uniform (same as property name)
 308    */
 309   void AddUniformMapping(Property::Index propertyIndex, ConstString uniformName) const;
 310
 311   /**
 312    * Removes uniform mapping for given property
 313    * @param uniformName name of the uniform (same as property name)
 314    */
 315   void RemoveUniformMapping(const std::string& uniformName) const;
 316
 317   /******************************** Constraints ********************************/
 318
 319   /**
 320    * Apply a constraint to an Object.
 321    * @param[in] constraint The constraint to apply.
 322    */
 323   void ApplyConstraint(ConstraintBase& constraint);
 324
 325   /**
 326    * Remove one constraint from an Object.
 327    * @param[in] constraint The constraint to remove.
 328    */
 329   void RemoveConstraint(ConstraintBase& constraint);
 330
 331   /**
 332    * Remove all constraints from a Object.
 333    */
 334   void RemoveConstraints();
 335
 336   /**
 337    * @copydoc Dali::Handle::RemoveConstraints( uint32_t )
 338    */
 339   void RemoveConstraints(uint32_t tag);
 340
 341   /**
 342    * Called by TypeInfo to set the type-info that this object-impl is created by.
 343    * @param[in] typeInfo The TypeInfo that creates this object-impl.
 344    */
 345   void SetTypeInfo(const TypeInfo* typeInfo);
 346
 347   /**
 348    * @return the index from which custom properties start
 349    */
 350   uint32_t CustomPropertyStartIndex()
 351   {
 352     return PROPERTY_CUSTOM_START_INDEX;
 353   }
 354
 355   /**
 356    * Retrieve the scene-graph object added by this object.
 357    * @return reference to the scene-graph object, it will always exist
 358    */
 359   const SceneGraph::PropertyOwner& GetSceneObject() const;
 360
 361   /********************  Can be overridden by deriving classes ********************/
 362
 363   /**
 364    * Retrieve an animatable property owned by the scene-graph object.
 365    * @pre -1 < index < GetPropertyCount().
 366    * @param[in] index The index of the property.
 367    * @return A dereferenceable pointer to a property, or NULL if a scene-object does not exist with this property.
 368    */
 369   virtual const SceneGraph::PropertyBase* GetSceneObjectAnimatableProperty(Property::Index index) const;
 370
 371   /**
 372    * Retrieve a constraint input-property owned by the scene-graph object.
 373    * @pre -1 < index < GetPropertyCount().
 374    * @param[in] index The index of the property.
 375    * @return A dereferenceable pointer to an input property, or NULL if a scene-object does not exist with this property.
 376    */
 377   virtual const PropertyInputImpl* GetSceneObjectInputProperty(Property::Index index) const;
 378
 379   /**
 380    * Query whether the property is a component of a scene-graph property.
 381    * @pre -1 < index < GetPropertyCount().
 382    * @param[in] index The index of the property.
 383    * @return The index or Property::INVALID_COMPONENT_INDEX.
 384    */
 385   virtual int32_t GetPropertyComponentIndex(Property::Index index) const;
 386
 387   /**
 388    * Query whether playing an animation is possible or not.
 389    * @return true if playing an animation is possible.
 390    */
 391   virtual bool IsAnimationPossible() const
 392   {
 393     return true;
 394   }
 395
 396   /**
 397    * @copydoc Dali::Handle::PropertySetSignal()
 398    */
 399   Handle::PropertySetSignalType& PropertySetSignal();
 400
 401 protected:
 402   /**
 403    * Constructor. Protected so use New to construct an instance of this class
 404    *
 405    * @param sceneObject the scene graph property owner
 406    */
 407   Object(const SceneGraph::PropertyOwner* sceneObject);
 408
 409   /**
 410    * A reference counted object may only be deleted by calling Unreference()
 411    */
 412   ~Object() override;
 413
 414   /**
 415    * Called immediately by derived classes, after the scene-object has been created & passed to the scene-graph.
 416    */
 417   void OnSceneObjectAdd();
 418
 419   /**
 420    * Called by derived classes, shortly before send a message to remove the scene-object.
 421    */
 422   void OnSceneObjectRemove();
 423
 424   /**
 425    * For overriding by derived classes to return the parent of this object.
 426    */
 427   virtual Object* GetParentObject() const
 428   {
 429     // By default the Object does not have a parent
 430     return nullptr;
 431   };
 432
 433   /**
 434    * For use in derived classes.
 435    * This is called after a property is set.
 436    * @param [in] index The index of the property.
 437    * @param [in] propertyValue The value of the property.
 438    */
 439   virtual void OnPropertySet(Property::Index index, const Property::Value& propertyValue)
 440   {
 441   }
 442
 443   /**
 444    * Retrieves the TypeInfo for this object. Only retrieves it from the type-registry once and then stores a pointer
 445    * to it locally there-after. The type info will not change during the life-time of the application.
 446    * @return The type-info for this object (Can be NULL)
 447    */
 448   const TypeInfo* GetTypeInfo() const;
 449
 450   /**
 451    * Helper to find custom property
 452    * @param index
 453    * @return pointer to the property
 454    */
 455   CustomPropertyMetadata* FindCustomProperty(Property::Index index) const;
 456
 457   /**
 458    * Helper to find animatable property
 459    * @param index
 460    * @return pointer to the property
 461    */
 462   AnimatablePropertyMetadata* FindAnimatableProperty(Property::Index index) const;
 463
 464   /**
 465    * Helper to register a scene-graph property
 466    * @param [in] name The name of the property.
 467    * @param [in] key The key of the property
 468    * @param [in] index The index of the property
 469    * @param [in] value The value of the property.
 470    * @return The index of the registered property or Property::INVALID_INDEX if registration failed.
 471    */
 472   Property::Index RegisterSceneGraphProperty(ConstString name, Property::Index key, Property::Index index, Property::Value propertyValue) const;
 473
 474   /**
 475    * Registers animatable scene property
 476    * @param typeInfo to check the default value
 477    * @param index of the property to register
 478    * @param value initial value or nullptr
 479    */
 480   void RegisterAnimatableProperty(const TypeInfo& typeInfo, Property::Index index, const Property::Value* value) const;
 481
 482   /**
 483    * Check whether the animatable property is registered already, if not then register on.
 484    * @param [in] index The index of the property
 485    * @param [in] value optional value for the property
 486    * @return pointer to the property metadata
 487    */
 488   AnimatablePropertyMetadata* GetSceneAnimatableProperty(Property::Index index, const Property::Value* value) const;
 489
 490   /**
 491    * Resolve the index and name of child properties if any.
 492    */
 493   void ResolveChildProperties();
 494
 495 private: // Default property extensions for derived classes
 496   /**
 497    * Set the value of a default property.
 498    * @pre The property types match i.e. propertyValue.GetType() is equal to GetPropertyType(index).
 499    * @param [in] index The index of the property.
 500    * @param [in] propertyValue The new value of the property.
 501    */
 502   virtual void SetDefaultProperty(Property::Index index, const Property::Value& propertyValue);
 503
 504   /**
 505    * Retrieve a default property value.
 506    * @param [in] index The index of the property.
 507    * @return The property value.
 508    */
 509   virtual Property::Value GetDefaultProperty(Property::Index index) const;
 510
 511   /**
 512    * Retrieve the latest scene-graph value of a default property.
 513    * @param[in] index The index of the property.
 514    * @return The latest scene-graph value of a default property.
 515    */
 516   virtual Property::Value GetDefaultPropertyCurrentValue(Property::Index index) const;
 517
 518   /**
 519    * Notifies that a default property is being animated so the deriving class should update the cached value.
 520    * @param[in] animation The animation animating the property.
 521    * @param[in] index The index of the property.
 522    * @param[in] value The value of the property after the animation.
 523    * @param[in] animationType Whether the property value given is the target or a relative value.
 524    */
 525   virtual void OnNotifyDefaultPropertyAnimation(Animation& animation, Property::Index index, const Property::Value& value, Animation::Type propertyChangeType)
 526   {
 527   }
 528
 529 private:
 530   // no default, copy or assignment
 531   Object()                  = delete;
 532   Object(const Object& rhs) = delete;
 533   Object& operator=(const Object& rhs) = delete;
 534
 535   /**
 536    * Enable property notifications in scene graph
 537    */
 538   void EnablePropertyNotifications();
 539
 540   /**
 541    * Enable property notifications in scene graph
 542    */
 543   void DisablePropertyNotifications();
 544
 545   /**
 546    * Get the latest value of the property on the scene-graph.
 547    * @param[in] entry An entry from the property lookup container.
 548    * @return The latest value of the property.
 549    */
 550   Property::Value GetCurrentPropertyValue(const PropertyMetadata& entry) const;
 551
 552   /**
 553    * Set the value of scene graph property.
 554    * @param [in] index The index of the property.
 555    * @param [in] entry An entry from the property lookup container.
 556    * @param [in] value The new value of the property.
 557    */
 558   virtual void SetSceneGraphProperty(Property::Index index, const PropertyMetadata& entry, const Property::Value& value);
 559
 560 protected:
 561   /**
 562    * Get the event thread services object - used for sending messages to the scene graph
 563    * Assert if called from the wrong thread.
 564    * This is intentionally inline for performance reasons.
 565    *
 566    * @return The event thread services object
 567    */
 568   inline EventThreadServices& GetEventThreadServices()
 569   {
 570     DALI_ASSERT_ALWAYS(EventThreadServices::IsCoreRunning());
 571     return mEventThreadServices;
 572   }
 573
 574   /**
 575    * Get the event thread services object - used for sending messages to the scene graph
 576    * Assert if called from the wrong thread
 577    * This is intentionally inline for performance reasons.
 578    *
 579    * @return The event thread services object
 580    */
 581   inline const EventThreadServices& GetEventThreadServices() const
 582   {
 583     DALI_ASSERT_ALWAYS(EventThreadServices::IsCoreRunning());
 584     return mEventThreadServices;
 585   }
 586
 587 private:
 588   EventThreadServices& mEventThreadServices;
 589
 590 protected:
 591   // mutable because it's lazy initialised and GetSceneObject has to be const so it can be called from const methods
 592   // const to prevent accidentally calling setters directly from event thread
 593   // protected to allow fast access from derived classes that have their own scene object (no function call overhead)
 594   mutable const SceneGraph::PropertyOwner* mUpdateObject; ///< Reference to object to hold the scene graph properties
 595
 596 private:
 597   Dali::Vector<Observer*>                   mObservers;
 598   mutable OwnerContainer<PropertyMetadata*> mCustomProperties;     ///< Used for accessing custom Node properties
 599   mutable OwnerContainer<PropertyMetadata*> mAnimatableProperties; ///< Used for accessing animatable Node properties
 600   mutable const TypeInfo*                   mTypeInfo;             ///< The type-info for this object, mutable so it can be lazy initialized from const method if it is required
 601
 602   ConstraintContainer* mConstraints; ///< Container of owned -constraints.
 603
 604   using PropertyNotificationContainer = std::vector<Dali::PropertyNotification>;
 605   PropertyNotificationContainer* mPropertyNotifications; ///< Container of owned property notifications.
 606
 607   Handle::PropertySetSignalType mPropertySetSignal;
 608 };
 609
 610 } // namespace Internal
 611
 612 // Helpers for public-api forwarding methods
 613
 614 inline Internal::Object& GetImplementation(Dali::Handle& object)
 615 {
 616   DALI_ASSERT_ALWAYS(object && "Object handle is empty");
 617
 618   BaseObject& handle = object.GetBaseObject();
 619
 620   return static_cast<Internal::Object&>(handle);
 621 }
 622
 623 inline const Internal::Object& GetImplementation(const Dali::Handle& object)
 624 {
 625   DALI_ASSERT_ALWAYS(object && "Object handle is empty");
 626
 627   const BaseObject& handle = object.GetBaseObject();
 628
 629   return static_cast<const Internal::Object&>(handle);
 630 }
 631
 632 } // namespace Dali
 633
 634 #endif // DALI_INTERNAL_OBJECT_H