dali/internal/event/common/proxy-object.h

   1 #ifndef __DALI_INTERNAL_PROXY_OBJECT_H__
   2 #define __DALI_INTERNAL_PROXY_OBJECT_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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
  10 //
  11 //     http://floralicense.org/license/
  12 //
  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.
  18 //
  19
  20 // EXTERNAL INCLUDES
  21 #include <string>
  22
  23 // INTERNAL INCLUDES
  24 #include <dali/public-api/common/dali-vector.h>
  25 #include <dali/public-api/common/vector-wrapper.h>
  26 #include <dali/public-api/animation/active-constraint.h>
  27 #include <dali/public-api/animation/animation.h>
  28 #include <dali/public-api/animation/constraint.h>
  29 #include <dali/public-api/object/constrainable.h>
  30 #include <dali/public-api/object/property-input.h>
  31 #include <dali/public-api/object/property-notification.h>
  32 #include <dali/internal/event/common/object-impl.h>
  33 #include <dali/internal/event/common/custom-property.h>
  34 #include <dali/internal/event/common/property-input-impl.h>
  35 #include <dali/internal/update/common/property-base.h>
  36
  37 namespace Dali
  38 {
  39
  40 namespace Internal
  41 {
  42
  43 class Stage;
  44 class PropertyInputImpl;
  45 class ProxyObject;
  46 class Constraint;
  47 class TypeInfo;
  48
  49 namespace SceneGraph
  50 {
  51 class PropertyBase;
  52 class PropertyOwner;
  53 }
  54
  55 typedef std::vector< Dali::ActiveConstraint >     ActiveConstraintContainer;
  56 typedef ActiveConstraintContainer::iterator       ActiveConstraintIter;
  57 typedef ActiveConstraintContainer::const_iterator ActiveConstraintConstIter;
  58
  59 /**
  60  * A proxy for a property-owning object in the scene-graph.
  61  * This provides an interface for observing the addition/removal of scene-objects.
  62  *
  63  * The concrete derived class is responsible for:
  64  *   1) Adding & removing an object from the scene-graph. The OnSceneObjectAdd() and OnSceneObjectRemove()
  65  *      methods should be called by the derived class, to trigger observer callbacks.
  66  *   3) Implementing the GetSceneObject() methods, used to access the scene-object.
  67  *   4) Providing access to properties stored by the scene-graph object. These should match the properties
  68  *      reported by the base Dali::Internal::Object methods.
  69  */
  70 class ProxyObject : public Object
  71 {
  72 public:
  73
  74   class Observer
  75   {
  76   public:
  77
  78     /**
  79      * Called immediately after the proxy has created & passed ownership of a scene-graph object.
  80      * @param[in] proxy The proxy object.
  81      */
  82     virtual void SceneObjectAdded(ProxyObject& proxy) = 0;
  83
  84     /**
  85      * Called shortly before the proxy sends a message to remove its scene object.
  86      * @param[in] proxy The proxy object.
  87      */
  88     virtual void SceneObjectRemoved(ProxyObject& proxy) = 0;
  89
  90     /**
  91      * Called shortly before the proxy itself is destroyed; no further callbacks will be received.
  92      * @param[in] proxy The proxy object.
  93      */
  94     virtual void ProxyDestroyed(ProxyObject& proxy) = 0;
  95
  96   protected:
  97     /**
  98      * Virtual destructor
  99      */
 100     virtual ~Observer(){}
 101   };
 102
 103   /**
 104    * Constructor.
 105    */
 106   ProxyObject();
 107
 108   /**
 109    * Query whether the proxy object removes (& re-adds) its associated scene-object.
 110    * Otherwise the scene-object lifetime is expected to match that of the proxy.
 111    * @return True if scene-objects are removed.
 112    */
 113   virtual bool IsSceneObjectRemovable() const = 0;
 114
 115   /**
 116    * Add an observer to the proxy.
 117    * @param[in] observer The observer to add.
 118    */
 119   virtual void AddObserver(Observer& observer);
 120
 121   /**
 122    * Remove an observer from the proxy
 123    * @pre The observer has already been added.
 124    * @param[in] observer The observer to remove.
 125    */
 126   virtual void RemoveObserver(Observer& observer);
 127
 128   /**
 129    * Retrieve the scene-graph object added by this proxy.
 130    * @return A pointer to the object, or NULL if no object has been added to the scene-graph.
 131    */
 132   virtual const SceneGraph::PropertyOwner* GetSceneObject() const = 0;
 133
 134   /**
 135    * Retrieve an animatable property owned by the scene-graph object.
 136    * @pre -1 < index < GetPropertyCount().
 137    * @param[in] index The index of the property.
 138    * @return A dereferenceable pointer to a property, or NULL if a scene-object does not exist with this property.
 139    */
 140   virtual const SceneGraph::PropertyBase* GetSceneObjectAnimatableProperty( Property::Index index ) const = 0;
 141
 142   /**
 143    * Retrieve an constraint input-property owned by the scene-graph object.
 144    * @pre -1 < index < GetPropertyCount().
 145    * @param[in] index The index of the property.
 146    * @return A dereferenceable pointer to an input property, or NULL if a scene-object does not exist with this property.
 147    */
 148   virtual const PropertyInputImpl* GetSceneObjectInputProperty( Property::Index index ) const = 0;
 149
 150   /**
 151    * Query whether the property is a component of a scene-graph property.
 152    * @pre -1 < index < GetPropertyCount().
 153    * @param[in] index The index of the property.
 154    * @return The index or Property::INVALID_COMPONENT_INDEX.
 155    */
 156   virtual int GetPropertyComponentIndex( Property::Index index ) const;
 157
 158 public: // Property system interface from Internal::Object
 159
 160   /**
 161    * @copydoc Dali::Internal::Object::Supports()
 162    */
 163   virtual bool Supports( Object::Capability capability ) const;
 164
 165   /**
 166    * @copydoc Dali::Internal::Object::GetPropertyCount()
 167    */
 168   virtual unsigned int GetPropertyCount() const;
 169
 170   /**
 171    * @copydoc Dali::Internal::Object::GetPropertyName()
 172    */
 173   virtual const std::string& GetPropertyName( Property::Index index ) const;
 174
 175   /**
 176    * @copydoc Dali::Internal::Object::GetPropertyIndex()
 177    */
 178   virtual Property::Index GetPropertyIndex(const std::string& name) const;
 179
 180   /**
 181    * @copydoc Dali::Internal::Object::IsPropertyWritable()
 182    */
 183   virtual bool IsPropertyWritable(Property::Index index) const;
 184
 185   /**
 186    * @copydoc Dali::Internal::Object::IsPropertyAnimatable()
 187    */
 188   virtual bool IsPropertyAnimatable(Property::Index index) const;
 189
 190   /**
 191    * @copydoc Dali::Internal::Object::GetPropertyType()
 192    */
 193   virtual Property::Type GetPropertyType(Property::Index index) const;
 194
 195   /**
 196    * @copydoc Dali::Internal::Object::SetProperty()
 197    */
 198   virtual void SetProperty(Property::Index index, const Property::Value& propertyValue);
 199
 200   /**
 201    * @copydoc Dali::Internal::Object::GetProperty()
 202    */
 203   virtual Property::Value GetProperty(Property::Index index) const;
 204
 205   /**
 206    * @copydoc Dali::Handle::GetPropertyIndices()
 207    */
 208   virtual void GetPropertyIndices( Property::IndexContainer& indices ) const;
 209
 210   /**
 211    * @copydoc Dali::Internal::Object::RegisterProperty()
 212    */
 213   virtual Property::Index RegisterProperty(std::string name, const Property::Value& propertyValue);
 214
 215   /**
 216    * @copydoc Dali::Handle::RegisterProperty(std::string name, Property::Value propertyValue, Property::AccessMode accessMode)
 217    */
 218   virtual Property::Index RegisterProperty(std::string name, const Property::Value& propertyValue, Property::AccessMode accessMode);
 219
 220   /**
 221    * @copydoc Dali::Handle::AddPropertyNotification()
 222    */
 223   virtual Dali::PropertyNotification AddPropertyNotification(Property::Index index,
 224                                                              int componentIndex,
 225                                                              const Dali::PropertyCondition& condition);
 226
 227   /**
 228    * @copydoc Dali::Handle::RemovePropertyNotification()
 229    */
 230   virtual void RemovePropertyNotification(Dali::PropertyNotification propertyNotification);
 231
 232   /**
 233    * @copydoc Dali::Handle::RemovePropertyNotifications()
 234    */
 235   void RemovePropertyNotifications();
 236
 237 private:
 238   /**
 239    * Enable property notifications in scene graph
 240    */
 241   void EnablePropertyNotifications();
 242
 243   /**
 244    * Enable property notifications in scene graph
 245    */
 246   void DisablePropertyNotifications();
 247
 248 public: // Constraints
 249
 250   /**
 251    * Apply a constraint to a ProxyObject.
 252    * @param[in] constraint The constraint to apply.
 253    */
 254   Dali::ActiveConstraint ApplyConstraint( Constraint& constraint );
 255
 256   /**
 257    * Apply a constraint to a ProxyObject.
 258    * @param[in] constraint The constraint to apply.
 259    * @param[in] callback This method will be called at the end of the constraint apply-time.
 260    */
 261   Dali::ActiveConstraint ApplyConstraint( Constraint& constraint, ActiveConstraintCallbackType callback );
 262
 263   /**
 264    * Remove one constraint from a ProxyObject.
 265    * @param[in] activeConstraint The active constraint to remove.
 266    */
 267   void RemoveConstraint( Dali::ActiveConstraint activeConstraint );
 268
 269   /**
 270    * Remove all constraints from a ProxyObject.
 271    */
 272   void RemoveConstraints();
 273
 274 protected:
 275
 276   /**
 277    * Called immediately by derived classes, after the scene-object has been created & passed to the scene-graph.
 278    */
 279   void OnSceneObjectAdd();
 280
 281   /**
 282    * Called by derived classes, shortly before send a message to remove the scene-object.
 283    */
 284   void OnSceneObjectRemove();
 285
 286   /**
 287    * A reference counted object may only be deleted by calling Unreference()
 288    */
 289   virtual ~ProxyObject();
 290
 291 private:
 292
 293   // Undefined
 294   ProxyObject(const ProxyObject&);
 295
 296   // Undefined
 297   ProxyObject& operator=(const ProxyObject& rhs);
 298
 299   /**
 300    * Helper for ApplyConstraint overloads.
 301    * @return The new active-constraint which is owned by ProxyObject.
 302    */
 303   ActiveConstraintBase* DoApplyConstraint( Constraint& constraint, ActiveConstraintCallbackType* callback );
 304
 305   /**
 306    * Helper to delete removed constraints
 307    */
 308   void DeleteRemovedConstraints();
 309
 310 private: // Default property extensions for derived classes
 311
 312   /**
 313    * Query how many default properties the derived class supports.
 314    * @return The number of default properties.
 315    */
 316   virtual unsigned int GetDefaultPropertyCount() const = 0;
 317
 318   /**
 319    * Retrieve all the indices that are associated with the default properties supported by the derived class.
 320    * @return A container of default property indices.
 321    * @note The deriving class must not modify the existing elements in the container.
 322    */
 323   virtual void GetDefaultPropertyIndices( Property::IndexContainer& indices ) const = 0;
 324
 325   /**
 326    * Query how many default properties the derived class supports.
 327    * @pre Property::INVALID_INDEX < index < GetDefaultPropertyCount().
 328    * @return The number of default properties.
 329    */
 330   virtual const std::string& GetDefaultPropertyName( Property::Index index ) const = 0;
 331
 332   /**
 333    * Query the index of a default property.
 334    * @param [in] name The name of the property.
 335    * @return The index of the property, or Property::INVALID_INDEX if no default property exists with the given name.
 336    */
 337   virtual Property::Index GetDefaultPropertyIndex( const std::string& name ) const = 0;
 338
 339   /**
 340    * Query whether a default property is writable.
 341    * @pre Property::INVALID_INDEX < index < GetDefaultPropertyCount().
 342    * @param [in] index The index of the property.
 343    * @return True if the property is animatable.
 344    */
 345   virtual bool IsDefaultPropertyWritable( Property::Index index ) const = 0;
 346
 347   /**
 348    * Query whether a default property is animatable.
 349    * This determines whether the property can be the target of an animation or constraint.
 350    * @pre Property::INVALID_INDEX < index < GetDefaultPropertyCount().
 351    * @param [in] index The index of the property.
 352    * @return True if the property is animatable.
 353    */
 354   virtual bool IsDefaultPropertyAnimatable( Property::Index index ) const = 0;
 355
 356   /**
 357    * Query the type of a default property.
 358    * @pre Property::INVALID_INDEX < index < GetDefaultPropertyCount().
 359    * @param [in] index The index of the property.
 360    * @return The type of the property.
 361    */
 362   virtual Property::Type GetDefaultPropertyType( Property::Index index ) const = 0;
 363
 364   /**
 365    * Set the value of a default property.
 366    * @pre Property::INVALID_INDEX < index < GetDefaultPropertyCount().
 367    * @pre The property types match i.e. propertyValue.GetType() is equal to GetPropertyType(index).
 368    * @param [in] index The index of the property.
 369    * @param [in] propertyValue The new value of the property.
 370    */
 371   virtual void SetDefaultProperty( Property::Index index, const Property::Value& propertyValue ) = 0;
 372
 373   /**
 374    * Set the value of custom property.
 375    * @param [in] index The index of the property.
 376    * @param [in] entry An entry from the CustomPropertyLookup.
 377    * @param [in] value The new value of the property.
 378    */
 379   virtual void SetCustomProperty( Property::Index index, const CustomProperty& entry, const Property::Value& value );
 380
 381   /**
 382    * Retrieve a default property value.
 383    * @pre Property::INVALID_INDEX < index < GetDefaultPropertyCount().
 384    * @param [in] index The index of the property.
 385    * @return The property value.
 386    */
 387   virtual Property::Value GetDefaultProperty( Property::Index index ) const = 0;
 388
 389   /**
 390    * Install a newly allocated scene-object property.
 391    * The derived class is responsible for this, since the type of scene-object is not known to this base class.
 392    * @param [in] newProperty A newly allocated scene-object property.
 393    * @param [in] name The name allocated to this custom property.
 394    * @param [in] index The index allocated to this custom property.
 395    */
 396   virtual void InstallSceneObjectProperty( SceneGraph::PropertyBase& newProperty, const std::string& name, unsigned int index ) = 0;
 397
 398 protected:
 399
 400   /**
 401    * Not all proxy objects will have custom properties so we want to only create the lookup when its actually needed
 402    * @return the custom property lookup
 403    */
 404   CustomPropertyLookup& GetCustomPropertyLookup() const;
 405
 406   /**
 407    * Retrieves the TypeInfo for this object. Only retrieves it from the type-registry once and then stores a pointer
 408    * to it locally there-after. The type info will not change during the life-time of the application.
 409    * @return The type-info for this object (Can be NULL)
 410    */
 411   TypeInfo* GetTypeInfo() const;
 412
 413 private:
 414
 415   mutable TypeInfo* mTypeInfo; ///< The type-info for this object, mutable so it can be lazy initialized from const method if it is required
 416
 417   Property::Index mNextCustomPropertyIndex; ///< The ID of the next custom property to be registered
 418
 419   mutable CustomPropertyLookup* mCustomProperties; ///< Used for accessing custom Node properties, mutable so it can be lazy initialized from const function
 420
 421   Dali::Vector<Observer*> mObservers;
 422
 423   ActiveConstraintContainer* mConstraints;               ///< Container of owned active-constraints.
 424   ActiveConstraintContainer* mRemovedConstraints;        ///< Container of owned active-constraints, which are being removed.
 425
 426   typedef std::vector< Dali::PropertyNotification >     PropertyNotificationContainer;
 427   typedef PropertyNotificationContainer::iterator       PropertyNotificationContainerIter;
 428   typedef PropertyNotificationContainer::const_iterator PropertyNotificationContainerConstIter;
 429   PropertyNotificationContainer* mPropertyNotifications; ///< Container of owned property notifications.
 430 };
 431
 432 } // namespace Internal
 433
 434 inline Internal::ProxyObject& GetImplementation(Dali::Constrainable& object)
 435 {
 436   DALI_ASSERT_ALWAYS( object && "ProxyObject handle is empty" );
 437   BaseObject& handle = object.GetBaseObject();
 438   return static_cast<Internal::ProxyObject&>(handle);
 439 }
 440
 441 inline const Internal::ProxyObject& GetImplementation(const Dali::Constrainable& object)
 442 {
 443   DALI_ASSERT_ALWAYS( object && "ProxyObject handle is empty" );
 444   const BaseObject& handle = object.GetBaseObject();
 445   return static_cast<const Internal::ProxyObject&>(handle);
 446 }
 447
 448
 449 } // namespace Dali
 450
 451 #endif // __DALI_INTERNAL_PROXY_OBJECT_H__