1 #ifndef DALI_INTERNAL_OBJECT_H
2 #define DALI_INTERNAL_OBJECT_H
5 * Copyright (c) 2020 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/public-api/animation/constraint.h>
26 #include <dali/public-api/common/dali-vector.h>
27 #include <dali/public-api/common/vector-wrapper.h>
28 #include <dali/public-api/object/base-object.h>
29 #include <dali/public-api/object/handle.h>
30 #include <dali/public-api/object/property.h>
31 #include <dali/public-api/object/property-index-ranges.h>
32 #include <dali/public-api/object/property-input.h>
33 #include <dali/public-api/object/property-map.h>
34 #include <dali/public-api/object/property-notification.h>
35 #include <dali/devel-api/common/owner-container.h>
36 #include <dali/devel-api/object/handle-devel.h>
37 #include <dali/internal/event/animation/animation-impl.h>
38 #include <dali/internal/event/common/event-thread-services.h>
39 #include <dali/internal/event/common/property-input-impl.h>
40 #include <dali/internal/event/common/property-metadata.h>
41 #include <dali/internal/update/common/property-base.h>
46 class PropertyNotification;
51 class EventThreadServices;
52 class PropertyCondition;
53 class PropertyInputImpl;
63 using ConstraintContainer = std::vector< Dali::Constraint >;
64 using ConstraintIter = ConstraintContainer::iterator;
65 using ConstraintConstIter = ConstraintContainer::const_iterator;
68 * A base class for objects which optionally provide properties.
69 * The concrete derived class is responsible for implementing the property system methods.
70 * Classes may derive from Dali::BaseObject, until any properties are required.
72 * An object for a property-owning object in the scene-graph.
73 * This provides an interface for observing the addition/removal of scene-objects.
75 * The derived class should either:
76 * a) Create their own scene-graph object and pass it to Object constructor.
77 * b) pass nullptr to Object constructor, in this case Object will create default scene object for property handling
79 class Object : public Dali::BaseObject
83 using Capability = Dali::Handle::Capability;
90 * Called immediately after the object has created & passed ownership of a scene-graph object.
91 * @param[in] object The object object.
93 virtual void SceneObjectAdded(Object& object) = 0;
96 * Called shortly before the object sends a message to remove its scene object.
97 * @param[in] object The object object.
99 virtual void SceneObjectRemoved(Object& object) = 0;
102 * Called shortly before the object itself is destroyed; no further callbacks will be received.
103 * @param[in] object The object object.
105 virtual void ObjectDestroyed(Object& object) = 0;
112 virtual ~Observer(){}
116 * Creates a new object
118 * @return an smart pointer to the object
120 static IntrusivePtr<Object> New();
123 * Add an observer to the object.
124 * @param[in] observer The observer to add.
126 void AddObserver( Observer& observer );
129 * Remove an observer from the object
130 * @pre The observer has already been added.
131 * @param[in] observer The observer to remove.
133 void RemoveObserver( Observer& observer );
136 * @copydoc Dali::Handle::Supports()
138 bool Supports( Capability capability ) const;
141 * @copydoc Dali::Handle::GetPropertyCount()
143 uint32_t GetPropertyCount() const;
146 * @copydoc Dali::Handle::GetPropertyName()
148 std::string GetPropertyName( Property::Index index ) const;
151 * @copydoc Dali::Handle::GetPropertyIndex()
153 Property::Index GetPropertyIndex( Property::Key key ) const;
156 * @copydoc Dali::Handle::IsPropertyWritable()
158 bool IsPropertyWritable( Property::Index index ) const;
161 * @copydoc Dali::Handle::IsPropertyAnimatable()
163 bool IsPropertyAnimatable( Property::Index index ) const;
166 * @copydoc Dali::Handle::IsPropertyAConstraintInput()
168 bool IsPropertyAConstraintInput( Property::Index index ) const;
171 * @copydoc Dali::Handle::GetPropertyType()
173 Property::Type GetPropertyType( Property::Index index ) const;
176 * @copydoc Dali::Handle::SetProperty()
178 void SetProperty(Property::Index index, Property::Value propertyValue);
181 * @copydoc Dali::Handle::GetProperty()
183 Property::Value GetProperty( Property::Index index ) const;
186 * @brief Retrieves the latest value of the property on the scene-graph.
187 * @param[in] index The index of the property required.
188 * @return The latest value of the property on the scene-graph.
190 Property::Value GetCurrentProperty( Property::Index index ) const;
193 * @copydoc Dali::Handle::GetPropertyIndices()
195 void GetPropertyIndices( Property::IndexContainer& indices ) const;
198 * @copydoc Dali::Handle::RegisterProperty()
200 Property::Index RegisterProperty(std::string name, Property::Value propertyValue);
203 * @copydoc Dali::Handle::RegisterProperty()
205 Property::Index RegisterProperty(std::string name, Property::Index key, Property::Value propertyValue);
208 * @copydoc Dali::DevelHandle::SetProperties()
210 void SetProperties( const Property::Map& properties );
213 * @copydoc Dali::DevelHandle::GetProperties()
215 void GetProperties( Property::Map& properties );
218 * @copydoc Dali::Handle::RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode)
220 Property::Index RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode);
223 * @brief Implementing method for this override
225 Property::Index RegisterProperty(std::string name,
227 Property::Value propertyValue,
228 Property::AccessMode accessMode);
231 * @brief returns true if the custom property exists on this object.
233 * @note The property may be defined for a type within the type registry, but it isn't explicity
234 * defined in every consequent instantiation. It can be automatically added, e.g. parenting an actor
235 * automatically registers it's parent container's child properties.
237 * @param[in] handle The handle of the object to test
238 * @param[in] index The property index to look for.
239 * @return true if the property exists on the object, false otherwise.
241 bool DoesCustomPropertyExist( Property::Index index );
244 * @copydoc Dali::Handle::AddPropertyNotification()
246 Dali::PropertyNotification AddPropertyNotification( Property::Index index,
247 int32_t componentIndex,
248 const Dali::PropertyCondition& condition );
251 * @copydoc Dali::Handle::RemovePropertyNotification()
253 void RemovePropertyNotification( Dali::PropertyNotification propertyNotification );
256 * @copydoc Dali::Handle::RemovePropertyNotifications()
258 void RemovePropertyNotifications();
261 * Notifies that a property is being animated.
262 * @param[in] animation The animation animating the property.
263 * @param[in] index The index of the property.
264 * @param[in] value The value of the property after the animation.
265 * @param[in] animationType Whether the property value given is the target or a relative value.
267 void NotifyPropertyAnimation( Animation& animation, Property::Index index, const Property::Value& value, Animation::Type animationType );
269 /******************************** Uniform Mappings ********************************/
272 * Adds uniform mapping for given property
273 * @param propertyIndex index of the property
274 * @param uniformName name of the uniform (same as property name)
276 void AddUniformMapping(Property::Index propertyIndex, std::string uniformName) const;
279 * Removes uniform mapping for given property
280 * @param uniformName name of the uniform (same as property name)
282 void RemoveUniformMapping( const std::string& uniformName ) const;
284 /******************************** Constraints ********************************/
287 * Apply a constraint to an Object.
288 * @param[in] constraint The constraint to apply.
290 void ApplyConstraint( ConstraintBase& constraint );
293 * Remove one constraint from an Object.
294 * @param[in] constraint The constraint to remove.
296 void RemoveConstraint( ConstraintBase& constraint );
299 * Remove all constraints from a Object.
301 void RemoveConstraints();
304 * @copydoc Dali::Handle::RemoveConstraints( uint32_t )
306 void RemoveConstraints( uint32_t tag );
309 * Called by TypeInfo to set the type-info that this object-impl is created by.
310 * @param[in] typeInfo The TypeInfo that creates this object-impl.
312 void SetTypeInfo( const TypeInfo* typeInfo );
315 * @return the index from which custom properties start
317 uint32_t CustomPropertyStartIndex()
319 return PROPERTY_CUSTOM_START_INDEX;
323 * Retrieve the scene-graph object added by this object.
324 * @return reference to the scene-graph object, it will always exist
326 const SceneGraph::PropertyOwner& GetSceneObject() const;
328 /******************** Can be overridden by deriving classes ********************/
331 * Retrieve an animatable property owned by the scene-graph object.
332 * @pre -1 < index < GetPropertyCount().
333 * @param[in] index The index of the property.
334 * @return A dereferenceable pointer to a property, or NULL if a scene-object does not exist with this property.
336 virtual const SceneGraph::PropertyBase* GetSceneObjectAnimatableProperty( Property::Index index ) const;
339 * Retrieve a constraint input-property owned by the scene-graph object.
340 * @pre -1 < index < GetPropertyCount().
341 * @param[in] index The index of the property.
342 * @return A dereferenceable pointer to an input property, or NULL if a scene-object does not exist with this property.
344 virtual const PropertyInputImpl* GetSceneObjectInputProperty( Property::Index index ) const;
347 * Query whether the property is a component of a scene-graph property.
348 * @pre -1 < index < GetPropertyCount().
349 * @param[in] index The index of the property.
350 * @return The index or Property::INVALID_COMPONENT_INDEX.
352 virtual int32_t GetPropertyComponentIndex( Property::Index index ) const;
355 * Query whether playing an animation is possible or not.
356 * @return true if playing an animation is possible.
358 virtual bool IsAnimationPossible() const
364 * @copydoc Dali::Handle::PropertySetSignal()
366 Handle::PropertySetSignalType& PropertySetSignal();
371 * Constructor. Protected so use New to construct an instance of this class
373 * @param sceneObject the scene graph property owner
375 Object( const SceneGraph::PropertyOwner* sceneObject );
378 * A reference counted object may only be deleted by calling Unreference()
383 * Called immediately by derived classes, after the scene-object has been created & passed to the scene-graph.
385 void OnSceneObjectAdd();
388 * Called by derived classes, shortly before send a message to remove the scene-object.
390 void OnSceneObjectRemove();
393 * For overriding by derived classes to return the parent of this object.
395 virtual Object* GetParentObject() const
397 // By default the Object does not have a parent
402 * For use in derived classes.
403 * This is called after a property is set.
404 * @param [in] index The index of the property.
405 * @param [in] propertyValue The value of the property.
407 virtual void OnPropertySet( Property::Index index, const Property::Value& propertyValue ) {}
410 * Retrieves the TypeInfo for this object. Only retrieves it from the type-registry once and then stores a pointer
411 * to it locally there-after. The type info will not change during the life-time of the application.
412 * @return The type-info for this object (Can be NULL)
414 const TypeInfo* GetTypeInfo() const;
417 * Helper to find custom property
419 * @return pointer to the property
421 CustomPropertyMetadata* FindCustomProperty( Property::Index index ) const;
424 * Helper to find animatable property
426 * @return pointer to the property
428 AnimatablePropertyMetadata* FindAnimatableProperty( Property::Index index ) const;
431 * Helper to register a scene-graph property
432 * @param [in] name The name of the property.
433 * @param [in] key The key of the property
434 * @param [in] index The index of the property
435 * @param [in] value The value of the property.
436 * @return The index of the registered property or Property::INVALID_INDEX if registration failed.
438 Property::Index RegisterSceneGraphProperty( std::string name, Property::Index key, Property::Index index, Property::Value propertyValue ) const;
441 * Registers animatable scene property
442 * @param typeInfo to check the default value
443 * @param index of the property to register
444 * @param value initial value or nullptr
446 void RegisterAnimatableProperty( const TypeInfo& typeInfo, Property::Index index, const Property::Value* value ) const;
449 * Check whether the animatable property is registered already, if not then register on.
450 * @param [in] index The index of the property
451 * @param [in] value optional value for the property
452 * @return pointer to the property metadata
454 AnimatablePropertyMetadata* GetSceneAnimatableProperty( Property::Index index, const Property::Value* value ) const;
457 * Resolve the index and name of child properties if any.
459 void ResolveChildProperties();
461 private: // Default property extensions for derived classes
464 * Set the value of a default property.
465 * @pre The property types match i.e. propertyValue.GetType() is equal to GetPropertyType(index).
466 * @param [in] index The index of the property.
467 * @param [in] propertyValue The new value of the property.
469 virtual void SetDefaultProperty( Property::Index index, const Property::Value& propertyValue );
472 * Retrieve a default property value.
473 * @param [in] index The index of the property.
474 * @return The property value.
476 virtual Property::Value GetDefaultProperty( Property::Index index ) const;
479 * Retrieve the latest scene-graph value of a default property.
480 * @param[in] index The index of the property.
481 * @return The latest scene-graph value of a default property.
483 virtual Property::Value GetDefaultPropertyCurrentValue( Property::Index index ) const;
486 * Notifies that a default property is being animated so the deriving class should update the cached value.
487 * @param[in] animation The animation animating the property.
488 * @param[in] index The index of the property.
489 * @param[in] value The value of the property after the animation.
490 * @param[in] animationType Whether the property value given is the target or a relative value.
492 virtual void OnNotifyDefaultPropertyAnimation( Animation& animation, Property::Index index, const Property::Value& value, Animation::Type propertyChangeType )
497 // no default, copy or assignment
499 Object(const Object& rhs) = delete;
500 Object& operator=(const Object& rhs) = delete;
503 * Enable property notifications in scene graph
505 void EnablePropertyNotifications();
508 * Enable property notifications in scene graph
510 void DisablePropertyNotifications();
513 * Get the latest value of the property on the scene-graph.
514 * @param[in] entry An entry from the property lookup container.
515 * @return The latest value of the property.
517 Property::Value GetCurrentPropertyValue( const PropertyMetadata& entry ) const;
520 * Set the value of scene graph property.
521 * @param [in] index The index of the property.
522 * @param [in] entry An entry from the property lookup container.
523 * @param [in] value The new value of the property.
525 virtual void SetSceneGraphProperty( Property::Index index, const PropertyMetadata& entry, const Property::Value& value );
529 * Get the event thread services object - used for sending messages to the scene graph
530 * Assert if called from the wrong thread.
531 * This is intentionally inline for performance reasons.
533 * @return The event thread services object
535 inline EventThreadServices& GetEventThreadServices()
537 DALI_ASSERT_ALWAYS( EventThreadServices::IsCoreRunning() );
538 return mEventThreadServices;
542 * Get the event thread services object - used for sending messages to the scene graph
543 * Assert if called from the wrong thread
544 * This is intentionally inline for performance reasons.
546 * @return The event thread services object
548 inline const EventThreadServices& GetEventThreadServices() const
550 DALI_ASSERT_ALWAYS( EventThreadServices::IsCoreRunning() );
551 return mEventThreadServices;
556 EventThreadServices& mEventThreadServices;
560 // mutable because it's lazy initialised and GetSceneObject has to be const so it can be called from const methods
561 // const to prevent accidentally calling setters directly from event thread
562 // protected to allow fast access from derived classes that have their own scene object (no function call overhead)
563 mutable const SceneGraph::PropertyOwner* mUpdateObject; ///< Reference to object to hold the scene graph properties
567 Dali::Vector<Observer*> mObservers;
568 mutable OwnerContainer<PropertyMetadata*> mCustomProperties; ///< Used for accessing custom Node properties
569 mutable OwnerContainer<PropertyMetadata*> mAnimatableProperties; ///< Used for accessing animatable Node properties
570 mutable const TypeInfo* mTypeInfo; ///< The type-info for this object, mutable so it can be lazy initialized from const method if it is required
572 ConstraintContainer* mConstraints; ///< Container of owned -constraints.
574 using PropertyNotificationContainer = std::vector< Dali::PropertyNotification >;
575 PropertyNotificationContainer* mPropertyNotifications; ///< Container of owned property notifications.
577 Handle::PropertySetSignalType mPropertySetSignal;
580 } // namespace Internal
582 // Helpers for public-api forwarding methods
584 inline Internal::Object& GetImplementation(Dali::Handle& object)
586 DALI_ASSERT_ALWAYS( object && "Object handle is empty" );
588 BaseObject& handle = object.GetBaseObject();
590 return static_cast<Internal::Object&>(handle);
593 inline const Internal::Object& GetImplementation(const Dali::Handle& object)
595 DALI_ASSERT_ALWAYS( object && "Object handle is empty" );
597 const BaseObject& handle = object.GetBaseObject();
599 return static_cast<const Internal::Object&>(handle);
604 #endif // DALI_INTERNAL_OBJECT_H