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

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