1 #ifndef __DALI_CONSTRAINT_H__
2 #define __DALI_CONSTRAINT_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 // http://floralicense.org/license/
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.
21 * @addtogroup CAPI_DALI_FRAMEWORK
26 #include <boost/any.hpp>
27 #include <boost/function.hpp>
30 #include <dali/public-api/animation/alpha-functions.h>
31 #include <dali/public-api/animation/constraint-source.h>
32 #include <dali/public-api/animation/interpolator-functions.h>
33 #include <dali/public-api/object/handle.h>
34 #include <dali/public-api/object/property.h>
35 #include <dali/public-api/object/property-input.h>
37 namespace Dali DALI_IMPORT_API
41 namespace Internal DALI_INTERNAL
47 * An abstract base class for Constraints.
48 * This can be used to constrain a property of an actor, after animations have been applied.
49 * Constraints are applied in the following order:
50 * - Constraints are applied to on-stage actors in a depth-first traversal.
51 * - For each actor, the constraints are applied in the same order as the calls to Actor::ApplyConstraint().
52 * - Constraints are not applied to off-stage actors.
54 class DALI_IMPORT_API Constraint : public BaseHandle
58 typedef boost::any AnyFunction;
61 * Constraints can be applied gradually; see SetApplyTime() for more details.
62 * When a constraint is fully-applied the final value may be "baked" i.e. saved permanently.
63 * Alternatively the constrained value may be discarded when the constraint is removed.
67 Bake, ///< When the constraint is fully-applied, the constrained value is saved.
68 Discard ///< When the constraint is removed, the constrained value is discarded.
71 static const AlphaFunction DEFAULT_ALPHA_FUNCTION; // AlphaFunctions::Linear
72 static const RemoveAction DEFAULT_REMOVE_ACTION; // Bake
75 * Create an uninitialized Constraint; this can be initialized with Constraint::New()
76 * Calling member functions with an uninitialized Dali::Object is not allowed.
81 * 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 * Create a constraint which targets a property.
100 * The templated parameter P, is the type of the property to constrain.
101 * @param [in] target The index of the property to constrain.
102 * @param [in] func A function which returns the constrained property value.
103 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
104 * @return The new constraint.
107 static Constraint NewWithInterpolator( Property::Index target,
108 boost::function<P (const P& current)> func,
109 boost::function<P (const P&, const P&, float)> interpolator )
112 PropertyTypes::Get<P>(),
118 * Create a constraint which targets a property.
119 * The templated parameter P, is the type of the property to constrain.
120 * Animation will be performed using the default interpolator.
121 * @param [in] target The index of the property to constrain.
122 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
123 * @param [in] func A function which returns the constrained property value.
124 * @return The new constraint.
127 static Constraint New( Property::Index target,
128 ConstraintSource source1,
129 boost::function<P (const P& current, const PropertyInput& input1)> func )
132 PropertyTypes::Get<P>(),
135 GetDefaultInterpolator( PropertyTypes::Get<P>() ) );
139 * Create a constraint which targets a property.
140 * The templated parameter P, is the type of the property to constrain.
141 * @param [in] target The index of the property to constrain.
142 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
143 * @param [in] func A function which returns the constrained property value.
144 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
145 * @return The new constraint.
148 static Constraint NewWithInterpolator( Property::Index target,
149 ConstraintSource source1,
150 boost::function<P (const P& current, const PropertyInput& input1)> func,
151 boost::function<P (const P&, const P&, float)> interpolator )
154 PropertyTypes::Get<P>(),
161 * Create a constraint which targets a property.
162 * The templated parameter P, is the type of the property to constrain.
163 * Animation will be performed using the default interpolator.
164 * @param [in] target The index of the property to constrain.
165 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
166 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
167 * @param [in] func A function which returns the constrained property value.
168 * @return The new constraint.
171 static Constraint New( Property::Index target,
172 ConstraintSource source1,
173 ConstraintSource source2,
174 boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2)> func )
177 PropertyTypes::Get<P>(),
181 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
185 * Create a constraint which targets a property.
186 * The templated parameter P, is the type of the property to constrain.
187 * @param [in] target The index of the property to constrain.
188 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
189 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
190 * @param [in] func A function which returns the constrained property value.
191 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
192 * @return The new constraint.
195 static Constraint NewWithInterpolator( Property::Index target,
196 ConstraintSource source1,
197 ConstraintSource source2,
198 boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2)> func,
199 boost::function<P (const P&, const P&, float)> interpolator )
202 PropertyTypes::Get<P>(),
210 * Create a constraint which targets a property.
211 * The templated parameter P, is the type of the property to constrain.
212 * Animation will be performed using the default interpolator.
213 * @param [in] target The index of the property to constrain.
214 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
215 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
216 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
217 * @param [in] func A function which returns the constrained property value.
218 * @return The new constraint.
221 static Constraint New( Property::Index target,
222 ConstraintSource source1,
223 ConstraintSource source2,
224 ConstraintSource source3,
225 boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2, const PropertyInput& input3)> func )
228 PropertyTypes::Get<P>(),
233 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
237 * Create a constraint which targets a property.
238 * The templated parameter P, is the type of the property to constrain.
239 * @param [in] target The index of the property to constrain.
240 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
241 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
242 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
243 * @param [in] func A function which returns the constrained property value.
244 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
245 * @return The new constraint.
248 static Constraint NewWithInterpolator( Property::Index target,
249 ConstraintSource source1,
250 ConstraintSource source2,
251 ConstraintSource source3,
252 boost::function<P (const P& current, const PropertyInput& input1, const PropertyInput& input2, const PropertyInput& input3)> func,
253 boost::function<P (const P&, const P&, float)> interpolator )
256 PropertyTypes::Get<P>(),
265 * Create a constraint which targets a property.
266 * The templated parameter P, is the type of the property to constrain.
267 * Animation will be performed using the default interpolator.
268 * @param [in] target The index of the property to constrain.
269 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
270 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
271 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
272 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
273 * @param [in] func A function which returns the constrained property value.
274 * @return The new constraint.
277 static Constraint New( Property::Index target,
278 ConstraintSource source1,
279 ConstraintSource source2,
280 ConstraintSource source3,
281 ConstraintSource source4,
282 boost::function<P (const P& current,
283 const PropertyInput& input1,
284 const PropertyInput& input2,
285 const PropertyInput& input3,
286 const PropertyInput& input4)> func )
289 PropertyTypes::Get<P>(),
295 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
299 * Create a constraint which targets a property.
300 * The templated parameter P, is the type of the property to constrain.
301 * @param [in] target The index of the property to constrain.
302 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
303 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
304 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
305 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
306 * @param [in] func A function which returns the constrained property value.
307 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
308 * @return The new constraint.
311 static Constraint NewWithInterpolator( Property::Index target,
312 ConstraintSource source1,
313 ConstraintSource source2,
314 ConstraintSource source3,
315 ConstraintSource source4,
316 boost::function<P (const P& current,
317 const PropertyInput& input1,
318 const PropertyInput& input2,
319 const PropertyInput& input3,
320 const PropertyInput& input4)> func,
321 boost::function<P (const P&, const P&, float)> interpolator )
324 PropertyTypes::Get<P>(),
334 * Create a constraint which targets a property.
335 * The templated parameter P, is the type of the property to constrain.
336 * Animation will be performed using the default interpolator.
337 * @param [in] target The index of the property to constrain.
338 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
339 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
340 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
341 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
342 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
343 * @param [in] func A function which returns the constrained property value.
344 * @return The new constraint.
347 static Constraint New( Property::Index target,
348 ConstraintSource source1,
349 ConstraintSource source2,
350 ConstraintSource source3,
351 ConstraintSource source4,
352 ConstraintSource source5,
353 boost::function<P (const P& current,
354 const PropertyInput& input1,
355 const PropertyInput& input2,
356 const PropertyInput& input3,
357 const PropertyInput& input4,
358 const PropertyInput& input5)> func )
361 PropertyTypes::Get<P>(),
368 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
372 * Create a constraint which targets a property.
373 * The templated parameter P, is the type of the property to constrain.
374 * @param [in] target The index of the property to constrain.
375 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
376 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
377 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
378 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
379 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
380 * @param [in] func A function which returns the constrained property value.
381 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
382 * @return The new constraint.
385 static Constraint NewWithInterpolator( Property::Index target,
386 ConstraintSource source1,
387 ConstraintSource source2,
388 ConstraintSource source3,
389 ConstraintSource source4,
390 ConstraintSource source5,
391 boost::function<P (const P& current,
392 const PropertyInput& input1,
393 const PropertyInput& input2,
394 const PropertyInput& input3,
395 const PropertyInput& input4,
396 const PropertyInput& input5)> func,
397 boost::function<P (const P&, const P&, float)> interpolator )
400 PropertyTypes::Get<P>(),
411 * Create a constraint which targets a property.
412 * The templated parameter P, is the type of the property to constrain.
413 * Animation will be performed using the default interpolator.
414 * @param [in] target The index of the property to constrain.
415 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
416 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
417 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
418 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
419 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
420 * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func.
421 * @param [in] func A function which returns the constrained property value.
422 * @return The new constraint.
425 static Constraint New( Property::Index target,
426 ConstraintSource source1,
427 ConstraintSource source2,
428 ConstraintSource source3,
429 ConstraintSource source4,
430 ConstraintSource source5,
431 ConstraintSource source6,
432 boost::function<P (const P& current,
433 const PropertyInput& input1,
434 const PropertyInput& input2,
435 const PropertyInput& input3,
436 const PropertyInput& input4,
437 const PropertyInput& input5,
438 const PropertyInput& input6)> func )
441 PropertyTypes::Get<P>(),
449 GetDefaultInterpolator(PropertyTypes::Get<P>()) );
453 * Create a constraint which targets a property.
454 * The templated parameter P, is the type of the property to constrain.
455 * @param [in] target The index of the property to constrain.
456 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
457 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
458 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
459 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
460 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
461 * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func.
462 * @param [in] func A function which returns the constrained property value.
463 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
464 * @return The new constraint.
467 static Constraint NewWithInterpolator( Property::Index target,
468 ConstraintSource source1,
469 ConstraintSource source2,
470 ConstraintSource source3,
471 ConstraintSource source4,
472 ConstraintSource source5,
473 ConstraintSource source6,
474 boost::function<P (const P& current,
475 const PropertyInput& input1,
476 const PropertyInput& input2,
477 const PropertyInput& input3,
478 const PropertyInput& input4,
479 const PropertyInput& input5,
480 const PropertyInput& input6)> func,
481 boost::function<P (const P&, const P&, float)> interpolator )
484 PropertyTypes::Get<P>(),
496 * Downcast an Object handle to Constraint handle. If handle points to a Constraint object the
497 * downcast produces valid handle. If not the returned handle is left uninitialized.
498 * @param[in] handle to An object
499 * @return handle to a Constraint object or an uninitialized handle
501 static Constraint DownCast( BaseHandle handle );
506 virtual ~Constraint();
509 * @copydoc Dali::BaseHandle::operator=
511 using BaseHandle::operator=;
514 * Set the time taken for the constraint to be fully applied.
515 * The default is zero, meaning that the constraint is applied immediately.
516 * @param [in] timePeriod The constraint will be applied during this time period.
518 void SetApplyTime( TimePeriod timePeriod );
521 * Retrieve the time taken for the constraint to be fully applied.
522 * @return The apply time.
524 TimePeriod GetApplyTime() const;
527 * Set the time taken for the constraint to be fully removed.
528 * The default is zero, meaning that the constraint is removed immediately.
529 * @param [in] timePeriod The constraint will be removed during this time period.
531 void SetRemoveTime( TimePeriod timePeriod );
534 * Retrieve the time taken for the constraint to be fully removed.
535 * @return The remove time.
537 TimePeriod GetRemoveTime() const;
540 * Set the alpha function for a constraint; the default is AlphaFunctions::Linear.
541 * @param [in] func The alpha function to use when applying/removing the constraint.
543 void SetAlphaFunction( AlphaFunction func );
546 * Retrieve the alpha function of a constraint.
547 * @return The function.
549 AlphaFunction GetAlphaFunction();
552 * Set whether the constraint will "bake" a value when fully-applied.
553 * Otherwise the constrained value will be discarded, when the constraint is removed.
554 * The default value is Constraint::Bake.
555 * @param[in] action The remove-action.
557 void SetRemoveAction( RemoveAction action );
560 * Query whether the constraint will "bake" a value when fully-applied.
561 * Otherwise the constrained value will be discarded, when the constraint is removed.
562 * @return The apply-action.
564 RemoveAction GetRemoveAction() const;
566 public: // Not intended for use by Application developers
569 * This constructor is used by Dali New() methods
570 * @param [in] constraint A pointer to a newly allocated Dali resource
572 explicit DALI_INTERNAL Constraint( Internal::Constraint* constraint );
574 private: // Not intended for use by Application developers
577 * Construct a new constraint which targets a property.
578 * @param [in] target The index of the property to constrain.
579 * @param [in] targetType The type of the constrained property.
580 * @param [in] func The constraint function.
581 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
583 static Constraint New( Property::Index target,
584 Property::Type targetType,
586 AnyFunction interpolator );
589 * Construct a new constraint which targets a property.
590 * @param [in] target The index of the property to constrain.
591 * @param [in] targetType The type of the constrained property.
592 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
593 * @param [in] func The constraint function.
594 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
596 static Constraint New( Property::Index target,
597 Property::Type targetType,
598 ConstraintSource source1,
600 AnyFunction interpolator );
603 * Construct a new constraint which targets a property.
604 * @param [in] target The index of the property to constrain.
605 * @param [in] targetType The type of the constrained property.
606 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
607 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
608 * @param [in] func The constraint function.
609 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
611 static Constraint New( Property::Index target,
612 Property::Type targetType,
613 ConstraintSource source1,
614 ConstraintSource source2,
616 AnyFunction interpolator );
619 * Construct a new constraint which targets a property.
620 * @param [in] target The index of the property to constrain.
621 * @param [in] targetType The type of the constrained property.
622 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
623 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
624 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
625 * @param [in] func The constraint function.
626 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
628 static Constraint New( Property::Index target,
629 Property::Type targetType,
630 ConstraintSource source1,
631 ConstraintSource source2,
632 ConstraintSource source3,
634 AnyFunction interpolator );
637 * Construct a new constraint which targets a property.
638 * @param [in] target The index of the property to constrain.
639 * @param [in] targetType The type of the constrained property.
640 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
641 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
642 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
643 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
644 * @param [in] func The constraint function.
645 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
647 static Constraint New( Property::Index target,
648 Property::Type targetType,
649 ConstraintSource source1,
650 ConstraintSource source2,
651 ConstraintSource source3,
652 ConstraintSource source4,
654 AnyFunction interpolator );
657 * Construct a new constraint which targets a property.
658 * @param [in] target The index of the property to constrain.
659 * @param [in] targetType The type of the constrained property.
660 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
661 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
662 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
663 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
664 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
665 * @param [in] func The constraint function.
666 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
668 static Constraint New( Property::Index target,
669 Property::Type targetType,
670 ConstraintSource source1,
671 ConstraintSource source2,
672 ConstraintSource source3,
673 ConstraintSource source4,
674 ConstraintSource source5,
676 AnyFunction interpolator );
679 * Construct a new constraint which targets a property.
680 * @param [in] target The index of the property to constrain.
681 * @param [in] targetType The type of the constrained property.
682 * @param [in] source1 The source of a property; the current value will be passed as the 2nd parameter of func.
683 * @param [in] source2 The source of a property; the current value will be passed as the 3rd parameter of func.
684 * @param [in] source3 The source of a property; the current value will be passed as the 4th parameter of func.
685 * @param [in] source4 The source of a property; the current value will be passed as the 5th parameter of func.
686 * @param [in] source5 The source of a property; the current value will be passed as the 6th parameter of func.
687 * @param [in] source6 The source of a property; the current value will be passed as the 7th parameter of func.
688 * @param [in] func The constraint function.
689 * @param [in] interpolator A function used to interpolate between the start value, and the value returned by func.
691 static Constraint New( Property::Index target,
692 Property::Type targetType,
693 ConstraintSource source1,
694 ConstraintSource source2,
695 ConstraintSource source3,
696 ConstraintSource source4,
697 ConstraintSource source5,
698 ConstraintSource source6,
700 AnyFunction interpolator );
708 #endif // __DALI_CONSTRAINT_H__