1 #ifndef DALI_INTERNAL_OBJECT_H
2 #define DALI_INTERNAL_OBJECT_H
5 * Copyright (c) 2019 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-notification.h>
34 #include <dali/devel-api/common/owner-container.h>
35 #include <dali/devel-api/object/handle-devel.h>
36 #include <dali/internal/event/animation/animation-impl.h>
37 #include <dali/internal/event/common/event-thread-services.h>
38 #include <dali/internal/event/common/property-input-impl.h>
39 #include <dali/internal/event/common/property-metadata.h>
40 #include <dali/internal/update/common/property-base.h>
45 class PropertyNotification;
50 class EventThreadServices;
51 class PropertyCondition;
52 class PropertyInputImpl;
62 using ConstraintContainer = std::vector< Dali::Constraint >;
63 using ConstraintIter = ConstraintContainer::iterator;
64 using ConstraintConstIter = ConstraintContainer::const_iterator;
67 * A base class for objects which optionally provide properties.
68 * The concrete derived class is responsible for implementing the property system methods.
69 * Classes may derive from Dali::BaseObject, until any properties are required.
71 * An object for a property-owning object in the scene-graph.
72 * This provides an interface for observing the addition/removal of scene-objects.
74 * The derived class should either:
75 * a) Create their own scene-graph object and pass it to Object constructor.
76 * b) pass nullptr to Object constructor, in this case Object will create default scene object for property handling
78 class Object : public Dali::BaseObject
82 using Capability = Dali::Handle::Capability;
89 * Called immediately after the object has created & passed ownership of a scene-graph object.
90 * @param[in] object The object object.
92 virtual void SceneObjectAdded(Object& object) = 0;
95 * Called shortly before the object sends a message to remove its scene object.
96 * @param[in] object The object object.
98 virtual void SceneObjectRemoved(Object& object) = 0;
101 * Called shortly before the object itself is destroyed; no further callbacks will be received.
102 * @param[in] object The object object.
104 virtual void ObjectDestroyed(Object& object) = 0;
111 virtual ~Observer(){}
115 * Creates a new object
117 * @return an smart pointer to the object
119 static IntrusivePtr<Object> New();
122 * Add an observer to the object.
123 * @param[in] observer The observer to add.
125 void AddObserver( Observer& observer );
128 * Remove an observer from the object
129 * @pre The observer has already been added.
130 * @param[in] observer The observer to remove.
132 void RemoveObserver( Observer& observer );
135 * @copydoc Dali::Handle::Supports()
137 bool Supports( Capability capability ) const;
140 * @copydoc Dali::Handle::GetPropertyCount()
142 uint32_t GetPropertyCount() const;
145 * @copydoc Dali::Handle::GetPropertyName()
147 std::string GetPropertyName( Property::Index index ) const;
150 * @copydoc Dali::Handle::GetPropertyIndex()
152 Property::Index GetPropertyIndex( const std::string& name ) const;
155 * @copydoc Dali::Handle::GetPropertyIndex()
157 Property::Index GetPropertyIndex( Property::Index key ) const;
160 * @copydoc Dali::Handle::GetPropertyIndex()
162 Property::Index GetPropertyIndex( Property::Key key ) const;
165 * @copydoc Dali::Handle::IsPropertyWritable()
167 bool IsPropertyWritable( Property::Index index ) const;
170 * @copydoc Dali::Handle::IsPropertyAnimatable()
172 bool IsPropertyAnimatable( Property::Index index ) const;
175 * @copydoc Dali::Handle::IsPropertyAConstraintInput()
177 bool IsPropertyAConstraintInput( Property::Index index ) const;
180 * @copydoc Dali::Handle::GetPropertyType()
182 Property::Type GetPropertyType( Property::Index index ) const;
185 * @copydoc Dali::Handle::SetProperty()
187 void SetProperty( Property::Index index, const Property::Value& propertyValue );
190 * @copydoc Dali::Handle::GetProperty()
192 Property::Value GetProperty( Property::Index index ) const;
195 * @brief Retrieves the latest value of the property on the scene-graph.
196 * @param[in] index The index of the property required.
197 * @return The latest value of the property on the scene-graph.
199 Property::Value GetCurrentProperty( Property::Index index ) const;
202 * @copydoc Dali::Handle::GetPropertyIndices()
204 void GetPropertyIndices( Property::IndexContainer& indices ) const;
207 * @copydoc Dali::Handle::RegisterProperty()
209 Property::Index RegisterProperty( const std::string& name, const Property::Value& propertyValue );
212 * @copydoc Dali::Handle::RegisterProperty()
214 Property::Index RegisterProperty( const std::string& name, Property::Index key, const Property::Value& propertyValue );
217 * @copydoc Dali::Handle::RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode)
219 Property::Index RegisterProperty( const std::string& name, const Property::Value& propertyValue, Property::AccessMode accessMode );
222 * @brief Implementing method for this override
224 Property::Index RegisterProperty( const std::string& name, Property::Index key, const Property::Value& propertyValue, Property::AccessMode accessMode );
227 * @brief returns true if the custom property exists on this object.
229 * @note The property may be defined for a type within the type registry, but it isn't explicity
230 * defined in every consequent instantiation. It can be automatically added, e.g. parenting an actor
231 * automatically registers it's parent container's child properties.
233 * @param[in] handle The handle of the object to test
234 * @param[in] index The property index to look for.
235 * @return true if the property exists on the object, false otherwise.
237 bool DoesCustomPropertyExist( Property::Index index );
240 * @copydoc Dali::Handle::AddPropertyNotification()
242 Dali::PropertyNotification AddPropertyNotification( Property::Index index,
243 int32_t componentIndex,
244 const Dali::PropertyCondition& condition );
247 * @copydoc Dali::Handle::RemovePropertyNotification()
249 void RemovePropertyNotification( Dali::PropertyNotification propertyNotification );
252 * @copydoc Dali::Handle::RemovePropertyNotifications()
254 void RemovePropertyNotifications();
257 * Notifies that a property is being animated.
258 * @param[in] animation The animation animating the property.
259 * @param[in] index The index of the property.
260 * @param[in] value The value of the property after the animation.
261 * @param[in] animationType Whether the property value given is the target or a relative value.
263 void NotifyPropertyAnimation( Animation& animation, Property::Index index, const Property::Value& value, Animation::Type animationType );
265 /******************************** Uniform Mappings ********************************/
268 * Adds uniform mapping for given property
269 * @param propertyIndex index of the property
270 * @param uniformName name of the uniform (same as property name)
272 void AddUniformMapping( Property::Index propertyIndex, const std::string& uniformName ) const;
275 * Removes uniform mapping for given property
276 * @param uniformName name of the uniform (same as property name)
278 void RemoveUniformMapping( const std::string& uniformName ) const;
280 /******************************** Constraints ********************************/
283 * Apply a constraint to an Object.
284 * @param[in] constraint The constraint to apply.
286 void ApplyConstraint( ConstraintBase& constraint );
289 * Remove one constraint from an Object.
290 * @param[in] constraint The constraint to remove.
292 void RemoveConstraint( ConstraintBase& constraint );
295 * Remove all constraints from a Object.
297 void RemoveConstraints();
300 * @copydoc Dali::Handle::RemoveConstraints( uint32_t )
302 void RemoveConstraints( uint32_t tag );
305 * Called by TypeInfo to set the type-info that this object-impl is created by.
306 * @param[in] typeInfo The TypeInfo that creates this object-impl.
308 void SetTypeInfo( const TypeInfo* typeInfo );
311 * @return the index from which custom properties start
313 uint32_t CustomPropertyStartIndex()
315 return PROPERTY_CUSTOM_START_INDEX;
319 * Retrieve the scene-graph object added by this object.
320 * @return reference to the scene-graph object, it will always exist
322 const SceneGraph::PropertyOwner& GetSceneObject() const;
324 /******************** Can be overridden by deriving classes ********************/
327 * Retrieve an animatable property owned by the scene-graph object.
328 * @pre -1 < index < GetPropertyCount().
329 * @param[in] index The index of the property.
330 * @return A dereferenceable pointer to a property, or NULL if a scene-object does not exist with this property.
332 virtual const SceneGraph::PropertyBase* GetSceneObjectAnimatableProperty( Property::Index index ) const;
335 * Retrieve a constraint input-property owned by the scene-graph object.
336 * @pre -1 < index < GetPropertyCount().
337 * @param[in] index The index of the property.
338 * @return A dereferenceable pointer to an input property, or NULL if a scene-object does not exist with this property.
340 virtual const PropertyInputImpl* GetSceneObjectInputProperty( Property::Index index ) const;
343 * Query whether the property is a component of a scene-graph property.
344 * @pre -1 < index < GetPropertyCount().
345 * @param[in] index The index of the property.
346 * @return The index or Property::INVALID_COMPONENT_INDEX.
348 virtual int32_t GetPropertyComponentIndex( Property::Index index ) const;
351 * @copydoc Dali::Handle::PropertySetSignal()
353 DevelHandle::PropertySetSignalType& PropertySetSignal();
358 * Constructor. Protected so use New to construct an instance of this class
360 * @param sceneObject the scene graph property owner
362 Object( const SceneGraph::PropertyOwner* sceneObject );
365 * A reference counted object may only be deleted by calling Unreference()
370 * Called immediately by derived classes, after the scene-object has been created & passed to the scene-graph.
372 void OnSceneObjectAdd();
375 * Called by derived classes, shortly before send a message to remove the scene-object.
377 void OnSceneObjectRemove();
380 * For overriding by derived classes to return the parent of this object.
382 virtual Object* GetParentObject() const
384 // By default the Object does not have a parent
389 * For use in derived classes.
390 * This is called after a property is set.
391 * @param [in] index The index of the property.
392 * @param [in] propertyValue The value of the property.
394 virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) {}
397 * Retrieves the TypeInfo for this object. Only retrieves it from the type-registry once and then stores a pointer
398 * to it locally there-after. The type info will not change during the life-time of the application.
399 * @return The type-info for this object (Can be NULL)
401 const TypeInfo* GetTypeInfo() const;
404 * Helper to find custom property
406 * @return pointer to the property
408 CustomPropertyMetadata* FindCustomProperty( Property::Index index ) const;
411 * Helper to find animatable property
413 * @return pointer to the property
415 AnimatablePropertyMetadata* FindAnimatableProperty( Property::Index index ) const;
418 * Helper to register a scene-graph property
419 * @param [in] name The name of the property.
420 * @param [in] key The key of the property
421 * @param [in] index The index of the property
422 * @param [in] value The value of the property.
423 * @return The index of the registered property or Property::INVALID_INDEX if registration failed.
425 Property::Index RegisterSceneGraphProperty( const std::string& name, Property::Index key, Property::Index index, const Property::Value& propertyValue ) const;
428 * Registers animatable scene property
429 * @param typeInfo to check the default value
430 * @param index of the property to register
431 * @param value initial value or nullptr
433 void RegisterAnimatableProperty( const TypeInfo& typeInfo, Property::Index index, const Property::Value* value ) const;
436 * Check whether the animatable property is registered already, if not then register on.
437 * @param [in] index The index of the property
438 * @param [in] value optional value for the property
439 * @return pointer to the property metadata
441 AnimatablePropertyMetadata* GetSceneAnimatableProperty( Property::Index index, const Property::Value* value ) const;
444 * Resolve the index and name of child properties if any.
446 void ResolveChildProperties();
448 private: // Default property extensions for derived classes
451 * Set the value of a default property.
452 * @pre The property types match i.e. propertyValue.GetType() is equal to GetPropertyType(index).
453 * @param [in] index The index of the property.
454 * @param [in] propertyValue The new value of the property.
456 virtual void SetDefaultProperty( Property::Index index, const Property::Value& propertyValue );
459 * Retrieve a default property value.
460 * @param [in] index The index of the property.
461 * @return The property value.
463 virtual Property::Value GetDefaultProperty( Property::Index index ) const;
466 * Retrieve the latest scene-graph value of a default property.
467 * @param[in] index The index of the property.
468 * @return The latest scene-graph value of a default property.
470 virtual Property::Value GetDefaultPropertyCurrentValue( Property::Index index ) const;
473 * Notifies that a default property is being animated so the deriving class should update the cached value.
474 * @param[in] animation The animation animating the property.
475 * @param[in] index The index of the property.
476 * @param[in] value The value of the property after the animation.
477 * @param[in] animationType Whether the property value given is the target or a relative value.
479 virtual void OnNotifyDefaultPropertyAnimation( Animation& animation, Property::Index index, const Property::Value& value, Animation::Type propertyChangeType )
484 // no default, copy or assignment
486 Object(const Object& rhs) = delete;
487 Object& operator=(const Object& rhs) = delete;
490 * Enable property notifications in scene graph
492 void EnablePropertyNotifications();
495 * Enable property notifications in scene graph
497 void DisablePropertyNotifications();
500 * Get the latest value of the property on the scene-graph.
501 * @param[in] entry An entry from the property lookup container.
502 * @return The latest value of the property.
504 Property::Value GetCurrentPropertyValue( const PropertyMetadata& entry ) const;
507 * Set the value of scene graph property.
508 * @param [in] index The index of the property.
509 * @param [in] entry An entry from the property lookup container.
510 * @param [in] value The new value of the property.
512 virtual void SetSceneGraphProperty( Property::Index index, const PropertyMetadata& entry, const Property::Value& value );
516 * Get the event thread services object - used for sending messages to the scene graph
517 * Assert if called from the wrong thread.
518 * This is intentionally inline for performance reasons.
520 * @return The event thread services object
522 inline EventThreadServices& GetEventThreadServices()
524 DALI_ASSERT_DEBUG( EventThreadServices::IsCoreRunning() );
525 return mEventThreadServices;
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 const EventThreadServices& GetEventThreadServices() const
537 DALI_ASSERT_DEBUG( EventThreadServices::IsCoreRunning() );
538 return mEventThreadServices;
543 EventThreadServices& mEventThreadServices;
547 // mutable because it's lazy initialised and GetSceneObject has to be const so it can be called from const methods
548 // const to prevent accidentally calling setters directly from event thread
549 // protected to allow fast access from derived classes that have their own scene object (no function call overhead)
550 mutable const SceneGraph::PropertyOwner* mUpdateObject; ///< Reference to object to hold the scene graph properties
554 Dali::Vector<Observer*> mObservers;
555 mutable OwnerContainer<PropertyMetadata*> mCustomProperties; ///< Used for accessing custom Node properties
556 mutable OwnerContainer<PropertyMetadata*> mAnimatableProperties; ///< Used for accessing animatable Node properties
557 mutable const TypeInfo* mTypeInfo; ///< The type-info for this object, mutable so it can be lazy initialized from const method if it is required
559 ConstraintContainer* mConstraints; ///< Container of owned -constraints.
561 using PropertyNotificationContainer = std::vector< Dali::PropertyNotification >;
562 PropertyNotificationContainer* mPropertyNotifications; ///< Container of owned property notifications.
563 DevelHandle::PropertySetSignalType mPropertySetSignal;
567 } // namespace Internal
569 // Helpers for public-api forwarding methods
571 inline Internal::Object& GetImplementation(Dali::Handle& object)
573 DALI_ASSERT_ALWAYS( object && "Object handle is empty" );
575 BaseObject& handle = object.GetBaseObject();
577 return static_cast<Internal::Object&>(handle);
580 inline const Internal::Object& GetImplementation(const Dali::Handle& object)
582 DALI_ASSERT_ALWAYS( object && "Object handle is empty" );
584 const BaseObject& handle = object.GetBaseObject();
586 return static_cast<const Internal::Object&>(handle);
591 #endif // DALI_INTERNAL_OBJECT_H