1 #ifndef DALI_CONSTRAINT_H
2 #define DALI_CONSTRAINT_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-source.h>
26 #include <dali/public-api/common/dali-vector.h>
27 #include <dali/public-api/object/base-handle.h>
28 #include <dali/public-api/object/property.h>
29 #include <dali/public-api/object/property-input.h>
30 #include <dali/public-api/signals/callback.h>
35 * @addtogroup dali_core_animation
41 namespace Internal DALI_INTERNAL
46 typedef Vector< PropertyInput* > PropertyInputContainer;
49 * @brief An abstract base class for Constraints.
51 * This can be used to constrain a property of an object, after animations have been applied.
52 * Constraints are applied in the following order:
53 * - Constraints are applied to on-stage actors in a depth-first traversal.
54 * - For each actor, the constraints are applied in the same order as the calls to Apply().
55 * - Constraints are not applied to off-stage actors.
57 * Create a constraint using one of the New methods depending on the type of callback function used.
58 * Try to use a C function unless some data needs to be stored, otherwise functors and class methods
61 * A constraint can be applied to an object in the following manner:
64 * Handle handle = CreateMyObject();
65 * Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, &MyFunction );
66 * constraint.AddSource( LocalSource( INPUT_PROPERTY_INDEX ) );
71 class DALI_CORE_API Constraint : public BaseHandle
76 * @brief Template for the Function that is called by the Constraint system.
80 * - Static member methods of an object
81 * - Member functions of a particular class
82 * - Functors of a particular class
83 * - If a functor or method is provided, then a copy of the object is made.
85 * The expected signature of the callback should be:
87 * void Function( P&, const PropertyInputContainer& );
90 * The P& parameter is an in,out parameter which stores the current value of the property. The callback
91 * should change this value to the desired one. The PropertyInputContainer is a const reference to the property inputs
92 * added to the Constraint in the order they were added via AddSource().
95 * @tparam P The property type to constrain
97 template< typename P >
98 class DALI_INTERNAL Function : public CallbackBase
103 * @brief Constructor which connects to the provided C function (or a static member function).
105 * The expected signature of the function is:
107 * void MyFunction( P&, const PropertyInputContainer& );
111 * @param[in] function The function to call
113 Function( void( *function )( P&, const PropertyInputContainer& ) )
114 : CallbackBase( reinterpret_cast< CallbackBase::Function >( function ) ),
115 mCopyConstructorDispatcher( NULL )
120 * @brief Constructor which copies a function object and connects to the functor of that object.
122 * The function object should have a functor with the following signature:
124 * void operator()( P&, const PropertyInputContainer& );
128 * @param[in] object The object to copy
129 * @tparam T The type of the object
132 Function( const T& object )
133 : CallbackBase( reinterpret_cast< void* >( new T( object ) ), // copy the object
134 NULL, // uses operator() instead of member function
135 reinterpret_cast< CallbackBase::Dispatcher >( &FunctorDispatcher2< T, P&, const PropertyInputContainer& >::Dispatch ),
136 reinterpret_cast< CallbackBase::Destructor >( &Destroyer< T >::Delete ) ),
137 mCopyConstructorDispatcher( reinterpret_cast< CopyConstructorDispatcher >( &ObjectCopyConstructorDispatcher< T >::Copy ) )
142 * @brief Constructor which copies a function object and allows a connection to a member method.
144 * The object should have a method with the signature:
146 * void MyObject::MyMethod( P&, const PropertyInputContainer& );
150 * @param[in] object The object to copy
151 * @param[in] memberFunction The member function to call. This has to be a member of the same class
152 * @tparam T The type of the object
155 Function( const T& object, void ( T::*memberFunction ) ( P&, const PropertyInputContainer& ) )
156 : CallbackBase( reinterpret_cast< void* >( new T( object ) ), // copy the object
157 reinterpret_cast< CallbackBase::MemberFunction >( memberFunction ),
158 reinterpret_cast< CallbackBase::Dispatcher >( &Dispatcher2< T, P&, const PropertyInputContainer& >::Dispatch ),
159 reinterpret_cast< CallbackBase::Destructor >( &Destroyer< T >::Delete ) ),
160 mCopyConstructorDispatcher( reinterpret_cast< CopyConstructorDispatcher >( &ObjectCopyConstructorDispatcher< T >::Copy ) )
165 * @brief Clones the Function object.
167 * The object, if held by this object, is also copied.
170 * @return A pointer to a newly-allocated Function
172 CallbackBase* Clone()
174 CallbackBase* callback = NULL;
175 if ( mImpl && mImpl->mObjectPointer && mCopyConstructorDispatcher )
177 callback = new Function( mCopyConstructorDispatcher( reinterpret_cast< UndefinedClass* >( mImpl->mObjectPointer ) ) /* Copy the object */,
179 mImpl->mMemberFunctionDispatcher,
180 mImpl->mDestructorDispatcher,
181 mCopyConstructorDispatcher );
185 callback = new Function( mFunction );
193 * @brief Must not be declared.
195 * This is used so that no optimisations are done by the compiler when using void*.
197 class UndefinedClass;
200 * @brief Used to call the function to copy the stored object.
203 typedef UndefinedClass* (*CopyConstructorDispatcher) ( UndefinedClass* object );
206 * @brief Copies the actual object in Constraint::Function.
209 * @tparam T The type of the object
212 struct ObjectCopyConstructorDispatcher
215 * @brief Copies the object stored in Constraint::Function.
218 * @param[in] object The object to copy
219 * @return Newly allocated clone of the object
221 static UndefinedClass* Copy( const UndefinedClass* object )
223 T* copy = new T( *( reinterpret_cast< const T* >( object ) ) );
224 return reinterpret_cast< UndefinedClass* >( copy );
229 * @brief Undefined copy constructor.
232 Function( const Function& );
235 * @brief Undefined assignment operator.
238 Function& operator=( const Function& );
241 * @brief Constructor used when copying the stored object.
244 * @param[in] object A newly copied object
245 * @param[in] memberFunction The member function of the object
246 * @param[in] dispatcher Used to call the actual object
247 * @param[in] destructor Used to delete the owned object
248 * @param[in] copyConstructorDispatcher Used to create a copy of the owned object
250 Function( void* object,
251 CallbackBase::MemberFunction memberFunction,
252 CallbackBase::Dispatcher dispatcher,
253 CallbackBase::Destructor destructor,
254 CopyConstructorDispatcher copyConstructorDispatcher )
255 : CallbackBase( object, memberFunction, dispatcher, destructor ),
256 mCopyConstructorDispatcher( copyConstructorDispatcher )
261 * @brief Constructor used when copying a simple stored function.
264 * @param[in] function The function to call
266 Function( CallbackBase::Function function )
267 : CallbackBase( function ),
268 mCopyConstructorDispatcher( NULL )
274 CopyConstructorDispatcher mCopyConstructorDispatcher; ///< Function to call to copy the stored object
278 * @brief Enumeration for the action that will happen when the constraint is removed.
280 * The final value may be "baked" i.e. saved permanently.
281 * Alternatively the constrained value may be discarded when the constraint is removed.
286 Bake, ///< When the constraint is fully-applied, the constrained value is saved. @SINCE_1_0.0
287 Discard ///< When the constraint is removed, the constrained value is discarded. @SINCE_1_0.0
290 static const RemoveAction DEFAULT_REMOVE_ACTION; ///< Bake
293 * @brief Creates an uninitialized Constraint; this can be initialized with Constraint::New().
295 * Calling member functions with an uninitialized Constraint handle is not allowed.
301 * @brief Creates a constraint which targets a property using a function or a static class member.
303 * The expected signature, for a Vector3 type for example, of the function is:
305 * void MyFunction( Vector3&, const PropertyInputContainer& );
308 * Create the constraint with this function as follows:
311 * Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, &MyFunction );
315 * @param[in] handle The handle to the property-owning object
316 * @param[in] targetIndex The index of the property to constrain
317 * @param[in] function The function to call to set the constrained property value
319 * @tparam P The type of the property to constrain
320 * @return The new constraint
323 static Constraint New( Handle handle, Property::Index targetIndex, void( *function )( P&, const PropertyInputContainer& ) )
325 CallbackBase* callback = new Constraint::Function< P >( function );
326 return New( handle, targetIndex, PropertyTypes::Get< P >(), callback );
330 * @brief Creates a constraint which targets a property using a functor object.
332 * The expected structure, for a Vector3 type for example, of the functor object is:
336 * void operator() ( Vector3&, const PropertyInputContainer& );
340 * Create the constraint with this object as follows:
343 * Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, MyObject() );
347 * @param[in] handle The handle to the property-owning object
348 * @param[in] targetIndex The index of the property to constraint
349 * @param[in] object The functor object whose functor is called to set the constrained property value
351 * @tparam P The type of the property to constrain
352 * @tparam T The type of the object
353 * @return The new constraint
355 template< class P, class T >
356 static Constraint New( Handle handle, Property::Index targetIndex, const T& object )
358 CallbackBase* function = new Constraint::Function< P >( object );
359 return New( handle, targetIndex, PropertyTypes::Get< P >(), function );
363 * @brief Creates a constraint which targets a property using an object method.
365 * The expected structure, for a Vector3 type for example, of the object is:
369 * void MyMethod( Vector3&, const PropertyInputContainer& );
373 * Create the constraint with this object as follows:
376 * Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, MyObject(), &MyObject::MyMethod );
380 * @param[in] handle The handle to the property-owning object
381 * @param[in] targetIndex The index of the property to constraint
382 * @param[in] object The object whose member function is called to set the constrained property value
383 * @param[in] memberFunction The member function to call to set the constrained property value
384 * @return The new constraint
386 * @tparam P The type of the property to constrain
387 * @tparam T The type of the object
389 template< class P, class T >
390 static Constraint New( Handle handle, Property::Index targetIndex, const T& object, void ( T::*memberFunction ) ( P&, const PropertyInputContainer& ) )
392 CallbackBase* function = new Constraint::Function< P >( object, memberFunction );
393 return New( handle, targetIndex, PropertyTypes::Get< P >(), function );
397 * @brief Creates a clone of this constraint for another object.
400 * @param[in] handle The handle to the property-owning object this constraint is to be cloned for
401 * @return The new constraint
403 Constraint Clone( Handle handle );
408 * This is non-virtual since derived Handle types must not contain data or virtual methods.
414 * @brief This copy constructor is required for (smart) pointer semantics.
417 * @param[in] constraint A reference to the copied handle
419 Constraint( const Constraint& constraint );
422 * @brief This assignment operator is required for (smart) pointer semantics.
425 * @param[in] rhs A reference to the copied handle
426 * @return A reference to this
428 Constraint& operator=( const Constraint& rhs );
431 * @brief Downcasts a handle to Constraint handle.
433 * If handle points to a Constraint object, the downcast produces valid handle.
434 * If not, the returned handle is left uninitialized.
436 * @param[in] baseHandle BaseHandle to an object
437 * @return Handle to a Constraint object or an uninitialized handle
439 static Constraint DownCast( BaseHandle baseHandle );
442 * @brief Adds a constraint source to the constraint.
445 * @param[in] source The constraint source input to add
447 void AddSource( ConstraintSource source );
450 * @brief Applies this constraint.
453 * @pre The constraint must be initialized.
454 * @pre The target object must still be alive.
455 * @pre The source inputs should not have been destroyed.
460 * @brief Removes this constraint.
466 * @brief Retrieves the object which this constraint is targeting.
469 * @return The target object
471 Handle GetTargetObject();
474 * @brief Retrieves the property which this constraint is targeting.
477 * @return The target property
479 Dali::Property::Index GetTargetProperty();
482 * @brief Sets the remove action. Constraint::Bake will "bake" a value when fully-applied.
484 * In case of Constraint::Discard, the constrained value will be discarded, when the constraint is removed.
485 * The default value is Constraint::Bake.
487 * @param[in] action The remove-action
489 void SetRemoveAction( RemoveAction action );
492 * @brief Retrieves the remove action that will happen when the constraint is removed.
495 * @return The remove-action
497 RemoveAction GetRemoveAction() const;
500 * @brief Sets a tag for the constraint so it can be identified later.
503 * @param[in] tag An integer to identify the constraint
505 void SetTag( uint32_t tag );
508 * @brief Gets the tag.
513 uint32_t GetTag() const;
515 public: // Not intended for use by Application developers
519 * @brief This constructor is used by Constraint::New() methods.
521 * @param[in] constraint A pointer to a newly allocated Dali resource
523 explicit DALI_INTERNAL Constraint( Internal::ConstraintBase* constraint );
526 private: // Not intended for use by Application developers
530 * @brief Constructs a new constraint which targets a property.
533 * @param[in] handle The handle to the property-owning object
534 * @param[in] targetIndex The index of the property to constrain
535 * @param[in] targetType Type The type of the constrained property
536 * @param[in] function The constraint function
537 * @return The new constraint
539 static Constraint New( Handle handle, Property::Index targetIndex, Property::Type targetType, CallbackBase* function );
548 #endif // DALI_CONSTRAINT_H