1 #ifndef __DALI_INTERNAL_OBJECT_H__
2 #define __DALI_INTERNAL_OBJECT_H__
5 * Copyright (c) 2018 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 typedef std::vector< Dali::Constraint > ConstraintContainer;
63 typedef ConstraintContainer::iterator ConstraintIter;
64 typedef ConstraintContainer::const_iterator ConstraintConstIter;
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 concrete derived class is responsible for:
76 * 1) Adding & removing an object from the scene-graph. The OnSceneObjectAdd() and OnSceneObjectRemove()
77 * methods should be called by the derived class, to trigger observer callbacks.
78 * 3) Implementing the GetSceneObject() methods, used to access the scene-object.
79 * 4) Providing access to properties stored by the scene-graph object. These should match the properties
80 * reported by the base Dali::Internal::Object methods.
83 class Object : public Dali::BaseObject
87 typedef Dali::Handle::Capability Capability;
94 * Called immediately after the object has created & passed ownership of a scene-graph object.
95 * @param[in] object The object object.
97 virtual void SceneObjectAdded(Object& object) = 0;
100 * Called shortly before the object sends a message to remove its scene object.
101 * @param[in] object The object object.
103 virtual void SceneObjectRemoved(Object& object) = 0;
106 * Called shortly before the object itself is destroyed; no further callbacks will be received.
107 * @param[in] object The object object.
109 virtual void ObjectDestroyed(Object& object) = 0;
116 virtual ~Observer(){}
125 * Add an observer to the object.
126 * @param[in] observer The observer to add.
128 void AddObserver( Observer& observer );
131 * Remove an observer from the object
132 * @pre The observer has already been added.
133 * @param[in] observer The observer to remove.
135 void RemoveObserver( Observer& observer );
138 * @copydoc Dali::Handle::Supports()
140 bool Supports( Capability capability ) const;
143 * @copydoc Dali::Handle::GetPropertyCount()
145 uint32_t GetPropertyCount() const;
148 * @copydoc Dali::Handle::GetPropertyName()
150 std::string GetPropertyName( Property::Index index ) const;
153 * @copydoc Dali::Handle::GetPropertyIndex()
155 Property::Index GetPropertyIndex( const std::string& name ) const;
158 * @copydoc Dali::Handle::GetPropertyIndex()
160 Property::Index GetPropertyIndex( Property::Index key ) const;
163 * @copydoc Dali::Handle::GetPropertyIndex()
165 Property::Index GetPropertyIndex( Property::Key key ) const;
168 * @copydoc Dali::Handle::IsPropertyWritable()
170 bool IsPropertyWritable( Property::Index index ) const;
173 * @copydoc Dali::Handle::IsPropertyAnimatable()
175 bool IsPropertyAnimatable( Property::Index index ) const;
178 * @copydoc Dali::Handle::IsPropertyAConstraintInput()
180 bool IsPropertyAConstraintInput( Property::Index index ) const;
183 * @copydoc Dali::Handle::GetPropertyType()
185 Property::Type GetPropertyType( Property::Index index ) const;
188 * @copydoc Dali::Handle::SetProperty()
190 void SetProperty( Property::Index index, const Property::Value& propertyValue );
193 * @copydoc Dali::Handle::GetProperty()
195 Property::Value GetProperty( Property::Index index ) const;
198 * @brief Retrieves the latest value of the property on the scene-graph.
199 * @param[in] index The index of the property required.
200 * @return The latest value of the property on the scene-graph.
202 Property::Value GetCurrentProperty( Property::Index index ) const;
205 * @copydoc Dali::Handle::GetPropertyIndices()
207 void GetPropertyIndices( Property::IndexContainer& indices ) const;
210 * @copydoc Dali::Handle::RegisterProperty()
212 Property::Index RegisterProperty( const std::string& name, const Property::Value& propertyValue );
215 * @copydoc Dali::Handle::RegisterProperty()
217 Property::Index RegisterProperty( const std::string& name, Property::Index key, const Property::Value& propertyValue );
220 * @copydoc Dali::Handle::RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode)
222 Property::Index RegisterProperty( const std::string& name, const Property::Value& propertyValue, Property::AccessMode accessMode );
225 * @brief Implementing method for this override
227 Property::Index RegisterProperty( const std::string& name, Property::Index key, const Property::Value& propertyValue, Property::AccessMode accessMode );
230 * @brief returns true if the custom property exists on this object.
232 * @note The property may be defined for a type within the type registry, but it isn't explicity
233 * defined in every consequent instantiation. It can be automatically added, e.g. parenting an actor
234 * automatically registers it's parent container's child properties.
236 * @param[in] handle The handle of the object to test
237 * @param[in] index The property index to look for.
238 * @return true if the property exists on the object, false otherwise.
240 bool DoesCustomPropertyExist( Property::Index index );
243 * @copydoc Dali::Handle::AddPropertyNotification()
245 Dali::PropertyNotification AddPropertyNotification( Property::Index index,
246 int32_t componentIndex,
247 const Dali::PropertyCondition& condition );
250 * @copydoc Dali::Handle::RemovePropertyNotification()
252 void RemovePropertyNotification( Dali::PropertyNotification propertyNotification );
255 * @copydoc Dali::Handle::RemovePropertyNotifications()
257 void RemovePropertyNotifications();
260 * Notifies that a property is being animated.
261 * @param[in] animation The animation animating the property.
262 * @param[in] index The index of the property.
263 * @param[in] value The value of the property after the animation.
264 * @param[in] animationType Whether the property value given is the target or a relative value.
266 void NotifyPropertyAnimation( Animation& animation, Property::Index index, const Property::Value& value, Animation::Type animationType );
268 /******************************** Uniform Mappings ********************************/
271 * @copydoc Dali::Handle::AddUniformMapping()
273 void AddUniformMapping( Property::Index propertyIndex, const std::string& uniformName ) const;
276 * @copydoc Dali::Handle::RemoveUniformMapping( )
278 void RemoveUniformMapping( const std::string& uniformName );
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;
318 /******************** To be overridden by deriving classes ********************/
321 * Retrieve the scene-graph object added by this object.
322 * @return A pointer to the object, or NULL if no object has been added to the scene-graph.
324 virtual const SceneGraph::PropertyOwner* GetSceneObject() const = 0;
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 = 0;
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 = 0;
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 * A reference counted object may only be deleted by calling Unreference()
363 * Called immediately by derived classes, after the scene-object has been created & passed to the scene-graph.
365 void OnSceneObjectAdd();
368 * Called by derived classes, shortly before send a message to remove the scene-object.
370 void OnSceneObjectRemove();
373 * For overriding by derived classes to return the parent of this object.
375 virtual Object* GetParentObject() const
377 // By default the Object does not have a parent
382 * For use in derived classes.
383 * This is called after a property is set.
384 * @param [in] index The index of the property.
385 * @param [in] propertyValue The value of the property.
387 virtual void OnPropertySet( Property::Index index, Property::Value propertyValue ) {}
390 * Retrieves the TypeInfo for this object. Only retrieves it from the type-registry once and then stores a pointer
391 * to it locally there-after. The type info will not change during the life-time of the application.
392 * @return The type-info for this object (Can be NULL)
394 const TypeInfo* GetTypeInfo() const;
397 * Helper to find custom property
399 * @return pointer to the property
401 CustomPropertyMetadata* FindCustomProperty( Property::Index index ) const;
404 * Helper to find animatable property
406 * @return pointer to the property
408 AnimatablePropertyMetadata* FindAnimatableProperty( Property::Index index ) const;
411 * Helper to register a scene-graph property
412 * @param [in] name The name of the property.
413 * @param [in] key The key of the property
414 * @param [in] index The index of the property
415 * @param [in] value The value of the property.
416 * @return The index of the registered property or Property::INVALID_INDEX if registration failed.
418 Property::Index RegisterSceneGraphProperty(const std::string& name, Property::Index key, Property::Index index, const Property::Value& propertyValue) const;
421 * Registers animatable scene property
422 * @param typeInfo to check the default value
423 * @param index of the property to register
424 * @param value initial value or nullptr
426 void RegisterAnimatableProperty( const TypeInfo& typeInfo, Property::Index index, const Property::Value* value ) const;
429 * Check whether the animatable property is registered already, if not then register on.
430 * @param [in] index The index of the property
431 * @param [in] value optional value for the property
432 * @return pointer to the property metadata
434 AnimatablePropertyMetadata* GetSceneAnimatableProperty( Property::Index index, const Property::Value* value ) const;
437 * Resolve the index and name of child properties if any.
439 void ResolveChildProperties();
441 private: // Default property extensions for derived classes
444 * Set the value of a default property.
445 * @pre The property types match i.e. propertyValue.GetType() is equal to GetPropertyType(index).
446 * @param [in] index The index of the property.
447 * @param [in] propertyValue The new value of the property.
449 virtual void SetDefaultProperty( Property::Index index, const Property::Value& propertyValue ) = 0;
452 * Retrieve a default property value.
453 * @param [in] index The index of the property.
454 * @return The property value.
456 virtual Property::Value GetDefaultProperty( Property::Index index ) const = 0;
459 * Retrieve the latest scene-graph value of a default property.
460 * @param[in] index The index of the property.
461 * @return The latest scene-graph value of a default property.
463 virtual Property::Value GetDefaultPropertyCurrentValue( Property::Index index ) const = 0;
466 * Notifies that a default property is being animated so the deriving class should update the cached value.
467 * @param[in] animation The animation animating the property.
468 * @param[in] index The index of the property.
469 * @param[in] value The value of the property after the animation.
470 * @param[in] animationType Whether the property value given is the target or a relative value.
472 virtual void OnNotifyDefaultPropertyAnimation( Animation& animation, Property::Index index, const Property::Value& value, Animation::Type propertyChangeType )
476 * @todo this is virtual so that for now actor can override it,
477 * it needs to be removed and only have GetSceneObject but that requires changing actor and constraint logic
478 * Retrieve the scene-graph object added by this object.
479 * @return A pointer to the object, or NULL if no object has been added to the scene-graph.
481 virtual const SceneGraph::PropertyOwner* GetPropertyOwner() const
483 return GetSceneObject();
488 Object(const Object& rhs) = delete;
489 Object& operator=(const Object& rhs) = delete;
492 * Enable property notifications in scene graph
494 void EnablePropertyNotifications();
497 * Enable property notifications in scene graph
499 void DisablePropertyNotifications();
502 * Get the latest value of the property on the scene-graph.
503 * @param[in] entry An entry from the property lookup container.
504 * @return The latest value of the property.
506 Property::Value GetCurrentPropertyValue( const PropertyMetadata& entry ) const;
509 * Set the value of scene graph property.
510 * @param [in] index The index of the property.
511 * @param [in] entry An entry from the property lookup container.
512 * @param [in] value The new value of the property.
514 virtual void SetSceneGraphProperty( Property::Index index, const PropertyMetadata& entry, const Property::Value& value );
518 * Get the event thread services object - used for sending messages to the scene graph
519 * Assert if called from the wrong thread.
520 * This is intentionally inline for performance reasons.
522 * @return The event thread services object
524 inline EventThreadServices& GetEventThreadServices()
526 DALI_ASSERT_DEBUG( EventThreadServices::IsCoreRunning() );
527 return mEventThreadServices;
531 * Get the event thread services object - used for sending messages to the scene graph
532 * Assert if called from the wrong thread
533 * This is intentionally inline for performance reasons.
535 * @return The event thread services object
537 inline const EventThreadServices& GetEventThreadServices() const
539 DALI_ASSERT_DEBUG( EventThreadServices::IsCoreRunning() );
540 return mEventThreadServices;
545 EventThreadServices& mEventThreadServices;
549 Dali::Vector<Observer*> mObservers;
550 mutable OwnerContainer<PropertyMetadata*> mCustomProperties; ///< Used for accessing custom Node properties
551 mutable OwnerContainer<PropertyMetadata*> mAnimatableProperties; ///< Used for accessing animatable Node properties
552 mutable TypeInfo const * mTypeInfo; ///< The type-info for this object, mutable so it can be lazy initialized from const method if it is required
554 ConstraintContainer* mConstraints; ///< Container of owned -constraints.
556 using PropertyNotificationContainer = std::vector< Dali::PropertyNotification >;
557 PropertyNotificationContainer* mPropertyNotifications; ///< Container of owned property notifications.
558 DevelHandle::PropertySetSignalType mPropertySetSignal;
561 } // namespace Internal
563 // Helpers for public-api forwarding methods
565 inline Internal::Object& GetImplementation(Dali::Handle& object)
567 DALI_ASSERT_ALWAYS( object && "Object handle is empty" );
569 BaseObject& handle = object.GetBaseObject();
571 return static_cast<Internal::Object&>(handle);
574 inline const Internal::Object& GetImplementation(const Dali::Handle& object)
576 DALI_ASSERT_ALWAYS( object && "Object handle is empty" );
578 const BaseObject& handle = object.GetBaseObject();
580 return static_cast<const Internal::Object&>(handle);
585 #endif // __DALI_INTERNAL_OBJECT_H__