1 #ifndef __DALI_CONSTRAINT_H__
2 #define __DALI_CONSTRAINT_H__
5 * Copyright (c) 2014 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 <boost/function.hpp>
25 #include <dali/public-api/animation/alpha-functions.h>
26 #include <dali/public-api/animation/constraint-source.h>
27 #include <dali/public-api/animation/interpolator-functions.h>
28 #include <dali/public-api/object/any.h>
29 #include <dali/public-api/object/handle.h>
30 #include <dali/public-api/object/property.h>
31 #include <dali/public-api/object/property-input.h>
37 namespace Internal DALI_INTERNAL
43 * @brief An abstract base class for Constraints.
44 * This can be used to constrain a property of an actor, after animations have been applied.
45 * Constraints are applied in the following order:
46 * - Constraints are applied to on-stage actors in a depth-first traversal.
47 * - For each actor, the constraints are applied in the same order as the calls to Actor::ApplyConstraint().
48 * - Constraints are not applied to off-stage actors.
50 class DALI_IMPORT_API Constraint : public BaseHandle
54 typedef Any AnyFunction; ///< Generic function pointer for constraint and interpolator functions
57 * @brief The action that will happen when the constraint is removed.
59 * Constraints can be applied gradually; see SetApplyTime() for more details.
60 * When a constraint is fully-applied the final value may be "baked" i.e. saved permanently.
61 * Alternatively the constrained value may be discarded when the constraint is removed.
65 Bake, ///< When the constraint is fully-applied, the constrained value is saved.
66 Discard ///< When the constraint is removed, the constrained value is discarded.
69 static const AlphaFunction DEFAULT_ALPHA_FUNCTION; ///< AlphaFunctions::Linear
70 static const RemoveAction DEFAULT_REMOVE_ACTION; ///< Bake
73 * @brief Create an uninitialized Constraint; this can be initialized with Constraint::New().
75 * Calling member functions with an uninitialized Dali::Object is not allowed.
80 * @brief Create a constraint which targets a property.
82 * The templated parameter P, is the type of the property to constrain.
83 * Animation will be performed using the default interpolator.
84 * @param [in] target The index of the property to constrain.
85 * @param [in] func A function which returns the constrained property value.
86 * @return The new constraint.
89 static Constraint New( Property::Index target,
90 boost::function<P (const P& current)> func )
93 PropertyTypes::Get<P>(),
95 GetDefaultInterpolator( PropertyTypes::Get<P>() ) );
99 * @brief Create a constraint which targets a property.
101 * The templated parameter P, is the type of the property to constrain.
102 * @param [in] target The index of the property to constrain.
103 * @param [in] func A function which returns the constrained property value.
104 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
105 * @return The new constraint.
108 static Constraint NewWithInterpolator( Property::Index target,
109 boost::function<P (const P& current)> func,
110 boost::function<P (const P&, const P&, float)> interpolator )
113 PropertyTypes::Get<P>(),
119 * @brief Create a constraint which targets a property.
121 * The templated parameter P, is the type of the property to constrain.
122 * Animation will be performed using the default interpolator.
123 * @param [in] target The index of the property to constrain.
124 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
125 * @param [in] func A function which returns the constrained property value.
126 * @return The new constraint.
129 static Constraint New( Property::Index target,
130 ConstraintSource source1,
131 boost::function<P (const P& current, const PropertyInput& input1)> func )
134 PropertyTypes::Get<P>(),
137 GetDefaultInterpolator( PropertyTypes::Get<P>() ) );
141 * @brief Create a constraint which targets a property.
143 * The templated parameter P, is the type of the property to constrain.
144 * @param [in] target The index of the property to constrain.
145 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
146 * @param [in] func A function which returns the constrained property value.
147 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
148 * @return The new constraint.
151 static Constraint NewWithInterpolator( Property::Index target,
152 ConstraintSource source1,
153 boost::function<P (const P& current, const PropertyInput& input1)> func,
154 boost::function<P (const P&, const P&, float)> interpolator )
157 PropertyTypes::Get<P>(),
164 * @brief Create a constraint which targets a property.
166 * The templated parameter P, is the type of the property to constrain.
167 * Animation will be performed using the default interpolator.
168 * @param [in] target The index of the property to constrain.
169 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
170 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
171 * @param [in] func A function which returns the constrained property value.
172 * @return The new constraint.
175 static Constraint New( Property::Index target,
176 ConstraintSource source1,
177 ConstraintSource source2,
178 boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2)> func )
181 PropertyTypes::Get<P>(),
185 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
189 * @brief Create a constraint which targets a property.
191 * The templated parameter P, is the type of the property to constrain.
192 * @param [in] target The index of the property to constrain.
193 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
194 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
195 * @param [in] func A function which returns the constrained property value.
196 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
197 * @return The new constraint.
200 static Constraint NewWithInterpolator( Property::Index target,
201 ConstraintSource source1,
202 ConstraintSource source2,
203 boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2)> func,
204 boost::function<P (const P&, const P&, float)> interpolator )
207 PropertyTypes::Get<P>(),
215 * @brief Create a constraint which targets a property.
217 * The templated parameter P, is the type of the property to constrain.
218 * Animation will be performed using the default interpolator.
219 * @param [in] target The index of the property to constrain.
220 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
221 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
222 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
223 * @param [in] func A function which returns the constrained property value.
224 * @return The new constraint.
227 static Constraint New( Property::Index target,
228 ConstraintSource source1,
229 ConstraintSource source2,
230 ConstraintSource source3,
231 boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2, const PropertyInput& input3)> func )
234 PropertyTypes::Get<P>(),
239 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
243 * @brief Create a constraint which targets a property.
245 * The templated parameter P, is the type of the property to constrain.
246 * @param [in] target The index of the property to constrain.
247 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
248 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
249 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
250 * @param [in] func A function which returns the constrained property value.
251 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
252 * @return The new constraint.
255 static Constraint NewWithInterpolator( Property::Index target,
256 ConstraintSource source1,
257 ConstraintSource source2,
258 ConstraintSource source3,
259 boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2, const PropertyInput& input3)> func,
260 boost::function<P (const P&, const P&, float)> interpolator )
263 PropertyTypes::Get<P>(),
272 * @brief Create a constraint which targets a property.
274 * The templated parameter P, is the type of the property to constrain.
275 * Animation will be performed using the default interpolator.
276 * @param [in] target The index of the property to constrain.
277 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
278 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
279 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
280 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
281 * @param [in] func A function which returns the constrained property value.
282 * @return The new constraint.
285 static Constraint New( Property::Index target,
286 ConstraintSource source1,
287 ConstraintSource source2,
288 ConstraintSource source3,
289 ConstraintSource source4,
290 boost::function<P (const P& current,
291 const PropertyInput& input1,
292 const PropertyInput& input2,
293 const PropertyInput& input3,
294 const PropertyInput& input4)> func )
297 PropertyTypes::Get<P>(),
303 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
307 * @brief Create a constraint which targets a property.
309 * The templated parameter P, is the type of the property to constrain.
310 * @param [in] target The index of the property to constrain.
311 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
312 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
313 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
314 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
315 * @param [in] func A function which returns the constrained property value.
316 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
317 * @return The new constraint.
320 static Constraint NewWithInterpolator( Property::Index target,
321 ConstraintSource source1,
322 ConstraintSource source2,
323 ConstraintSource source3,
324 ConstraintSource source4,
325 boost::function<P (const P& current,
326 const PropertyInput& input1,
327 const PropertyInput& input2,
328 const PropertyInput& input3,
329 const PropertyInput& input4)> func,
330 boost::function<P (const P&, const P&, float)> interpolator )
333 PropertyTypes::Get<P>(),
343 * @brief Create a constraint which targets a property.
345 * The templated parameter P, is the type of the property to constrain.
346 * Animation will be performed using the default interpolator.
347 * @param [in] target The index of the property to constrain.
348 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
349 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
350 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
351 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
352 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
353 * @param [in] func A function which returns the constrained property value.
354 * @return The new constraint.
357 static Constraint New( Property::Index target,
358 ConstraintSource source1,
359 ConstraintSource source2,
360 ConstraintSource source3,
361 ConstraintSource source4,
362 ConstraintSource source5,
363 boost::function<P (const P& current,
364 const PropertyInput& input1,
365 const PropertyInput& input2,
366 const PropertyInput& input3,
367 const PropertyInput& input4,
368 const PropertyInput& input5)> func )
371 PropertyTypes::Get<P>(),
378 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
382 * @brief Create a constraint which targets a property.
384 * The templated parameter P, is the type of the property to constrain.
385 * @param [in] target The index of the property to constrain.
386 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
387 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
388 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
389 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
390 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
391 * @param [in] func A function which returns the constrained property value.
392 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
393 * @return The new constraint.
396 static Constraint NewWithInterpolator( Property::Index target,
397 ConstraintSource source1,
398 ConstraintSource source2,
399 ConstraintSource source3,
400 ConstraintSource source4,
401 ConstraintSource source5,
402 boost::function<P (const P& current,
403 const PropertyInput& input1,
404 const PropertyInput& input2,
405 const PropertyInput& input3,
406 const PropertyInput& input4,
407 const PropertyInput& input5)> func,
408 boost::function<P (const P&, const P&, float)> interpolator )
411 PropertyTypes::Get<P>(),
422 * @brief Create a constraint which targets a property.
424 * The templated parameter P, is the type of the property to constrain.
425 * Animation will be performed using the default interpolator.
426 * @param [in] target The index of the property to constrain.
427 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
428 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
429 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
430 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
431 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
432 * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func.
433 * @param [in] func A function which returns the constrained property value.
434 * @return The new constraint.
437 static Constraint New( Property::Index target,
438 ConstraintSource source1,
439 ConstraintSource source2,
440 ConstraintSource source3,
441 ConstraintSource source4,
442 ConstraintSource source5,
443 ConstraintSource source6,
444 boost::function<P (const P& current,
445 const PropertyInput& input1,
446 const PropertyInput& input2,
447 const PropertyInput& input3,
448 const PropertyInput& input4,
449 const PropertyInput& input5,
450 const PropertyInput& input6)> func )
453 PropertyTypes::Get<P>(),
461 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
465 * @brief Create a constraint which targets a property.
467 * The templated parameter P, is the type of the property to constrain.
468 * @param [in] target The index of the property to constrain.
469 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
470 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
471 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
472 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
473 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
474 * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func.
475 * @param [in] func A function which returns the constrained property value.
476 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
477 * @return The new constraint.
480 static Constraint NewWithInterpolator( Property::Index target,
481 ConstraintSource source1,
482 ConstraintSource source2,
483 ConstraintSource source3,
484 ConstraintSource source4,
485 ConstraintSource source5,
486 ConstraintSource source6,
487 boost::function<P (const P& current,
488 const PropertyInput& input1,
489 const PropertyInput& input2,
490 const PropertyInput& input3,
491 const PropertyInput& input4,
492 const PropertyInput& input5,
493 const PropertyInput& input6)> func,
494 boost::function<P (const P&, const P&, float)> interpolator )
497 PropertyTypes::Get<P>(),
509 * @brief Downcast an Object handle to Constraint handle.
511 * If handle points to a Constraint object the
512 * downcast produces valid handle. If not the returned handle is left uninitialized.
513 * @param[in] handle to An object
514 * @return handle to a Constraint object or an uninitialized handle
516 static Constraint DownCast( BaseHandle handle );
521 * This is non-virtual since derived Handle types must not contain data or virtual methods.
526 * @brief This copy constructor is required for (smart) pointer semantics.
528 * @param [in] handle A reference to the copied handle
530 Constraint(const Constraint& handle);
533 * @brief This assignment operator is required for (smart) pointer semantics.
535 * @param [in] rhs A reference to the copied handle
536 * @return A reference to this
538 Constraint& operator=(const Constraint& rhs);
541 * @brief Set the time taken for the constraint to be fully applied.
543 * The default is zero, meaning that the constraint is applied immediately.
544 * @param [in] timePeriod The constraint will be applied during this time period.
546 void SetApplyTime( TimePeriod timePeriod );
549 * @brief Retrieve the time taken for the constraint to be fully applied.
551 * @return The apply time.
553 TimePeriod GetApplyTime() const;
556 * @brief Set the alpha function for a constraint; the default is AlphaFunctions::Linear.
558 * @param [in] func The alpha function to use when applying/removing the constraint.
560 void SetAlphaFunction( AlphaFunction func );
563 * @brief Retrieve the alpha function of a constraint.
565 * @return The function.
567 AlphaFunction GetAlphaFunction();
570 * @brief Set whether the constraint will "bake" a value when fully-applied.
572 * Otherwise the constrained value will be discarded, when the constraint is removed.
573 * The default value is Constraint::Bake.
574 * @param[in] action The remove-action.
576 void SetRemoveAction( RemoveAction action );
579 * @brief Query whether the constraint will "bake" a value when fully-applied.
581 * Otherwise the constrained value will be discarded, when the constraint is removed.
582 * @return The apply-action.
584 RemoveAction GetRemoveAction() const;
587 * @brief Set a tag for the constraint so it can be identified later
589 * @param[in] tag An integer to identify the constraint
591 void SetTag( const unsigned int tag );
598 unsigned int GetTag() const;
600 public: // Not intended for use by Application developers
603 * @brief This constructor is used by Dali New() methods
604 * @param [in] constraint A pointer to a newly allocated Dali resource
606 explicit DALI_INTERNAL Constraint( Internal::Constraint* constraint );
608 private: // Not intended for use by Application developers
611 * @brief Construct a new constraint which targets a property.
613 * @param [in] target The index of the property to constrain.
614 * @param [in] targetType The type of the constrained property.
615 * @param [in] func The constraint function.
616 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
617 * @return The new constraint.
619 static Constraint New( Property::Index target,
620 Property::Type targetType,
622 AnyFunction interpolator );
625 * @brief Construct a new constraint which targets a property.
627 * @param [in] target The index of the property to constrain.
628 * @param [in] targetType The type of the constrained property.
629 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
630 * @param [in] func The constraint function.
631 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
632 * @return The new constraint.
634 static Constraint New( Property::Index target,
635 Property::Type targetType,
636 ConstraintSource source1,
638 AnyFunction interpolator );
641 * @brief Construct a new constraint which targets a property.
643 * @param [in] target The index of the property to constrain.
644 * @param [in] targetType The type of the constrained property.
645 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
646 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
647 * @param [in] func The constraint function.
648 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
649 * @return The new constraint.
651 static Constraint New( Property::Index target,
652 Property::Type targetType,
653 ConstraintSource source1,
654 ConstraintSource source2,
656 AnyFunction interpolator );
659 * @brief Construct a new constraint which targets a property.
661 * @param [in] target The index of the property to constrain.
662 * @param [in] targetType The type of the constrained property.
663 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
664 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
665 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
666 * @param [in] func The constraint function.
667 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
668 * @return The new constraint.
670 static Constraint New( Property::Index target,
671 Property::Type targetType,
672 ConstraintSource source1,
673 ConstraintSource source2,
674 ConstraintSource source3,
676 AnyFunction interpolator );
679 * @brief Construct a new constraint which targets a property.
681 * @param [in] target The index of the property to constrain.
682 * @param [in] targetType The type of the constrained property.
683 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
684 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
685 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
686 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
687 * @param [in] func The constraint function.
688 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
689 * @return The new constraint.
691 static Constraint New( Property::Index target,
692 Property::Type targetType,
693 ConstraintSource source1,
694 ConstraintSource source2,
695 ConstraintSource source3,
696 ConstraintSource source4,
698 AnyFunction interpolator );
701 * @brief Construct a new constraint which targets a property.
703 * @param [in] target The index of the property to constrain.
704 * @param [in] targetType The type of the constrained property.
705 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
706 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
707 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
708 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
709 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
710 * @param [in] func The constraint function.
711 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
712 * @return The new constraint.
714 static Constraint New( Property::Index target,
715 Property::Type targetType,
716 ConstraintSource source1,
717 ConstraintSource source2,
718 ConstraintSource source3,
719 ConstraintSource source4,
720 ConstraintSource source5,
722 AnyFunction interpolator );
725 * @brief Construct a new constraint which targets a property.
727 * @param [in] target The index of the property to constrain.
728 * @param [in] targetType The type of the constrained property.
729 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
730 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
731 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
732 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
733 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
734 * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func.
735 * @param [in] func The constraint function.
736 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
737 * @return The new constraint.
739 static Constraint New( Property::Index target,
740 Property::Type targetType,
741 ConstraintSource source1,
742 ConstraintSource source2,
743 ConstraintSource source3,
744 ConstraintSource source4,
745 ConstraintSource source5,
746 ConstraintSource source6,
748 AnyFunction interpolator );
753 #endif // __DALI_CONSTRAINT_H__