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, const 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( const std::string& name, const Property::Value& propertyValue );
203 * @copydoc Dali::Handle::RegisterProperty()
205 Property::Index RegisterProperty( const std::string& name, Property::Index key, const 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( const std::string& name, const Property::Value& propertyValue, Property::AccessMode accessMode );
223 * @brief Implementing method for this override
225 Property::Index RegisterProperty( const std::string& name, Property::Index key, const Property::Value& propertyValue, Property::AccessMode accessMode );
228 * @brief returns true if the custom property exists on this object.
230 * @note The property may be defined for a type within the type registry, but it isn't explicity
231 * defined in every consequent instantiation. It can be automatically added, e.g. parenting an actor
232 * automatically registers it's parent container's child properties.
234 * @param[in] handle The handle of the object to test
235 * @param[in] index The property index to look for.
236 * @return true if the property exists on the object, false otherwise.
238 bool DoesCustomPropertyExist( Property::Index index );
241 * @copydoc Dali::Handle::AddPropertyNotification()
243 Dali::PropertyNotification AddPropertyNotification( Property::Index index,
244 int32_t componentIndex,
245 const Dali::PropertyCondition& condition );
248 * @copydoc Dali::Handle::RemovePropertyNotification()
250 void RemovePropertyNotification( Dali::PropertyNotification propertyNotification );
253 * @copydoc Dali::Handle::RemovePropertyNotifications()
255 void RemovePropertyNotifications();
258 * Notifies that a property is being animated.
259 * @param[in] animation The animation animating the property.
260 * @param[in] index The index of the property.
261 * @param[in] value The value of the property after the animation.
262 * @param[in] animationType Whether the property value given is the target or a relative value.
264 void NotifyPropertyAnimation( Animation& animation, Property::Index index, const Property::Value& value, Animation::Type animationType );
266 /******************************** Uniform Mappings ********************************/
269 * Adds uniform mapping for given property
270 * @param propertyIndex index of the property
271 * @param uniformName name of the uniform (same as property name)
273 void AddUniformMapping( Property::Index propertyIndex, const std::string& uniformName ) const;
276 * Removes uniform mapping for given property
277 * @param uniformName name of the uniform (same as property name)
279 void RemoveUniformMapping( const std::string& uniformName ) const;
281 /******************************** Constraints ********************************/
284 * Apply a constraint to an Object.
285 * @param[in] constraint The constraint to apply.
287 void ApplyConstraint( ConstraintBase& constraint );
290 * Remove one constraint from an Object.
291 * @param[in] constraint The constraint to remove.
293 void RemoveConstraint( ConstraintBase& constraint );
296 * Remove all constraints from a Object.
298 void RemoveConstraints();
301 * @copydoc Dali::Handle::RemoveConstraints( uint32_t )
303 void RemoveConstraints( uint32_t tag );
306 * Called by TypeInfo to set the type-info that this object-impl is created by.
307 * @param[in] typeInfo The TypeInfo that creates this object-impl.
309 void SetTypeInfo( const TypeInfo* typeInfo );
312 * @return the index from which custom properties start
314 uint32_t CustomPropertyStartIndex()
316 return PROPERTY_CUSTOM_START_INDEX;
320 * Retrieve the scene-graph object added by this object.
321 * @return reference to the scene-graph object, it will always exist
323 const SceneGraph::PropertyOwner& GetSceneObject() const;
325 /******************** Can be overridden by deriving classes ********************/
328 * Retrieve an animatable property owned by the scene-graph object.
329 * @pre -1 < index < GetPropertyCount().
330 * @param[in] index The index of the property.
331 * @return A dereferenceable pointer to a property, or NULL if a scene-object does not exist with this property.
333 virtual const SceneGraph::PropertyBase* GetSceneObjectAnimatableProperty( Property::Index index ) const;
336 * Retrieve a constraint input-property owned by the scene-graph object.
337 * @pre -1 < index < GetPropertyCount().
338 * @param[in] index The index of the property.
339 * @return A dereferenceable pointer to an input property, or NULL if a scene-object does not exist with this property.
341 virtual const PropertyInputImpl* GetSceneObjectInputProperty( Property::Index index ) const;
344 * Query whether the property is a component of a scene-graph property.
345 * @pre -1 < index < GetPropertyCount().
346 * @param[in] index The index of the property.
347 * @return The index or Property::INVALID_COMPONENT_INDEX.
349 virtual int32_t GetPropertyComponentIndex( Property::Index index ) const;
352 * @copydoc Dali::Handle::PropertySetSignal()
354 Handle::PropertySetSignalType& PropertySetSignal();
359 * Constructor. Protected so use New to construct an instance of this class
361 * @param sceneObject the scene graph property owner
363 Object( const SceneGraph::PropertyOwner* sceneObject );
366 * A reference counted object may only be deleted by calling Unreference()
371 * Called immediately by derived classes, after the scene-object has been created & passed to the scene-graph.
373 void OnSceneObjectAdd();
376 * Called by derived classes, shortly before send a message to remove the scene-object.
378 void OnSceneObjectRemove();
381 * For overriding by derived classes to return the parent of this object.
383 virtual Object* GetParentObject() const
385 // By default the Object does not have a parent
390 * For use in derived classes.
391 * This is called after a property is set.
392 * @param [in] index The index of the property.
393 * @param [in] propertyValue The value of the property.
395 virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) {}
398 * Retrieves the TypeInfo for this object. Only retrieves it from the type-registry once and then stores a pointer
399 * to it locally there-after. The type info will not change during the life-time of the application.
400 * @return The type-info for this object (Can be NULL)
402 const TypeInfo* GetTypeInfo() const;
405 * Helper to find custom property
407 * @return pointer to the property
409 CustomPropertyMetadata* FindCustomProperty( Property::Index index ) const;
412 * Helper to find animatable property
414 * @return pointer to the property
416 AnimatablePropertyMetadata* FindAnimatableProperty( Property::Index index ) const;
419 * Helper to register a scene-graph property
420 * @param [in] name The name of the property.
421 * @param [in] key The key of the property
422 * @param [in] index The index of the property
423 * @param [in] value The value of the property.
424 * @return The index of the registered property or Property::INVALID_INDEX if registration failed.
426 Property::Index RegisterSceneGraphProperty( const std::string& name, Property::Index key, Property::Index index, const Property::Value& propertyValue ) const;
429 * Registers animatable scene property
430 * @param typeInfo to check the default value
431 * @param index of the property to register
432 * @param value initial value or nullptr
434 void RegisterAnimatableProperty( const TypeInfo& typeInfo, Property::Index index, const Property::Value* value ) const;
437 * Check whether the animatable property is registered already, if not then register on.
438 * @param [in] index The index of the property
439 * @param [in] value optional value for the property
440 * @return pointer to the property metadata
442 AnimatablePropertyMetadata* GetSceneAnimatableProperty( Property::Index index, const Property::Value* value ) const;
445 * Resolve the index and name of child properties if any.
447 void ResolveChildProperties();
449 private: // Default property extensions for derived classes
452 * Set the value of a default property.
453 * @pre The property types match i.e. propertyValue.GetType() is equal to GetPropertyType(index).
454 * @param [in] index The index of the property.
455 * @param [in] propertyValue The new value of the property.
457 virtual void SetDefaultProperty( Property::Index index, const Property::Value& propertyValue );
460 * Retrieve a default property value.
461 * @param [in] index The index of the property.
462 * @return The property value.
464 virtual Property::Value GetDefaultProperty( Property::Index index ) const;
467 * Retrieve the latest scene-graph value of a default property.
468 * @param[in] index The index of the property.
469 * @return The latest scene-graph value of a default property.
471 virtual Property::Value GetDefaultPropertyCurrentValue( Property::Index index ) const;
474 * Notifies that a default property is being animated so the deriving class should update the cached value.
475 * @param[in] animation The animation animating the property.
476 * @param[in] index The index of the property.
477 * @param[in] value The value of the property after the animation.
478 * @param[in] animationType Whether the property value given is the target or a relative value.
480 virtual void OnNotifyDefaultPropertyAnimation( Animation& animation, Property::Index index, const Property::Value& value, Animation::Type propertyChangeType )
485 // no default, copy or assignment
487 Object(const Object& rhs) = delete;
488 Object& operator=(const Object& rhs) = delete;
491 * Enable property notifications in scene graph
493 void EnablePropertyNotifications();
496 * Enable property notifications in scene graph
498 void DisablePropertyNotifications();
501 * Get the latest value of the property on the scene-graph.
502 * @param[in] entry An entry from the property lookup container.
503 * @return The latest value of the property.
505 Property::Value GetCurrentPropertyValue( const PropertyMetadata& entry ) const;
508 * Set the value of scene graph property.
509 * @param [in] index The index of the property.
510 * @param [in] entry An entry from the property lookup container.
511 * @param [in] value The new value of the property.
513 virtual void SetSceneGraphProperty( Property::Index index, const PropertyMetadata& entry, const Property::Value& value );
517 * Get the event thread services object - used for sending messages to the scene graph
518 * Assert if called from the wrong thread.
519 * This is intentionally inline for performance reasons.
521 * @return The event thread services object
523 inline EventThreadServices& GetEventThreadServices()
525 DALI_ASSERT_ALWAYS( EventThreadServices::IsCoreRunning() );
526 return mEventThreadServices;
530 * Get the event thread services object - used for sending messages to the scene graph
531 * Assert if called from the wrong thread
532 * This is intentionally inline for performance reasons.
534 * @return The event thread services object
536 inline const EventThreadServices& GetEventThreadServices() const
538 DALI_ASSERT_ALWAYS( EventThreadServices::IsCoreRunning() );
539 return mEventThreadServices;
544 EventThreadServices& mEventThreadServices;
548 // mutable because it's lazy initialised and GetSceneObject has to be const so it can be called from const methods
549 // const to prevent accidentally calling setters directly from event thread
550 // protected to allow fast access from derived classes that have their own scene object (no function call overhead)
551 mutable const SceneGraph::PropertyOwner* mUpdateObject; ///< Reference to object to hold the scene graph properties
555 Dali::Vector<Observer*> mObservers;
556 mutable OwnerContainer<PropertyMetadata*> mCustomProperties; ///< Used for accessing custom Node properties
557 mutable OwnerContainer<PropertyMetadata*> mAnimatableProperties; ///< Used for accessing animatable Node properties
558 mutable const TypeInfo* mTypeInfo; ///< The type-info for this object, mutable so it can be lazy initialized from const method if it is required
560 ConstraintContainer* mConstraints; ///< Container of owned -constraints.
562 using PropertyNotificationContainer = std::vector< Dali::PropertyNotification >;
563 PropertyNotificationContainer* mPropertyNotifications; ///< Container of owned property notifications.
565 Handle::PropertySetSignalType mPropertySetSignal;
568 } // namespace Internal
570 // Helpers for public-api forwarding methods
572 inline Internal::Object& GetImplementation(Dali::Handle& object)
574 DALI_ASSERT_ALWAYS( object && "Object handle is empty" );
576 BaseObject& handle = object.GetBaseObject();
578 return static_cast<Internal::Object&>(handle);
581 inline const Internal::Object& GetImplementation(const Dali::Handle& object)
583 DALI_ASSERT_ALWAYS( object && "Object handle is empty" );
585 const BaseObject& handle = object.GetBaseObject();
587 return static_cast<const Internal::Object&>(handle);
592 #endif // DALI_INTERNAL_OBJECT_H