1 #ifndef DALI_INTERNAL_OBJECT_H
2 #define DALI_INTERNAL_OBJECT_H
5 * Copyright (c) 2022 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <cstdint> // uint32_t
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>
46 class PropertyNotification;
51 class EventThreadServices;
52 class PropertyCondition;
53 class PropertyInputImpl;
61 } // namespace SceneGraph
63 using ConstraintContainer = std::vector<Dali::Constraint>;
64 using ConstraintIter = ConstraintContainer::iterator;
65 using ConstraintConstIter = ConstraintContainer::const_iterator;
70 KeyRef(const Property::Key& key)
73 if(mType == Property::Key::STRING)
75 mString = ConstString(key.stringKey);
79 mIndex = key.indexKey;
82 KeyRef(ConstString str)
83 : mType(Property::Key::STRING)
87 KeyRef(Property::Index index)
88 : mType(Property::Key::INDEX)
92 Property::Key::Type mType;
93 Property::Index mIndex{Property::INVALID_INDEX};
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.
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.
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
109 class Object : public Dali::BaseObject
112 using Capability = Dali::Handle::Capability;
118 * Called immediately after the object has created & passed ownership of a scene-graph object.
119 * @param[in] object The object object.
121 virtual void SceneObjectAdded(Object& object) = 0;
124 * Called shortly before the object sends a message to remove its scene object.
125 * @param[in] object The object object.
127 virtual void SceneObjectRemoved(Object& object) = 0;
130 * Called shortly before the object itself is destroyed; no further callbacks will be received.
131 * @param[in] object The object object.
133 virtual void ObjectDestroyed(Object& object) = 0;
139 virtual ~Observer() = default;
143 * Creates a new object
145 * @return an smart pointer to the object
147 static IntrusivePtr<Object> New();
150 * Add an observer to the object.
151 * @param[in] observer The observer to add.
153 void AddObserver(Observer& observer);
156 * Remove an observer from the object
157 * @pre The observer has already been added.
158 * @param[in] observer The observer to remove.
160 void RemoveObserver(Observer& observer);
163 * @copydoc Dali::Handle::Supports()
165 bool Supports(Capability capability) const;
168 * @copydoc Dali::Handle::GetPropertyCount()
170 uint32_t GetPropertyCount() const;
173 * @copydoc Dali::Handle::GetPropertyName()
175 std::string_view GetPropertyName(Property::Index index) const;
178 * @copydoc Dali::Handle::GetPropertyIndex()
180 Property::Index GetPropertyIndex(KeyRef key) const;
183 * @copydoc Dali::Handle::IsPropertyWritable()
185 bool IsPropertyWritable(Property::Index index) const;
188 * @copydoc Dali::Handle::IsPropertyAnimatable()
190 bool IsPropertyAnimatable(Property::Index index) const;
193 * @copydoc Dali::Handle::IsPropertyAConstraintInput()
195 bool IsPropertyAConstraintInput(Property::Index index) const;
198 * @copydoc Dali::Handle::GetPropertyType()
200 Property::Type GetPropertyType(Property::Index index) const;
203 * @copydoc Dali::Handle::SetProperty()
205 void SetProperty(Property::Index index, Property::Value propertyValue);
208 * @copydoc Dali::Handle::GetProperty()
210 Property::Value GetProperty(Property::Index index) const;
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.
217 Property::Value GetCurrentProperty(Property::Index index) const;
220 * @copydoc Dali::Handle::GetPropertyIndices()
222 void GetPropertyIndices(Property::IndexContainer& indices) const;
225 * @copydoc Dali::DevelHandle::SetProperties()
227 void SetProperties(const Property::Map& properties);
230 * @copydoc Dali::DevelHandle::GetProperties()
232 void GetProperties(Property::Map& properties);
235 * @copydoc Dali::Handle::ReserveCustomProperties()
237 void ReserveCustomProperties(int propertyCount);
240 * @copydoc Dali::Handle::RegisterProperty()
242 Property::Index RegisterProperty(std::string_view name, Property::Value propertyValue);
245 * @copydoc Dali::Handle::RegisterProperty()
247 Property::Index RegisterProperty(std::string_view name, Property::Index key, Property::Value propertyValue, bool checkForUniqueName);
250 * @copydoc Dali::Handle::RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode)
252 Property::Index RegisterProperty(std::string_view name, Property::Value propertyValue, Property::AccessMode accessMode);
255 * @brief Implementing method for this override
257 Property::Index RegisterProperty(std::string_view name,
259 Property::Value propertyValue,
260 Property::AccessMode accessMode,
261 bool checkForUniqueName);
264 * @brief returns true if the custom property exists on this object.
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.
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.
274 bool DoesCustomPropertyExist(Property::Index index);
277 * @copydoc Dali::Handle::AddPropertyNotification()
279 Dali::PropertyNotification AddPropertyNotification(Property::Index index,
280 int32_t componentIndex,
281 const Dali::PropertyCondition& condition);
284 * @copydoc Dali::Handle::RemovePropertyNotification()
286 void RemovePropertyNotification(Dali::PropertyNotification propertyNotification);
289 * @copydoc Dali::Handle::RemovePropertyNotifications()
291 void RemovePropertyNotifications();
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.
300 void NotifyPropertyAnimation(Animation& animation, Property::Index index, const Property::Value& value, Animation::Type animationType);
302 /******************************** Uniform Mappings ********************************/
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)
309 void AddUniformMapping(Property::Index propertyIndex, ConstString uniformName) const;
312 * Removes uniform mapping for given property
313 * @param uniformName name of the uniform (same as property name)
315 void RemoveUniformMapping(const std::string& uniformName) const;
317 /******************************** Constraints ********************************/
320 * Apply a constraint to an Object.
321 * @param[in] constraint The constraint to apply.
323 void ApplyConstraint(ConstraintBase& constraint);
326 * Remove one constraint from an Object.
327 * @param[in] constraint The constraint to remove.
329 void RemoveConstraint(ConstraintBase& constraint);
332 * Remove all constraints from a Object.
334 void RemoveConstraints();
337 * @copydoc Dali::Handle::RemoveConstraints( uint32_t )
339 void RemoveConstraints(uint32_t tag);
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.
345 void SetTypeInfo(const TypeInfo* typeInfo);
348 * @return the index from which custom properties start
350 uint32_t CustomPropertyStartIndex()
352 return PROPERTY_CUSTOM_START_INDEX;
356 * Retrieve the scene-graph object added by this object.
357 * @return reference to the scene-graph object, it will always exist
359 const SceneGraph::PropertyOwner& GetSceneObject() const;
361 /******************** Can be overridden by deriving classes ********************/
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.
369 virtual const SceneGraph::PropertyBase* GetSceneObjectAnimatableProperty(Property::Index index) const;
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.
377 virtual const PropertyInputImpl* GetSceneObjectInputProperty(Property::Index index) const;
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.
385 virtual int32_t GetPropertyComponentIndex(Property::Index index) const;
388 * Query whether playing an animation is possible or not.
389 * @return true if playing an animation is possible.
391 virtual bool IsAnimationPossible() const
397 * @copydoc Dali::Handle::PropertySetSignal()
399 Handle::PropertySetSignalType& PropertySetSignal();
403 * Constructor. Protected so use New to construct an instance of this class
405 * @param sceneObject the scene graph property owner
407 Object(const SceneGraph::PropertyOwner* sceneObject);
410 * A reference counted object may only be deleted by calling Unreference()
415 * Called immediately by derived classes, after the scene-object has been created & passed to the scene-graph.
417 void OnSceneObjectAdd();
420 * Called by derived classes, shortly before send a message to remove the scene-object.
422 void OnSceneObjectRemove();
425 * For overriding by derived classes to return the parent of this object.
427 virtual Object* GetParentObject() const
429 // By default the Object does not have a parent
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.
439 virtual void OnPropertySet(Property::Index index, const Property::Value& propertyValue)
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)
448 const TypeInfo* GetTypeInfo() const;
451 * Helper to find custom property
453 * @return pointer to the property
455 CustomPropertyMetadata* FindCustomProperty(Property::Index index) const;
458 * Helper to find animatable property
460 * @return pointer to the property
462 AnimatablePropertyMetadata* FindAnimatableProperty(Property::Index index) const;
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.
472 Property::Index RegisterSceneGraphProperty(ConstString name, Property::Index key, Property::Index index, Property::Value propertyValue) const;
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
480 void RegisterAnimatableProperty(const TypeInfo& typeInfo, Property::Index index, const Property::Value* value) const;
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
488 AnimatablePropertyMetadata* GetSceneAnimatableProperty(Property::Index index, const Property::Value* value) const;
491 * Resolve the index and name of child properties if any.
493 void ResolveChildProperties();
495 private: // Default property extensions for derived classes
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.
502 virtual void SetDefaultProperty(Property::Index index, const Property::Value& propertyValue);
505 * Retrieve a default property value.
506 * @param [in] index The index of the property.
507 * @return The property value.
509 virtual Property::Value GetDefaultProperty(Property::Index index) const;
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.
516 virtual Property::Value GetDefaultPropertyCurrentValue(Property::Index index) const;
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.
525 virtual void OnNotifyDefaultPropertyAnimation(Animation& animation, Property::Index index, const Property::Value& value, Animation::Type propertyChangeType)
530 // no default, copy or assignment
532 Object(const Object& rhs) = delete;
533 Object& operator=(const Object& rhs) = delete;
536 * Enable property notifications in scene graph
538 void EnablePropertyNotifications();
541 * Enable property notifications in scene graph
543 void DisablePropertyNotifications();
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.
550 Property::Value GetCurrentPropertyValue(const PropertyMetadata& entry) const;
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.
558 virtual void SetSceneGraphProperty(Property::Index index, const PropertyMetadata& entry, const Property::Value& value);
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.
566 * @return The event thread services object
568 inline EventThreadServices& GetEventThreadServices()
570 DALI_ASSERT_ALWAYS(EventThreadServices::IsCoreRunning());
571 return mEventThreadServices;
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.
579 * @return The event thread services object
581 inline const EventThreadServices& GetEventThreadServices() const
583 DALI_ASSERT_ALWAYS(EventThreadServices::IsCoreRunning());
584 return mEventThreadServices;
588 EventThreadServices& mEventThreadServices;
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
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
602 ConstraintContainer* mConstraints; ///< Container of owned -constraints.
604 using PropertyNotificationContainer = std::vector<Dali::PropertyNotification>;
605 PropertyNotificationContainer* mPropertyNotifications; ///< Container of owned property notifications.
607 Handle::PropertySetSignalType mPropertySetSignal;
610 } // namespace Internal
612 // Helpers for public-api forwarding methods
614 inline Internal::Object& GetImplementation(Dali::Handle& object)
616 DALI_ASSERT_ALWAYS(object && "Object handle is empty");
618 BaseObject& handle = object.GetBaseObject();
620 return static_cast<Internal::Object&>(handle);
623 inline const Internal::Object& GetImplementation(const Dali::Handle& object)
625 DALI_ASSERT_ALWAYS(object && "Object handle is empty");
627 const BaseObject& handle = object.GetBaseObject();
629 return static_cast<const Internal::Object&>(handle);
634 #endif // DALI_INTERNAL_OBJECT_H