src/quick/util/qquickanimation.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtQml module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qquickanimation_p.h"
  43 #include "qquickanimation_p_p.h"
  44
  45 #include <private/qquickstatechangescript_p.h>
  46 #include <private/qqmlcontext_p.h>
  47
  48 #include <qqmlpropertyvaluesource.h>
  49 #include <qqml.h>
  50 #include <qqmlinfo.h>
  51 #include <qqmlexpression.h>
  52 #include <private/qqmlstringconverters_p.h>
  53 #include <private/qqmlglobal_p.h>
  54 #include <private/qqmlmetatype_p.h>
  55 #include <private/qqmlvaluetype_p.h>
  56 #include <private/qqmlproperty_p.h>
  57 #include <private/qqmlengine_p.h>
  58
  59 #include <qvariant.h>
  60 #include <qcolor.h>
  61 #include <qfile.h>
  62 #include "private/qparallelanimationgroupjob_p.h"
  63 #include "private/qsequentialanimationgroupjob_p.h"
  64 #include <QtCore/qset.h>
  65 #include <QtCore/qrect.h>
  66 #include <QtCore/qpoint.h>
  67 #include <QtCore/qsize.h>
  68 #include <QtCore/qmath.h>
  69
  70 QT_BEGIN_NAMESPACE
  71
  72 /*!
  73     \qmlclass Animation QQuickAbstractAnimation
  74     \inqmlmodule QtQuick 2
  75     \ingroup qml-animation-transition
  76     \brief The Animation element is the base of all QML animations.
  77
  78     The Animation element cannot be used directly in a QML file.  It exists
  79     to provide a set of common properties and methods, available across all the
  80     other animation types that inherit from it.  Attempting to use the Animation
  81     element directly will result in an error.
  82 */
  83
  84 QQuickAbstractAnimation::QQuickAbstractAnimation(QObject *parent)
  85 : QObject(*(new QQuickAbstractAnimationPrivate), parent)
  86 {
  87 }
  88
  89 QQuickAbstractAnimation::~QQuickAbstractAnimation()
  90 {
  91     Q_D(QQuickAbstractAnimation);
  92     delete d->animationInstance;
  93 }
  94
  95 QQuickAbstractAnimation::QQuickAbstractAnimation(QQuickAbstractAnimationPrivate &dd, QObject *parent)
  96 : QObject(dd, parent)
  97 {
  98 }
  99
 100 QAbstractAnimationJob* QQuickAbstractAnimation::qtAnimation()
 101 {
 102     Q_D(QQuickAbstractAnimation);
 103     return d->animationInstance;
 104 }
 105
 106 /*!
 107     \qmlproperty bool QtQuick2::Animation::running
 108     This property holds whether the animation is currently running.
 109
 110     The \c running property can be set to declaratively control whether or not
 111     an animation is running.  The following example will animate a rectangle
 112     whenever the \l MouseArea is pressed.
 113
 114     \code
 115     Rectangle {
 116         width: 100; height: 100
 117         NumberAnimation on x {
 118             running: myMouse.pressed
 119             from: 0; to: 100
 120         }
 121         MouseArea { id: myMouse }
 122     }
 123     \endcode
 124
 125     Likewise, the \c running property can be read to determine if the animation
 126     is running.  In the following example the text element will indicate whether
 127     or not the animation is running.
 128
 129     \code
 130     NumberAnimation { id: myAnimation }
 131     Text { text: myAnimation.running ? "Animation is running" : "Animation is not running" }
 132     \endcode
 133
 134     Animations can also be started and stopped imperatively from JavaScript
 135     using the \c start() and \c stop() methods.
 136
 137     By default, animations are not running. Though, when the animations are assigned to properties,
 138     as property value sources using the \e on syntax, they are set to running by default.
 139 */
 140 bool QQuickAbstractAnimation::isRunning() const
 141 {
 142     Q_D(const QQuickAbstractAnimation);
 143     return d->running;
 144 }
 145
 146 // the behavior calls this function
 147 void QQuickAbstractAnimation::notifyRunningChanged(bool running)
 148 {
 149     Q_D(QQuickAbstractAnimation);
 150     if (d->disableUserControl && d->running != running) {
 151         d->running = running;
 152         emit runningChanged(running);
 153     }
 154 }
 155
 156 //commence is called to start an animation when it is used as a
 157 //simple animation, and not as part of a transition
 158 void QQuickAbstractAnimationPrivate::commence()
 159 {
 160     Q_Q(QQuickAbstractAnimation);
 161
 162     QQuickStateActions actions;
 163     QQmlProperties properties;
 164
 165     QAbstractAnimationJob *oldInstance = animationInstance;
 166     animationInstance = q->transition(actions, properties, QQuickAbstractAnimation::Forward);
 167     if (oldInstance != animationInstance) {
 168         animationInstance->addAnimationChangeListener(this, QAbstractAnimationJob::Completion);
 169         if (oldInstance)
 170             delete oldInstance;
 171     }
 172     animationInstance->start();
 173     if (animationInstance->isStopped()) {
 174         running = false;
 175         emit q->completed();
 176     }
 177 }
 178
 179 QQmlProperty QQuickAbstractAnimationPrivate::createProperty(QObject *obj, const QString &str, QObject *infoObj)
 180 {
 181     QQmlProperty prop(obj, str, qmlContext(infoObj));
 182     if (!prop.isValid()) {
 183         qmlInfo(infoObj) << QQuickAbstractAnimation::tr("Cannot animate non-existent property \"%1\"").arg(str);
 184         return QQmlProperty();
 185     } else if (!prop.isWritable()) {
 186         qmlInfo(infoObj) << QQuickAbstractAnimation::tr("Cannot animate read-only property \"%1\"").arg(str);
 187         return QQmlProperty();
 188     }
 189     return prop;
 190 }
 191
 192 void QQuickAbstractAnimation::setRunning(bool r)
 193 {
 194     Q_D(QQuickAbstractAnimation);
 195     if (!d->componentComplete) {
 196         d->running = r;
 197         if (r == false)
 198             d->avoidPropertyValueSourceStart = true;
 199         else if (!d->registered) {
 200             d->registered = true;
 201             QQmlEnginePrivate *engPriv = QQmlEnginePrivate::get(qmlEngine(this));
 202             static int finalizedIdx = -1;
 203             if (finalizedIdx < 0)
 204                 finalizedIdx = metaObject()->indexOfSlot("componentFinalized()");
 205             engPriv->registerFinalizeCallback(this, finalizedIdx);
 206         }
 207         return;
 208     }
 209
 210     if (d->running == r)
 211         return;
 212
 213     if (d->group || d->disableUserControl) {
 214         qmlInfo(this) << "setRunning() cannot be used on non-root animation nodes.";
 215         return;
 216     }
 217
 218     d->running = r;
 219     if (d->running) {
 220         bool supressStart = false;
 221         if (d->alwaysRunToEnd && d->loopCount != 1
 222             && d->animationInstance && d->animationInstance->isRunning()) {
 223             //we've restarted before the final loop finished; restore proper loop count
 224             if (d->loopCount == -1)
 225                 d->animationInstance->setLoopCount(d->loopCount);
 226             else
 227                 d->animationInstance->setLoopCount(d->animationInstance->currentLoop() + d->loopCount);
 228             supressStart = true;    //we want the animation to continue, rather than restart
 229         }
 230         if (!supressStart)
 231             d->commence();
 232         emit started();
 233     } else {
 234         if (d->paused) {
 235             d->paused = false; //reset paused state to false when stopped
 236             emit pausedChanged(d->paused);
 237         }
 238
 239         if (d->animationInstance) {
 240             if (d->alwaysRunToEnd) {
 241                 if (d->loopCount != 1)
 242                     d->animationInstance->setLoopCount(d->animationInstance->currentLoop()+1);    //finish the current loop
 243             } else {
 244                 d->animationInstance->stop();
 245             }
 246         }
 247         emit completed();
 248     }
 249
 250     emit runningChanged(d->running);
 251 }
 252
 253 /*!
 254     \qmlproperty bool QtQuick2::Animation::paused
 255     This property holds whether the animation is currently paused.
 256
 257     The \c paused property can be set to declaratively control whether or not
 258     an animation is paused.
 259
 260     Animations can also be paused and resumed imperatively from JavaScript
 261     using the \c pause() and \c resume() methods.
 262
 263     By default, animations are not paused.
 264 */
 265 bool QQuickAbstractAnimation::isPaused() const
 266 {
 267     Q_D(const QQuickAbstractAnimation);
 268     Q_ASSERT((d->paused && d->running) || !d->paused);
 269     return d->paused;
 270 }
 271
 272 void QQuickAbstractAnimation::setPaused(bool p)
 273 {
 274     Q_D(QQuickAbstractAnimation);
 275     if (d->paused == p)
 276         return;
 277
 278     if (!d->running) {
 279         qmlInfo(this) << "setPaused() cannot be used when animation isn't running.";
 280         return;
 281     }
 282
 283     if (d->group || d->disableUserControl) {
 284         qmlInfo(this) << "setPaused() cannot be used on non-root animation nodes.";
 285         return;
 286     }
 287
 288     d->paused = p;
 289
 290     if (!d->componentComplete || !d->animationInstance)
 291         return;
 292
 293     if (d->paused)
 294         d->animationInstance->pause();
 295     else
 296         d->animationInstance->resume();
 297
 298     emit pausedChanged(d->paused);
 299 }
 300
 301 void QQuickAbstractAnimation::classBegin()
 302 {
 303     Q_D(QQuickAbstractAnimation);
 304     d->componentComplete = false;
 305 }
 306
 307 void QQuickAbstractAnimation::componentComplete()
 308 {
 309     Q_D(QQuickAbstractAnimation);
 310     d->componentComplete = true;
 311 }
 312
 313 void QQuickAbstractAnimation::componentFinalized()
 314 {
 315     Q_D(QQuickAbstractAnimation);
 316     if (d->running) {
 317         d->running = false;
 318         setRunning(true);
 319     }
 320     if (d->paused) {
 321         d->paused = false;
 322         setPaused(true);
 323     }
 324 }
 325
 326 /*!
 327     \qmlproperty bool QtQuick2::Animation::alwaysRunToEnd
 328     This property holds whether the animation should run to completion when it is stopped.
 329
 330     If this true the animation will complete its current iteration when it
 331     is stopped - either by setting the \c running property to false, or by
 332     calling the \c stop() method.  The \c complete() method is not effected
 333     by this value.
 334
 335     This behavior is most useful when the \c repeat property is set, as the
 336     animation will finish playing normally but not restart.
 337
 338     By default, the alwaysRunToEnd property is not set.
 339
 340     \note alwaysRunToEnd has no effect on animations in a Transition.
 341 */
 342 bool QQuickAbstractAnimation::alwaysRunToEnd() const
 343 {
 344     Q_D(const QQuickAbstractAnimation);
 345     return d->alwaysRunToEnd;
 346 }
 347
 348 void QQuickAbstractAnimation::setAlwaysRunToEnd(bool f)
 349 {
 350     Q_D(QQuickAbstractAnimation);
 351     if (d->alwaysRunToEnd == f)
 352         return;
 353
 354     d->alwaysRunToEnd = f;
 355     emit alwaysRunToEndChanged(f);
 356 }
 357
 358 /*!
 359     \qmlproperty int QtQuick2::Animation::loops
 360     This property holds the number of times the animation should play.
 361
 362     By default, \c loops is 1: the animation will play through once and then stop.
 363
 364     If set to Animation.Infinite, the animation will continuously repeat until it is explicitly
 365     stopped - either by setting the \c running property to false, or by calling
 366     the \c stop() method.
 367
 368     In the following example, the rectangle will spin indefinitely.
 369
 370     \code
 371     Rectangle {
 372         width: 100; height: 100; color: "green"
 373         RotationAnimation on rotation {
 374             loops: Animation.Infinite
 375             from: 0
 376             to: 360
 377         }
 378     }
 379     \endcode
 380 */
 381 int QQuickAbstractAnimation::loops() const
 382 {
 383     Q_D(const QQuickAbstractAnimation);
 384     return d->loopCount;
 385 }
 386
 387 void QQuickAbstractAnimation::setLoops(int loops)
 388 {
 389     Q_D(QQuickAbstractAnimation);
 390     if (loops < 0)
 391         loops = -1;
 392
 393     if (loops == d->loopCount)
 394         return;
 395
 396     d->loopCount = loops;
 397     emit loopCountChanged(loops);
 398 }
 399
 400 int QQuickAbstractAnimation::duration() const
 401 {
 402     Q_D(const QQuickAbstractAnimation);
 403     return d->animationInstance ? d->animationInstance->duration() : 0;
 404 }
 405
 406 int QQuickAbstractAnimation::currentTime()
 407 {
 408     Q_D(QQuickAbstractAnimation);
 409     return d->animationInstance ? d->animationInstance->currentLoopTime() : 0;
 410 }
 411
 412 void QQuickAbstractAnimation::setCurrentTime(int time)
 413 {
 414     Q_D(QQuickAbstractAnimation);
 415     if (d->animationInstance)
 416         d->animationInstance->setCurrentTime(time);
 417     //TODO save value for start?
 418 }
 419
 420 QQuickAnimationGroup *QQuickAbstractAnimation::group() const
 421 {
 422     Q_D(const QQuickAbstractAnimation);
 423     return d->group;
 424 }
 425
 426 void QQuickAbstractAnimation::setGroup(QQuickAnimationGroup *g)
 427 {
 428     Q_D(QQuickAbstractAnimation);
 429     if (d->group == g)
 430         return;
 431     if (d->group)
 432         static_cast<QQuickAnimationGroupPrivate *>(d->group->d_func())->animations.removeAll(this);
 433
 434     d->group = g;
 435
 436     if (d->group && !static_cast<QQuickAnimationGroupPrivate *>(d->group->d_func())->animations.contains(this))
 437         static_cast<QQuickAnimationGroupPrivate *>(d->group->d_func())->animations.append(this);
 438
 439     //if (g) //if removed from a group, then the group should no longer be the parent
 440         setParent(g);
 441 }
 442
 443 /*!
 444     \qmlmethod QtQuick2::Animation::start()
 445     \brief Starts the animation.
 446
 447     If the animation is already running, calling this method has no effect.  The
 448     \c running property will be true following a call to \c start().
 449 */
 450 void QQuickAbstractAnimation::start()
 451 {
 452     setRunning(true);
 453 }
 454
 455 /*!
 456     \qmlmethod QtQuick2::Animation::pause()
 457     \brief Pauses the animation.
 458
 459     If the animation is already paused or not \c running, calling this method has no effect.
 460     The \c paused property will be true following a call to \c pause().
 461 */
 462 void QQuickAbstractAnimation::pause()
 463 {
 464     setPaused(true);
 465 }
 466
 467 /*!
 468     \qmlmethod QtQuick2::Animation::resume()
 469     \brief Resumes a paused animation.
 470
 471     If the animation is not paused or not \c running, calling this method has no effect.
 472     The \c paused property will be false following a call to \c resume().
 473 */
 474 void QQuickAbstractAnimation::resume()
 475 {
 476     setPaused(false);
 477 }
 478
 479 /*!
 480     \qmlmethod QtQuick2::Animation::stop()
 481     \brief Stops the animation.
 482
 483     If the animation is not running, calling this method has no effect.  Both the
 484     \c running and \c paused properties will be false following a call to \c stop().
 485
 486     Normally \c stop() stops the animation immediately, and the animation has
 487     no further influence on property values.  In this example animation
 488     \code
 489     Rectangle {
 490         NumberAnimation on x { from: 0; to: 100; duration: 500 }
 491     }
 492     \endcode
 493     was stopped at time 250ms, the \c x property will have a value of 50.
 494
 495     However, if the \c alwaysRunToEnd property is set, the animation will
 496     continue running until it completes and then stop.  The \c running property
 497     will still become false immediately.
 498 */
 499 void QQuickAbstractAnimation::stop()
 500 {
 501     setRunning(false);
 502 }
 503
 504 /*!
 505     \qmlmethod QtQuick2::Animation::restart()
 506     \brief Restarts the animation.
 507
 508     This is a convenience method, and is equivalent to calling \c stop() and
 509     then \c start().
 510 */
 511 void QQuickAbstractAnimation::restart()
 512 {
 513     stop();
 514     start();
 515 }
 516
 517 /*!
 518     \qmlmethod QtQuick2::Animation::complete()
 519     \brief Stops the animation, jumping to the final property values.
 520
 521     If the animation is not running, calling this method has no effect.  The
 522     \c running property will be false following a call to \c complete().
 523
 524     Unlike \c stop(), \c complete() immediately fast-forwards the animation to
 525     its end.  In the following example,
 526     \code
 527     Rectangle {
 528         NumberAnimation on x { from: 0; to: 100; duration: 500 }
 529     }
 530     \endcode
 531     calling \c stop() at time 250ms will result in the \c x property having
 532     a value of 50, while calling \c complete() will set the \c x property to
 533     100, exactly as though the animation had played the whole way through.
 534 */
 535 void QQuickAbstractAnimation::complete()
 536 {
 537     Q_D(QQuickAbstractAnimation);
 538     if (isRunning() && d->animationInstance) {
 539          d->animationInstance->setCurrentTime(d->animationInstance->duration());
 540     }
 541 }
 542
 543 void QQuickAbstractAnimation::setTarget(const QQmlProperty &p)
 544 {
 545     Q_D(QQuickAbstractAnimation);
 546     d->defaultProperty = p;
 547
 548     if (!d->avoidPropertyValueSourceStart)
 549         setRunning(true);
 550 }
 551
 552 /*
 553     we rely on setTarget only being called when used as a value source
 554     so this function allows us to do the same thing as setTarget without
 555     that assumption
 556 */
 557 void QQuickAbstractAnimation::setDefaultTarget(const QQmlProperty &p)
 558 {
 559     Q_D(QQuickAbstractAnimation);
 560     d->defaultProperty = p;
 561 }
 562
 563 /*
 564     don't allow start/stop/pause/resume to be manually invoked,
 565     because something else (like a Behavior) already has control
 566     over the animation.
 567 */
 568 void QQuickAbstractAnimation::setDisableUserControl()
 569 {
 570     Q_D(QQuickAbstractAnimation);
 571     d->disableUserControl = true;
 572 }
 573
 574 void QQuickAbstractAnimation::setEnableUserControl()
 575 {
 576     Q_D(QQuickAbstractAnimation);
 577     d->disableUserControl = false;
 578
 579 }
 580
 581 bool QQuickAbstractAnimation::userControlDisabled() const
 582 {
 583     Q_D(const QQuickAbstractAnimation);
 584     return d->disableUserControl;
 585 }
 586
 587 QAbstractAnimationJob* QQuickAbstractAnimation::initInstance(QAbstractAnimationJob *animation)
 588 {
 589     Q_D(QQuickAbstractAnimation);
 590     animation->setLoopCount(d->loopCount);
 591     return animation;
 592 }
 593
 594 QAbstractAnimationJob* QQuickAbstractAnimation::transition(QQuickStateActions &actions,
 595                                       QQmlProperties &modified,
 596                                       TransitionDirection direction,
 597                                       QObject *defaultTarget)
 598 {
 599     Q_UNUSED(actions);
 600     Q_UNUSED(modified);
 601     Q_UNUSED(direction);
 602     Q_UNUSED(defaultTarget);
 603     return 0;
 604 }
 605
 606 void QQuickAbstractAnimationPrivate::animationFinished(QAbstractAnimationJob*)
 607 {
 608     Q_Q(QQuickAbstractAnimation);
 609     q->setRunning(false);
 610     if (alwaysRunToEnd && loopCount != 1) {
 611         //restore the proper loopCount for the next run
 612         animationInstance->setLoopCount(loopCount);
 613     }
 614 }
 615
 616 /*!
 617     \qmlclass PauseAnimation QQuickPauseAnimation
 618     \inqmlmodule QtQuick 2
 619     \ingroup qml-animation-transition
 620     \inherits Animation
 621     \brief The PauseAnimation element provides a pause for an animation.
 622
 623     When used in a SequentialAnimation, PauseAnimation is a step when
 624     nothing happens, for a specified duration.
 625
 626     A 500ms animation sequence, with a 100ms pause between two animations:
 627     \code
 628     SequentialAnimation {
 629         NumberAnimation { ... duration: 200 }
 630         PauseAnimation { duration: 100 }
 631         NumberAnimation { ... duration: 200 }
 632     }
 633     \endcode
 634
 635     \sa {QML Animation and Transitions}, {qml/animation/basics}{Animation basics example}
 636 */
 637 QQuickPauseAnimation::QQuickPauseAnimation(QObject *parent)
 638 : QQuickAbstractAnimation(*(new QQuickPauseAnimationPrivate), parent)
 639 {
 640 }
 641
 642 QQuickPauseAnimation::~QQuickPauseAnimation()
 643 {
 644 }
 645
 646 /*!
 647     \qmlproperty int QtQuick2::PauseAnimation::duration
 648     This property holds the duration of the pause in milliseconds
 649
 650     The default value is 250.
 651 */
 652 int QQuickPauseAnimation::duration() const
 653 {
 654     Q_D(const QQuickPauseAnimation);
 655     return d->duration;
 656 }
 657
 658 void QQuickPauseAnimation::setDuration(int duration)
 659 {
 660     if (duration < 0) {
 661         qmlInfo(this) << tr("Cannot set a duration of < 0");
 662         return;
 663     }
 664
 665     Q_D(QQuickPauseAnimation);
 666     if (d->duration == duration)
 667         return;
 668     d->duration = duration;
 669     emit durationChanged(duration);
 670 }
 671
 672 QAbstractAnimationJob* QQuickPauseAnimation::transition(QQuickStateActions &actions,
 673                                     QQmlProperties &modified,
 674                                     TransitionDirection direction,
 675                                     QObject *defaultTarget)
 676 {
 677     Q_D(QQuickPauseAnimation);
 678     Q_UNUSED(actions);
 679     Q_UNUSED(modified);
 680     Q_UNUSED(direction);
 681     Q_UNUSED(defaultTarget);
 682
 683     return initInstance(new QPauseAnimationJob(d->duration));
 684 }
 685
 686 /*!
 687     \qmlclass ColorAnimation QQuickColorAnimation
 688     \inqmlmodule QtQuick 2
 689   \ingroup qml-animation-transition
 690     \inherits PropertyAnimation
 691     \brief The ColorAnimation element animates changes in color values.
 692
 693     ColorAnimation is a specialized PropertyAnimation that defines an
 694     animation to be applied when a color value changes.
 695
 696     Here is a ColorAnimation applied to the \c color property of a \l Rectangle
 697     as a property value source. It animates the \c color property's value from
 698     its current value to a value of "red", over 1000 milliseconds:
 699
 700     \snippet doc/src/snippets/qml/coloranimation.qml 0
 701
 702     Like any other animation element, a ColorAnimation can be applied in a
 703     number of ways, including transitions, behaviors and property value
 704     sources. The \l {QML Animation and Transitions} documentation shows a
 705     variety of methods for creating animations.
 706
 707     For convenience, when a ColorAnimation is used in a \l Transition, it will
 708     animate any \c color properties that have been modified during the state
 709     change. If a \l{PropertyAnimation::}{property} or
 710     \l{PropertyAnimation::}{properties} are explicitly set for the animation,
 711     then those are used instead.
 712
 713     \sa {QML Animation and Transitions}, {qml/animation/basics}{Animation basics example}
 714 */
 715 QQuickColorAnimation::QQuickColorAnimation(QObject *parent)
 716 : QQuickPropertyAnimation(parent)
 717 {
 718     Q_D(QQuickPropertyAnimation);
 719     d->interpolatorType = QMetaType::QColor;
 720     d->defaultToInterpolatorType = true;
 721     d->interpolator = QVariantAnimationPrivate::getInterpolator(d->interpolatorType);
 722 }
 723
 724 QQuickColorAnimation::~QQuickColorAnimation()
 725 {
 726 }
 727
 728 /*!
 729     \qmlproperty color QtQuick2::ColorAnimation::from
 730     This property holds the color value at which the animation should begin.
 731
 732     For example, the following animation is not applied until a color value
 733     has reached "#c0c0c0":
 734
 735     \qml
 736     Item {
 737         states: [
 738             // States are defined here...
 739         ]
 740
 741         transition: Transition {
 742             ColorAnimation { from: "#c0c0c0"; duration: 2000 }
 743         }
 744     }
 745     \endqml
 746
 747     If the ColorAnimation is defined within a \l Transition or \l Behavior,
 748     this value defaults to the value defined in the starting state of the
 749     \l Transition, or the current value of the property at the moment the
 750     \l Behavior is triggered.
 751
 752     \sa {QML Animation and Transitions}
 753 */
 754 QColor QQuickColorAnimation::from() const
 755 {
 756     Q_D(const QQuickPropertyAnimation);
 757     return d->from.value<QColor>();
 758 }
 759
 760 void QQuickColorAnimation::setFrom(const QColor &f)
 761 {
 762     QQuickPropertyAnimation::setFrom(f);
 763 }
 764
 765 /*!
 766     \qmlproperty color QtQuick2::ColorAnimation::to
 767
 768     This property holds the color value at which the animation should end.
 769
 770     If the ColorAnimation is defined within a \l Transition or \l Behavior,
 771     this value defaults to the value defined in the end state of the
 772     \l Transition, or the value of the property change that triggered the
 773     \l Behavior.
 774
 775     \sa {QML Animation and Transitions}
 776 */
 777 QColor QQuickColorAnimation::to() const
 778 {
 779     Q_D(const QQuickPropertyAnimation);
 780     return d->to.value<QColor>();
 781 }
 782
 783 void QQuickColorAnimation::setTo(const QColor &t)
 784 {
 785     QQuickPropertyAnimation::setTo(t);
 786 }
 787
 788 QActionAnimation::QActionAnimation()
 789     : QAbstractAnimationJob(), animAction(0)
 790 {
 791 }
 792
 793 QActionAnimation::QActionAnimation(QAbstractAnimationAction *action)
 794     : QAbstractAnimationJob(), animAction(action)
 795 {
 796 }
 797
 798 QActionAnimation::~QActionAnimation()
 799 {
 800     delete animAction;
 801 }
 802
 803 int QActionAnimation::duration() const
 804 {
 805     return 0;
 806 }
 807
 808 void QActionAnimation::setAnimAction(QAbstractAnimationAction *action)
 809 {
 810     if (isRunning())
 811         stop();
 812     animAction = action;
 813 }
 814
 815 void QActionAnimation::updateCurrentTime(int)
 816 {
 817 }
 818
 819 void QActionAnimation::updateState(State newState, State oldState)
 820 {
 821     Q_UNUSED(oldState);
 822
 823     if (newState == Running) {
 824         if (animAction) {
 825             animAction->doAction();
 826         }
 827     }
 828 }
 829
 830 /*!
 831     \qmlclass ScriptAction QQuickScriptAction
 832     \inqmlmodule QtQuick 2
 833     \ingroup qml-animation-transition
 834     \inherits Animation
 835     \brief The ScriptAction element allows scripts to be run during an animation.
 836
 837     ScriptAction can be used to run a script at a specific point in an animation.
 838
 839     \qml
 840     SequentialAnimation {
 841         NumberAnimation {
 842             // ...
 843         }
 844         ScriptAction { script: doSomething(); }
 845         NumberAnimation {
 846             // ...
 847         }
 848     }
 849     \endqml
 850
 851     When used as part of a Transition, you can also target a specific
 852     StateChangeScript to run using the \c scriptName property.
 853
 854     \snippet doc/src/snippets/qml/states/statechangescript.qml state and transition
 855
 856     \sa StateChangeScript
 857 */
 858 QQuickScriptAction::QQuickScriptAction(QObject *parent)
 859     :QQuickAbstractAnimation(*(new QQuickScriptActionPrivate), parent)
 860 {
 861 }
 862
 863 QQuickScriptAction::~QQuickScriptAction()
 864 {
 865 }
 866
 867 QQuickScriptActionPrivate::QQuickScriptActionPrivate()
 868     : QQuickAbstractAnimationPrivate(), hasRunScriptScript(false), reversing(false){}
 869
 870 /*!
 871     \qmlproperty script QtQuick2::ScriptAction::script
 872     This property holds the script to run.
 873 */
 874 QQmlScriptString QQuickScriptAction::script() const
 875 {
 876     Q_D(const QQuickScriptAction);
 877     return d->script;
 878 }
 879
 880 void QQuickScriptAction::setScript(const QQmlScriptString &script)
 881 {
 882     Q_D(QQuickScriptAction);
 883     d->script = script;
 884 }
 885
 886 /*!
 887     \qmlproperty string QtQuick2::ScriptAction::scriptName
 888     This property holds the the name of the StateChangeScript to run.
 889
 890     This property is only valid when ScriptAction is used as part of a transition.
 891     If both script and scriptName are set, scriptName will be used.
 892
 893     \note When using scriptName in a reversible transition, the script will only
 894     be run when the transition is being run forwards.
 895 */
 896 QString QQuickScriptAction::stateChangeScriptName() const
 897 {
 898     Q_D(const QQuickScriptAction);
 899     return d->name;
 900 }
 901
 902 void QQuickScriptAction::setStateChangeScriptName(const QString &name)
 903 {
 904     Q_D(QQuickScriptAction);
 905     d->name = name;
 906 }
 907
 908 QAbstractAnimationAction* QQuickScriptActionPrivate::createAction()
 909 {
 910     return new Proxy(this);
 911 }
 912
 913 void QQuickScriptActionPrivate::execute()
 914 {
 915     Q_Q(QQuickScriptAction);
 916     if (hasRunScriptScript && reversing)
 917         return;
 918
 919     QQmlScriptString scriptStr = hasRunScriptScript ? runScriptScript : script;
 920
 921     if (!scriptStr.script().isEmpty()) {
 922         QQmlExpression expr(scriptStr);
 923         expr.evaluate();
 924         if (expr.hasError())
 925             qmlInfo(q) << expr.error();
 926     }
 927 }
 928
 929 QAbstractAnimationJob* QQuickScriptAction::transition(QQuickStateActions &actions,
 930                                     QQmlProperties &modified,
 931                                     TransitionDirection direction,
 932                                     QObject *defaultTarget)
 933 {
 934     Q_D(QQuickScriptAction);
 935     Q_UNUSED(modified);
 936     Q_UNUSED(defaultTarget);
 937
 938     d->hasRunScriptScript = false;
 939     d->reversing = (direction == Backward);
 940     for (int ii = 0; ii < actions.count(); ++ii) {
 941         QQuickAction &action = actions[ii];
 942
 943         if (action.event && action.event->type() == QQuickActionEvent::Script
 944             && static_cast<QQuickStateChangeScript*>(action.event)->name() == d->name) {
 945             d->runScriptScript = static_cast<QQuickStateChangeScript*>(action.event)->script();
 946             d->hasRunScriptScript = true;
 947             action.actionDone = true;
 948             break;  //only match one (names should be unique)
 949         }
 950     }
 951     return initInstance(new QActionAnimation(d->createAction()));
 952 }
 953
 954 /*!
 955     \qmlclass PropertyAction QQuickPropertyAction
 956     \inqmlmodule QtQuick 2
 957     \ingroup qml-animation-transition
 958     \inherits Animation
 959     \brief The PropertyAction element allows immediate property changes during animation.
 960
 961     PropertyAction is used to specify an immediate property change during an
 962     animation. The property change is not animated.
 963
 964     It is useful for setting non-animated property values during an animation.
 965
 966     For example, here is a SequentialAnimation that sets the image's
 967     \l {Image::}{smooth} property to \c true, animates the width of the image,
 968     then sets \l {Image::}{smooth} back to \c false:
 969
 970     \snippet doc/src/snippets/qml/propertyaction.qml standalone
 971
 972     PropertyAction is also useful for setting the exact point at which a property
 973     change should occur during a \l Transition. For example, if PropertyChanges
 974     was used in a \l State to rotate an item around a particular
 975     \l {Item::}{transformOrigin}, it might be implemented like this:
 976
 977     \snippet doc/src/snippets/qml/propertyaction.qml transition
 978
 979     However, with this code, the \c transformOrigin is not set until \e after
 980     the animation, as a \l State is taken to define the values at the \e end of
 981     a transition. The animation would rotate at the default \c transformOrigin,
 982     then jump to \c Item.BottomRight. To fix this, insert a PropertyAction
 983     before the RotationAnimation begins:
 984
 985     \snippet doc/src/snippets/qml/propertyaction-sequential.qml sequential
 986
 987     This immediately sets the \c transformOrigin property to the value defined
 988     in the end state of the \l Transition (i.e. the value defined in the
 989     PropertyAction object) so that the rotation animation begins with the
 990     correct transform origin.
 991
 992     \sa {QML Animation and Transitions}, QtQml
 993 */
 994 QQuickPropertyAction::QQuickPropertyAction(QObject *parent)
 995 : QQuickAbstractAnimation(*(new QQuickPropertyActionPrivate), parent)
 996 {
 997 }
 998
 999 QQuickPropertyAction::~QQuickPropertyAction()
1000 {
1001 }
1002
1003 QObject *QQuickPropertyAction::target() const
1004 {
1005     Q_D(const QQuickPropertyAction);
1006     return d->target;
1007 }
1008
1009 void QQuickPropertyAction::setTargetObject(QObject *o)
1010 {
1011     Q_D(QQuickPropertyAction);
1012     if (d->target == o)
1013         return;
1014     d->target = o;
1015     emit targetChanged();
1016 }
1017
1018 QString QQuickPropertyAction::property() const
1019 {
1020     Q_D(const QQuickPropertyAction);
1021     return d->propertyName;
1022 }
1023
1024 void QQuickPropertyAction::setProperty(const QString &n)
1025 {
1026     Q_D(QQuickPropertyAction);
1027     if (d->propertyName == n)
1028         return;
1029     d->propertyName = n;
1030     emit propertyChanged();
1031 }
1032
1033 /*!
1034     \qmlproperty Object QtQuick2::PropertyAction::target
1035     \qmlproperty list<Object> QtQuick2::PropertyAction::targets
1036     \qmlproperty string QtQuick2::PropertyAction::property
1037     \qmlproperty string QtQuick2::PropertyAction::properties
1038
1039     These properties determine the items and their properties that are
1040     affected by this action.
1041
1042     The details of how these properties are interpreted in different situations
1043     is covered in the \l{PropertyAnimation::properties}{corresponding} PropertyAnimation
1044     documentation.
1045
1046     \sa exclude
1047 */
1048 QString QQuickPropertyAction::properties() const
1049 {
1050     Q_D(const QQuickPropertyAction);
1051     return d->properties;
1052 }
1053
1054 void QQuickPropertyAction::setProperties(const QString &p)
1055 {
1056     Q_D(QQuickPropertyAction);
1057     if (d->properties == p)
1058         return;
1059     d->properties = p;
1060     emit propertiesChanged(p);
1061 }
1062
1063 QQmlListProperty<QObject> QQuickPropertyAction::targets()
1064 {
1065     Q_D(QQuickPropertyAction);
1066     return QQmlListProperty<QObject>(this, d->targets);
1067 }
1068
1069 /*!
1070     \qmlproperty list<Object> QtQuick2::PropertyAction::exclude
1071     This property holds the objects that should not be affected by this action.
1072
1073     \sa targets
1074 */
1075 QQmlListProperty<QObject> QQuickPropertyAction::exclude()
1076 {
1077     Q_D(QQuickPropertyAction);
1078     return QQmlListProperty<QObject>(this, d->exclude);
1079 }
1080
1081 /*!
1082     \qmlproperty any QtQuick2::PropertyAction::value
1083     This property holds the value to be set on the property.
1084
1085     If the PropertyAction is defined within a \l Transition or \l Behavior,
1086     this value defaults to the value defined in the end state of the
1087     \l Transition, or the value of the property change that triggered the
1088     \l Behavior.
1089 */
1090 QVariant QQuickPropertyAction::value() const
1091 {
1092     Q_D(const QQuickPropertyAction);
1093     return d->value;
1094 }
1095
1096 void QQuickPropertyAction::setValue(const QVariant &v)
1097 {
1098     Q_D(QQuickPropertyAction);
1099     if (d->value.isNull || d->value != v) {
1100         d->value = v;
1101         emit valueChanged(v);
1102     }
1103 }
1104
1105 QAbstractAnimationJob* QQuickPropertyAction::transition(QQuickStateActions &actions,
1106                                       QQmlProperties &modified,
1107                                       TransitionDirection direction,
1108                                       QObject *defaultTarget)
1109 {
1110     Q_D(QQuickPropertyAction);
1111     Q_UNUSED(direction);
1112
1113     struct QQuickSetPropertyAnimationAction : public QAbstractAnimationAction
1114     {
1115         QQuickStateActions actions;
1116         virtual void doAction()
1117         {
1118             for (int ii = 0; ii < actions.count(); ++ii) {
1119                 const QQuickAction &action = actions.at(ii);
1120                 QQmlPropertyPrivate::write(action.property, action.toValue, QQmlPropertyPrivate::BypassInterceptor | QQmlPropertyPrivate::DontRemoveBinding);
1121             }
1122         }
1123     };
1124
1125     QStringList props = d->properties.isEmpty() ? QStringList() : d->properties.split(QLatin1Char(','));
1126     for (int ii = 0; ii < props.count(); ++ii)
1127         props[ii] = props.at(ii).trimmed();
1128     if (!d->propertyName.isEmpty())
1129         props << d->propertyName;
1130
1131     QList<QObject*> targets = d->targets;
1132     if (d->target)
1133         targets.append(d->target);
1134
1135     bool hasSelectors = !props.isEmpty() || !targets.isEmpty() || !d->exclude.isEmpty();
1136
1137     if (d->defaultProperty.isValid() && !hasSelectors) {
1138         props << d->defaultProperty.name();
1139         targets << d->defaultProperty.object();
1140     }
1141
1142     if (defaultTarget && targets.isEmpty())
1143         targets << defaultTarget;
1144
1145     QQuickSetPropertyAnimationAction *data = new QQuickSetPropertyAnimationAction;
1146
1147     bool hasExplicit = false;
1148     //an explicit animation has been specified
1149     if (d->value.isValid()) {
1150         for (int i = 0; i < props.count(); ++i) {
1151             for (int j = 0; j < targets.count(); ++j) {
1152                 QQuickAction myAction;
1153                 myAction.property = d->createProperty(targets.at(j), props.at(i), this);
1154                 if (myAction.property.isValid()) {
1155                     myAction.toValue = d->value;
1156                     QQuickPropertyAnimationPrivate::convertVariant(myAction.toValue, myAction.property.propertyType());
1157                     data->actions << myAction;
1158                     hasExplicit = true;
1159                     for (int ii = 0; ii < actions.count(); ++ii) {
1160                         QQuickAction &action = actions[ii];
1161                         if (action.property.object() == myAction.property.object() &&
1162                             myAction.property.name() == action.property.name()) {
1163                             modified << action.property;
1164                             break;  //### any chance there could be multiples?
1165                         }
1166                     }
1167                 }
1168             }
1169         }
1170     }
1171
1172     if (!hasExplicit)
1173     for (int ii = 0; ii < actions.count(); ++ii) {
1174         QQuickAction &action = actions[ii];
1175
1176         QObject *obj = action.property.object();
1177         QString propertyName = action.property.name();
1178         QObject *sObj = action.specifiedObject;
1179         QString sPropertyName = action.specifiedProperty;
1180         bool same = (obj == sObj);
1181
1182         if ((targets.isEmpty() || targets.contains(obj) || (!same && targets.contains(sObj))) &&
1183            (!d->exclude.contains(obj)) && (same || (!d->exclude.contains(sObj))) &&
1184            (props.contains(propertyName) || (!same && props.contains(sPropertyName)))) {
1185             QQuickAction myAction = action;
1186
1187             if (d->value.isValid())
1188                 myAction.toValue = d->value;
1189             QQuickPropertyAnimationPrivate::convertVariant(myAction.toValue, myAction.property.propertyType());
1190
1191             modified << action.property;
1192             data->actions << myAction;
1193             action.fromValue = myAction.toValue;
1194         }
1195     }
1196
1197     QActionAnimation *action = new QActionAnimation;
1198     if (data->actions.count()) {
1199         action->setAnimAction(data);
1200     } else {
1201         delete data;
1202     }
1203     return initInstance(action);
1204 }
1205
1206 /*!
1207     \qmlclass NumberAnimation QQuickNumberAnimation
1208     \inqmlmodule QtQuick 2
1209   \ingroup qml-animation-transition
1210     \inherits PropertyAnimation
1211     \brief The NumberAnimation element animates changes in qreal-type values.
1212
1213     NumberAnimation is a specialized PropertyAnimation that defines an
1214     animation to be applied when a numerical value changes.
1215
1216     Here is a NumberAnimation applied to the \c x property of a \l Rectangle
1217     as a property value source. It animates the \c x value from its current
1218     value to a value of 50, over 1000 milliseconds:
1219
1220     \snippet doc/src/snippets/qml/numberanimation.qml 0
1221
1222     Like any other animation element, a NumberAnimation can be applied in a
1223     number of ways, including transitions, behaviors and property value
1224     sources. The \l {QML Animation and Transitions} documentation shows a
1225     variety of methods for creating animations.
1226
1227     Note that NumberAnimation may not animate smoothly if there are irregular
1228     changes in the number value that it is tracking. If this is the case, use
1229     SmoothedAnimation instead.
1230
1231     \sa {QML Animation and Transitions}, {qml/animation/basics}{Animation basics example}
1232 */
1233 QQuickNumberAnimation::QQuickNumberAnimation(QObject *parent)
1234 : QQuickPropertyAnimation(parent)
1235 {
1236     init();
1237 }
1238
1239 QQuickNumberAnimation::QQuickNumberAnimation(QQuickPropertyAnimationPrivate &dd, QObject *parent)
1240 : QQuickPropertyAnimation(dd, parent)
1241 {
1242     init();
1243 }
1244
1245 QQuickNumberAnimation::~QQuickNumberAnimation()
1246 {
1247 }
1248
1249 void QQuickNumberAnimation::init()
1250 {
1251     Q_D(QQuickPropertyAnimation);
1252     d->interpolatorType = QMetaType::QReal;
1253     d->interpolator = QVariantAnimationPrivate::getInterpolator(d->interpolatorType);
1254 }
1255
1256 /*!
1257     \qmlproperty real QtQuick2::NumberAnimation::from
1258     This property holds the starting value for the animation.
1259
1260     For example, the following animation is not applied until the \c x value
1261     has reached 100:
1262
1263     \qml
1264     Item {
1265         states: [
1266             // ...
1267         ]
1268
1269         transition: Transition {
1270             NumberAnimation { properties: "x"; from: 100; duration: 200 }
1271         }
1272     }
1273     \endqml
1274
1275     If the NumberAnimation is defined within a \l Transition or \l Behavior,
1276     this value defaults to the value defined in the starting state of the
1277     \l Transition, or the current value of the property at the moment the
1278     \l Behavior is triggered.
1279
1280     \sa {QML Animation and Transitions}
1281 */
1282
1283 qreal QQuickNumberAnimation::from() const
1284 {
1285     Q_D(const QQuickPropertyAnimation);
1286     return d->from.toReal();
1287 }
1288
1289 void QQuickNumberAnimation::setFrom(qreal f)
1290 {
1291     QQuickPropertyAnimation::setFrom(f);
1292 }
1293
1294 /*!
1295     \qmlproperty real QtQuick2::NumberAnimation::to
1296     This property holds the end value for the animation.
1297
1298     If the NumberAnimation is defined within a \l Transition or \l Behavior,
1299     this value defaults to the value defined in the end state of the
1300     \l Transition, or the value of the property change that triggered the
1301     \l Behavior.
1302
1303     \sa {QML Animation and Transitions}
1304 */
1305 qreal QQuickNumberAnimation::to() const
1306 {
1307     Q_D(const QQuickPropertyAnimation);
1308     return d->to.toReal();
1309 }
1310
1311 void QQuickNumberAnimation::setTo(qreal t)
1312 {
1313     QQuickPropertyAnimation::setTo(t);
1314 }
1315
1316
1317
1318 /*!
1319     \qmlclass Vector3dAnimation QQuickVector3dAnimation
1320     \inqmlmodule QtQuick 2
1321     \ingroup qml-animation-transition
1322     \inherits PropertyAnimation
1323     \brief The Vector3dAnimation element animates changes in QVector3d values.
1324
1325     Vector3dAnimation is a specialized PropertyAnimation that defines an
1326     animation to be applied when a Vector3d value changes.
1327
1328     Like any other animation element, a Vector3dAnimation can be applied in a
1329     number of ways, including transitions, behaviors and property value
1330     sources. The \l {QML Animation and Transitions} documentation shows a
1331     variety of methods for creating animations.
1332
1333     \sa {QML Animation and Transitions}, {qml/animation/basics}{Animation basics example}
1334 */
1335 QQuickVector3dAnimation::QQuickVector3dAnimation(QObject *parent)
1336 : QQuickPropertyAnimation(parent)
1337 {
1338     Q_D(QQuickPropertyAnimation);
1339     d->interpolatorType = QMetaType::QVector3D;
1340     d->defaultToInterpolatorType = true;
1341     d->interpolator = QVariantAnimationPrivate::getInterpolator(d->interpolatorType);
1342 }
1343
1344 QQuickVector3dAnimation::~QQuickVector3dAnimation()
1345 {
1346 }
1347
1348 /*!
1349     \qmlproperty real QtQuick2::Vector3dAnimation::from
1350     This property holds the starting value for the animation.
1351
1352     If the Vector3dAnimation is defined within a \l Transition or \l Behavior,
1353     this value defaults to the value defined in the starting state of the
1354     \l Transition, or the current value of the property at the moment the
1355     \l Behavior is triggered.
1356
1357     \sa {QML Animation and Transitions}
1358 */
1359 QVector3D QQuickVector3dAnimation::from() const
1360 {
1361     Q_D(const QQuickPropertyAnimation);
1362     return d->from.value<QVector3D>();
1363 }
1364
1365 void QQuickVector3dAnimation::setFrom(QVector3D f)
1366 {
1367     QQuickPropertyAnimation::setFrom(f);
1368 }
1369
1370 /*!
1371     \qmlproperty real QtQuick2::Vector3dAnimation::to
1372     This property holds the end value for the animation.
1373
1374     If the Vector3dAnimation is defined within a \l Transition or \l Behavior,
1375     this value defaults to the value defined in the end state of the
1376     \l Transition, or the value of the property change that triggered the
1377     \l Behavior.
1378
1379     \sa {QML Animation and Transitions}
1380 */
1381 QVector3D QQuickVector3dAnimation::to() const
1382 {
1383     Q_D(const QQuickPropertyAnimation);
1384     return d->to.value<QVector3D>();
1385 }
1386
1387 void QQuickVector3dAnimation::setTo(QVector3D t)
1388 {
1389     QQuickPropertyAnimation::setTo(t);
1390 }
1391
1392
1393
1394 /*!
1395     \qmlclass RotationAnimation QQuickRotationAnimation
1396     \inqmlmodule QtQuick 2
1397     \ingroup qml-animation-transition
1398     \inherits PropertyAnimation
1399     \brief The RotationAnimation element animates changes in rotation values.
1400
1401     RotationAnimation is a specialized PropertyAnimation that gives control
1402     over the direction of rotation during an animation.
1403
1404     By default, it rotates in the direction
1405     of the numerical change; a rotation from 0 to 240 will rotate 240 degrees
1406     clockwise, while a rotation from 240 to 0 will rotate 240 degrees
1407     counterclockwise. The \l direction property can be set to specify the
1408     direction in which the rotation should occur.
1409
1410     In the following example we use RotationAnimation to animate the rotation
1411     between states via the shortest path:
1412
1413     \snippet doc/src/snippets/qml/rotationanimation.qml 0
1414
1415     Notice the RotationAnimation did not need to set a \l target
1416     value. As a convenience, when used in a transition, RotationAnimation will rotate all
1417     properties named "rotation" or "angle". You can override this by providing
1418     your own properties via \l {PropertyAnimation::properties}{properties} or
1419     \l {PropertyAnimation::property}{property}.
1420
1421     Also, note the \l Rectangle will be rotated around its default
1422     \l {Item::}{transformOrigin} (which is \c Item.Center). To use a different
1423     transform origin, set the origin in the PropertyChanges object and apply
1424     the change at the start of the animation using PropertyAction. See the
1425     PropertyAction documentation for more details.
1426
1427     Like any other animation element, a RotationAnimation can be applied in a
1428     number of ways, including transitions, behaviors and property value
1429     sources. The \l {QML Animation and Transitions} documentation shows a
1430     variety of methods for creating animations.
1431
1432     \sa {QML Animation and Transitions}, {qml/animation/basics}{Animation basics example}
1433 */
1434 QVariant _q_interpolateShortestRotation(qreal &f, qreal &t, qreal progress)
1435 {
1436     qreal newt = t;
1437     qreal diff = t-f;
1438     while(diff > 180.0){
1439         newt -= 360.0;
1440         diff -= 360.0;
1441     }
1442     while(diff < -180.0){
1443         newt += 360.0;
1444         diff += 360.0;
1445     }
1446     return QVariant(f + (newt - f) * progress);
1447 }
1448
1449 QVariant _q_interpolateClockwiseRotation(qreal &f, qreal &t, qreal progress)
1450 {
1451     qreal newt = t;
1452     qreal diff = t-f;
1453     while(diff < 0.0){
1454         newt += 360.0;
1455         diff += 360.0;
1456     }
1457     return QVariant(f + (newt - f) * progress);
1458 }
1459
1460 QVariant _q_interpolateCounterclockwiseRotation(qreal &f, qreal &t, qreal progress)
1461 {
1462     qreal newt = t;
1463     qreal diff = t-f;
1464     while(diff > 0.0){
1465         newt -= 360.0;
1466         diff -= 360.0;
1467     }
1468     return QVariant(f + (newt - f) * progress);
1469 }
1470
1471 QQuickRotationAnimation::QQuickRotationAnimation(QObject *parent)
1472 : QQuickPropertyAnimation(*(new QQuickRotationAnimationPrivate), parent)
1473 {
1474     Q_D(QQuickRotationAnimation);
1475     d->interpolatorType = QMetaType::QReal;
1476     d->interpolator = QVariantAnimationPrivate::getInterpolator(d->interpolatorType);
1477     d->defaultProperties = QLatin1String("rotation,angle");
1478 }
1479
1480 QQuickRotationAnimation::~QQuickRotationAnimation()
1481 {
1482 }
1483
1484 /*!
1485     \qmlproperty real QtQuick2::RotationAnimation::from
1486     This property holds the starting value for the animation.
1487
1488     For example, the following animation is not applied until the \c angle value
1489     has reached 100:
1490
1491     \qml
1492     Item {
1493         states: [
1494             // ...
1495         ]
1496
1497         transition: Transition {
1498             RotationAnimation { properties: "angle"; from: 100; duration: 2000 }
1499         }
1500     }
1501     \endqml
1502
1503     If the RotationAnimation is defined within a \l Transition or \l Behavior,
1504     this value defaults to the value defined in the starting state of the
1505     \l Transition, or the current value of the property at the moment the
1506     \l Behavior is triggered.
1507
1508     \sa {QML Animation and Transitions}
1509 */
1510 qreal QQuickRotationAnimation::from() const
1511 {
1512     Q_D(const QQuickRotationAnimation);
1513     return d->from.toReal();
1514 }
1515
1516 void QQuickRotationAnimation::setFrom(qreal f)
1517 {
1518     QQuickPropertyAnimation::setFrom(f);
1519 }
1520
1521 /*!
1522     \qmlproperty real QtQuick2::RotationAnimation::to
1523     This property holds the end value for the animation..
1524
1525     If the RotationAnimation is defined within a \l Transition or \l Behavior,
1526     this value defaults to the value defined in the end state of the
1527     \l Transition, or the value of the property change that triggered the
1528     \l Behavior.
1529
1530     \sa {QML Animation and Transitions}
1531 */
1532 qreal QQuickRotationAnimation::to() const
1533 {
1534     Q_D(const QQuickRotationAnimation);
1535     return d->to.toReal();
1536 }
1537
1538 void QQuickRotationAnimation::setTo(qreal t)
1539 {
1540     QQuickPropertyAnimation::setTo(t);
1541 }
1542
1543 /*!
1544     \qmlproperty enumeration QtQuick2::RotationAnimation::direction
1545     This property holds the direction of the rotation.
1546
1547     Possible values are:
1548
1549     \list
1550     \li RotationAnimation.Numerical (default) - Rotate by linearly interpolating between the two numbers.
1551            A rotation from 10 to 350 will rotate 340 degrees clockwise.
1552     \li RotationAnimation.Clockwise - Rotate clockwise between the two values
1553     \li RotationAnimation.Counterclockwise - Rotate counterclockwise between the two values
1554     \li RotationAnimation.Shortest - Rotate in the direction that produces the shortest animation path.
1555            A rotation from 10 to 350 will rotate 20 degrees counterclockwise.
1556     \endlist
1557 */
1558 QQuickRotationAnimation::RotationDirection QQuickRotationAnimation::direction() const
1559 {
1560     Q_D(const QQuickRotationAnimation);
1561     return d->direction;
1562 }
1563
1564 void QQuickRotationAnimation::setDirection(QQuickRotationAnimation::RotationDirection direction)
1565 {
1566     Q_D(QQuickRotationAnimation);
1567     if (d->direction == direction)
1568         return;
1569
1570     d->direction = direction;
1571     switch(d->direction) {
1572     case Clockwise:
1573         d->interpolator = reinterpret_cast<QVariantAnimation::Interpolator>(&_q_interpolateClockwiseRotation);
1574         break;
1575     case Counterclockwise:
1576         d->interpolator = reinterpret_cast<QVariantAnimation::Interpolator>(&_q_interpolateCounterclockwiseRotation);
1577         break;
1578     case Shortest:
1579         d->interpolator = reinterpret_cast<QVariantAnimation::Interpolator>(&_q_interpolateShortestRotation);
1580         break;
1581     default:
1582         d->interpolator = QVariantAnimationPrivate::getInterpolator(d->interpolatorType);
1583         break;
1584     }
1585     emit directionChanged();
1586 }
1587
1588
1589
1590 QQuickAnimationGroup::QQuickAnimationGroup(QObject *parent)
1591 : QQuickAbstractAnimation(*(new QQuickAnimationGroupPrivate), parent)
1592 {
1593 }
1594
1595 QQuickAnimationGroup::QQuickAnimationGroup(QQuickAnimationGroupPrivate &dd, QObject *parent)
1596     : QQuickAbstractAnimation(dd, parent)
1597 {
1598 }
1599
1600 void QQuickAnimationGroupPrivate::append_animation(QQmlListProperty<QQuickAbstractAnimation> *list, QQuickAbstractAnimation *a)
1601 {
1602     QQuickAnimationGroup *q = qobject_cast<QQuickAnimationGroup *>(list->object);
1603     if (q) {
1604         a->setGroup(q);
1605     }
1606 }
1607
1608 void QQuickAnimationGroupPrivate::clear_animation(QQmlListProperty<QQuickAbstractAnimation> *list)
1609 {
1610     QQuickAnimationGroup *q = qobject_cast<QQuickAnimationGroup *>(list->object);
1611     if (q) {
1612         while (q->d_func()->animations.count()) {
1613             QQuickAbstractAnimation *firstAnim = q->d_func()->animations.at(0);
1614             firstAnim->setGroup(0);
1615         }
1616     }
1617 }
1618
1619 QQuickAnimationGroup::~QQuickAnimationGroup()
1620 {
1621 }
1622
1623 QQmlListProperty<QQuickAbstractAnimation> QQuickAnimationGroup::animations()
1624 {
1625     Q_D(QQuickAnimationGroup);
1626     QQmlListProperty<QQuickAbstractAnimation> list(this, d->animations);
1627     list.append = &QQuickAnimationGroupPrivate::append_animation;
1628     list.clear = &QQuickAnimationGroupPrivate::clear_animation;
1629     return list;
1630 }
1631
1632 /*!
1633     \qmlclass SequentialAnimation QQuickSequentialAnimation
1634     \inqmlmodule QtQuick 2
1635   \ingroup qml-animation-transition
1636     \inherits Animation
1637     \brief The SequentialAnimation element allows animations to be run sequentially.
1638
1639     The SequentialAnimation and ParallelAnimation elements allow multiple
1640     animations to be run together. Animations defined in a SequentialAnimation
1641     are run one after the other, while animations defined in a ParallelAnimation
1642     are run at the same time.
1643
1644     The following example runs two number animations in a sequence.  The \l Rectangle
1645     animates to a \c x position of 50, then to a \c y position of 50.
1646
1647     \snippet doc/src/snippets/qml/sequentialanimation.qml 0
1648
1649     Animations defined within a \l Transition are automatically run in parallel,
1650     so SequentialAnimation can be used to enclose the animations in a \l Transition
1651     if this is the preferred behavior.
1652
1653     Like any other animation element, a SequentialAnimation can be applied in a
1654     number of ways, including transitions, behaviors and property value
1655     sources. The \l {QML Animation and Transitions} documentation shows a
1656     variety of methods for creating animations.
1657
1658     \note Once an animation has been grouped into a SequentialAnimation or
1659     ParallelAnimation, it cannot be individually started and stopped; the
1660     SequentialAnimation or ParallelAnimation must be started and stopped as a group.
1661
1662     \sa ParallelAnimation, {QML Animation and Transitions}, {qml/animation/basics}{Animation basics example}
1663 */
1664
1665 QQuickSequentialAnimation::QQuickSequentialAnimation(QObject *parent) :
1666     QQuickAnimationGroup(parent)
1667 {
1668 }
1669
1670 QQuickSequentialAnimation::~QQuickSequentialAnimation()
1671 {
1672 }
1673
1674 QAbstractAnimationJob* QQuickSequentialAnimation::transition(QQuickStateActions &actions,
1675                                     QQmlProperties &modified,
1676                                     TransitionDirection direction,
1677                                     QObject *defaultTarget)
1678 {
1679     Q_D(QQuickAnimationGroup);
1680
1681     QSequentialAnimationGroupJob *ag = new QSequentialAnimationGroupJob;
1682
1683     int inc = 1;
1684     int from = 0;
1685     if (direction == Backward) {
1686         inc = -1;
1687         from = d->animations.count() - 1;
1688     }
1689
1690     bool valid = d->defaultProperty.isValid();
1691     QAbstractAnimationJob* anim;
1692     for (int ii = from; ii < d->animations.count() && ii >= 0; ii += inc) {
1693         if (valid)
1694             d->animations.at(ii)->setDefaultTarget(d->defaultProperty);
1695         anim = d->animations.at(ii)->transition(actions, modified, direction, defaultTarget);
1696         inc == -1 ? ag->prependAnimation(anim) : ag->appendAnimation(anim);
1697     }
1698
1699     return initInstance(ag);
1700 }
1701
1702
1703
1704 /*!
1705     \qmlclass ParallelAnimation QQuickParallelAnimation
1706     \inqmlmodule QtQuick 2
1707   \ingroup qml-animation-transition
1708     \inherits Animation
1709     \brief The ParallelAnimation element allows animations to be run in parallel.
1710
1711     The SequentialAnimation and ParallelAnimation elements allow multiple
1712     animations to be run together. Animations defined in a SequentialAnimation
1713     are run one after the other, while animations defined in a ParallelAnimation
1714     are run at the same time.
1715
1716     The following animation runs two number animations in parallel. The \l Rectangle
1717     moves to (50,50) by animating its \c x and \c y properties at the same time.
1718
1719     \snippet doc/src/snippets/qml/parallelanimation.qml 0
1720
1721     Like any other animation element, a ParallelAnimation can be applied in a
1722     number of ways, including transitions, behaviors and property value
1723     sources. The \l {QML Animation and Transitions} documentation shows a
1724     variety of methods for creating animations.
1725
1726     \note Once an animation has been grouped into a SequentialAnimation or
1727     ParallelAnimation, it cannot be individually started and stopped; the
1728     SequentialAnimation or ParallelAnimation must be started and stopped as a group.
1729
1730     \sa SequentialAnimation, {QML Animation and Transitions}, {qml/animation/basics}{Animation basics example}
1731 */
1732 QQuickParallelAnimation::QQuickParallelAnimation(QObject *parent) :
1733     QQuickAnimationGroup(parent)
1734 {
1735 }
1736
1737 QQuickParallelAnimation::~QQuickParallelAnimation()
1738 {
1739 }
1740
1741 QAbstractAnimationJob* QQuickParallelAnimation::transition(QQuickStateActions &actions,
1742                                       QQmlProperties &modified,
1743                                       TransitionDirection direction,
1744                                       QObject *defaultTarget)
1745 {
1746     Q_D(QQuickAnimationGroup);
1747     QParallelAnimationGroupJob *ag = new QParallelAnimationGroupJob;
1748
1749     bool valid = d->defaultProperty.isValid();
1750     QAbstractAnimationJob* anim;
1751     for (int ii = 0; ii < d->animations.count(); ++ii) {
1752         if (valid)
1753             d->animations.at(ii)->setDefaultTarget(d->defaultProperty);
1754         anim = d->animations.at(ii)->transition(actions, modified, direction, defaultTarget);
1755         ag->appendAnimation(anim);
1756     }
1757     return initInstance(ag);
1758 }
1759
1760 //convert a variant from string type to another animatable type
1761 void QQuickPropertyAnimationPrivate::convertVariant(QVariant &variant, int type)
1762 {
1763     if (variant.userType() != QVariant::String) {
1764         variant.convert((QVariant::Type)type);
1765         return;
1766     }
1767
1768     switch (type) {
1769     case QVariant::Rect:
1770     case QVariant::RectF:
1771     case QVariant::Point:
1772     case QVariant::PointF:
1773     case QVariant::Size:
1774     case QVariant::SizeF:
1775     case QVariant::Color:
1776     case QVariant::Vector3D:
1777         {
1778         bool ok = false;
1779         variant = QQmlStringConverters::variantFromString(variant.toString(), type, &ok);
1780         }
1781         break;
1782     default:
1783         if (QQmlValueTypeFactory::isValueType((uint)type)) {
1784             variant.convert((QVariant::Type)type);
1785         } else {
1786             QQmlMetaType::StringConverter converter = QQmlMetaType::customStringConverter(type);
1787             if (converter)
1788                 variant = converter(variant.toString());
1789         }
1790         break;
1791     }
1792 }
1793
1794 QQuickBulkValueAnimator::QQuickBulkValueAnimator()
1795     : QAbstractAnimationJob(), animValue(0), fromSourced(0), m_duration(250)
1796 {
1797 }
1798
1799 QQuickBulkValueAnimator::~QQuickBulkValueAnimator()
1800 {
1801     delete animValue;
1802 }
1803
1804 void QQuickBulkValueAnimator::setAnimValue(QQuickBulkValueUpdater *value)
1805 {
1806     if (isRunning())
1807         stop();
1808     animValue = value;
1809 }
1810
1811 void QQuickBulkValueAnimator::updateCurrentTime(int currentTime)
1812 {
1813     if (isStopped())
1814         return;
1815
1816     const qreal progress = easing.valueForProgress(((m_duration == 0) ? qreal(1) : qreal(currentTime) / qreal(m_duration)));
1817
1818     if (animValue)
1819         animValue->setValue(progress);
1820 }
1821
1822 void QQuickBulkValueAnimator::topLevelAnimationLoopChanged()
1823 {
1824     //check for new from every top-level loop (when the top level animation is started and all subsequent loops)
1825     if (fromSourced)
1826         *fromSourced = false;
1827 }
1828
1829 /*!
1830     \qmlclass PropertyAnimation QQuickPropertyAnimation
1831     \inqmlmodule QtQuick 2
1832   \ingroup qml-animation-transition
1833     \inherits Animation
1834     \brief The PropertyAnimation element animates changes in property values.
1835
1836     PropertyAnimation provides a way to animate changes to a property's value.
1837
1838     It can be used to define animations in a number of ways:
1839
1840     \list
1841     \li In a \l Transition
1842
1843     For example, to animate any objects that have changed their \c x or \c y properties
1844     as a result of a state change, using an \c InOutQuad easing curve:
1845
1846     \snippet doc/src/snippets/qml/propertyanimation.qml transition
1847
1848
1849     \li In a \l Behavior
1850
1851     For example, to animate all changes to a rectangle's \c x property:
1852
1853     \snippet doc/src/snippets/qml/propertyanimation.qml behavior
1854
1855
1856     \li As a property value source
1857
1858     For example, to repeatedly animate the rectangle's \c x property:
1859
1860     \snippet doc/src/snippets/qml/propertyanimation.qml propertyvaluesource
1861
1862
1863     \li In a signal handler
1864
1865     For example, to fade out \c theObject when clicked:
1866     \qml
1867     MouseArea {
1868         anchors.fill: theObject
1869         onClicked: PropertyAnimation { target: theObject; property: "opacity"; to: 0 }
1870     }
1871     \endqml
1872
1873     \li Standalone
1874
1875     For example, to animate \c rect's \c width property over 500ms, from its current width to 30:
1876
1877     \snippet doc/src/snippets/qml/propertyanimation.qml standalone
1878
1879     \endlist
1880
1881     Depending on how the animation is used, the set of properties normally used will be
1882     different. For more information see the individual property documentation, as well
1883     as the \l{QML Animation and Transitions} introduction.
1884
1885     Note that PropertyAnimation inherits the abstract \l Animation element.
1886     This includes additional properties and methods for controlling the animation.
1887
1888     \sa {QML Animation and Transitions}, {qml/animation/basics}{Animation basics example}
1889 */
1890
1891 QQuickPropertyAnimation::QQuickPropertyAnimation(QObject *parent)
1892 : QQuickAbstractAnimation(*(new QQuickPropertyAnimationPrivate), parent)
1893 {
1894 }
1895
1896 QQuickPropertyAnimation::QQuickPropertyAnimation(QQuickPropertyAnimationPrivate &dd, QObject *parent)
1897 : QQuickAbstractAnimation(dd, parent)
1898 {
1899 }
1900
1901 QQuickPropertyAnimation::~QQuickPropertyAnimation()
1902 {
1903 }
1904
1905 /*!
1906     \qmlproperty int QtQuick2::PropertyAnimation::duration
1907     This property holds the duration of the animation, in milliseconds.
1908
1909     The default value is 250.
1910 */
1911 int QQuickPropertyAnimation::duration() const
1912 {
1913     Q_D(const QQuickPropertyAnimation);
1914     return d->duration;
1915 }
1916
1917 void QQuickPropertyAnimation::setDuration(int duration)
1918 {
1919     if (duration < 0) {
1920         qmlInfo(this) << tr("Cannot set a duration of < 0");
1921         return;
1922     }
1923
1924     Q_D(QQuickPropertyAnimation);
1925     if (d->duration == duration)
1926         return;
1927     d->duration = duration;
1928     emit durationChanged(duration);
1929 }
1930
1931 /*!
1932     \qmlproperty real QtQuick2::PropertyAnimation::from
1933     This property holds the starting value for the animation.
1934
1935     If the PropertyAnimation is defined within a \l Transition or \l Behavior,
1936     this value defaults to the value defined in the starting state of the
1937     \l Transition, or the current value of the property at the moment the
1938     \l Behavior is triggered.
1939
1940     \sa {QML Animation and Transitions}
1941 */
1942 QVariant QQuickPropertyAnimation::from() const
1943 {
1944     Q_D(const QQuickPropertyAnimation);
1945     return d->from;
1946 }
1947
1948 void QQuickPropertyAnimation::setFrom(const QVariant &f)
1949 {
1950     Q_D(QQuickPropertyAnimation);
1951     if (d->fromIsDefined && f == d->from)
1952         return;
1953     d->from = f;
1954     d->fromIsDefined = f.isValid();
1955     emit fromChanged(f);
1956 }
1957
1958 /*!
1959     \qmlproperty real QtQuick2::PropertyAnimation::to
1960     This property holds the end value for the animation.
1961
1962     If the PropertyAnimation is defined within a \l Transition or \l Behavior,
1963     this value defaults to the value defined in the end state of the
1964     \l Transition, or the value of the property change that triggered the
1965     \l Behavior.
1966
1967     \sa {QML Animation and Transitions}
1968 */
1969 QVariant QQuickPropertyAnimation::to() const
1970 {
1971     Q_D(const QQuickPropertyAnimation);
1972     return d->to;
1973 }
1974
1975 void QQuickPropertyAnimation::setTo(const QVariant &t)
1976 {
1977     Q_D(QQuickPropertyAnimation);
1978     if (d->toIsDefined && t == d->to)
1979         return;
1980     d->to = t;
1981     d->toIsDefined = t.isValid();
1982     emit toChanged(t);
1983 }
1984
1985 /*!
1986     \qmlproperty enumeration QtQuick2::PropertyAnimation::easing.type
1987     \qmlproperty real QtQuick2::PropertyAnimation::easing.amplitude
1988     \qmlproperty real QtQuick2::PropertyAnimation::easing.overshoot
1989     \qmlproperty real QtQuick2::PropertyAnimation::easing.period
1990     \qmlproperty list<real> QtQuick2::PropertyAnimation::easing.bezierCurve
1991     \brief the easing curve used for the animation.
1992
1993     To specify an easing curve you need to specify at least the type. For some curves you can also specify
1994     amplitude, period and/or overshoot (more details provided after the table). The default easing curve is
1995     \c Easing.Linear.
1996
1997     \qml
1998     PropertyAnimation { properties: "y"; easing.type: Easing.InOutElastic; easing.amplitude: 2.0; easing.period: 1.5 }
1999     \endqml
2000
2001     Available types are:
2002
2003     \table
2004     \row
2005         \li \c Easing.Linear
2006         \li Easing curve for a linear (t) function: velocity is constant.
2007         \li \inlineimage qeasingcurve-linear.png
2008     \row
2009         \li \c Easing.InQuad
2010         \li Easing curve for a quadratic (t^2) function: accelerating from zero velocity.
2011         \li \inlineimage qeasingcurve-inquad.png
2012     \row
2013         \li \c Easing.OutQuad
2014         \li Easing curve for a quadratic (t^2) function: decelerating to zero velocity.
2015         \li \inlineimage qeasingcurve-outquad.png
2016     \row
2017         \li \c Easing.InOutQuad
2018         \li Easing curve for a quadratic (t^2) function: acceleration until halfway, then deceleration.
2019         \li \inlineimage qeasingcurve-inoutquad.png
2020     \row
2021         \li \c Easing.OutInQuad
2022         \li Easing curve for a quadratic (t^2) function: deceleration until halfway, then acceleration.
2023         \li \inlineimage qeasingcurve-outinquad.png
2024     \row
2025         \li \c Easing.InCubic
2026         \li Easing curve for a cubic (t^3) function: accelerating from zero velocity.
2027         \li \inlineimage qeasingcurve-incubic.png
2028     \row
2029         \li \c Easing.OutCubic
2030         \li Easing curve for a cubic (t^3) function: decelerating from zero velocity.
2031         \li \inlineimage qeasingcurve-outcubic.png
2032     \row
2033         \li \c Easing.InOutCubic
2034         \li Easing curve for a cubic (t^3) function: acceleration until halfway, then deceleration.
2035         \li \inlineimage qeasingcurve-inoutcubic.png
2036     \row
2037         \li \c Easing.OutInCubic
2038         \li Easing curve for a cubic (t^3) function: deceleration until halfway, then acceleration.
2039         \li \inlineimage qeasingcurve-outincubic.png
2040     \row
2041         \li \c Easing.InQuart
2042         \li Easing curve for a quartic (t^4) function: accelerating from zero velocity.
2043         \li \inlineimage qeasingcurve-inquart.png
2044     \row
2045         \li \c Easing.OutQuart
2046         \li Easing curve for a quartic (t^4) function: decelerating from zero velocity.
2047         \li \inlineimage qeasingcurve-outquart.png
2048     \row
2049         \li \c Easing.InOutQuart
2050         \li Easing curve for a quartic (t^4) function: acceleration until halfway, then deceleration.
2051         \li \inlineimage qeasingcurve-inoutquart.png
2052     \row
2053         \li \c Easing.OutInQuart
2054         \li Easing curve for a quartic (t^4) function: deceleration until halfway, then acceleration.
2055         \li \inlineimage qeasingcurve-outinquart.png
2056     \row
2057         \li \c Easing.InQuint
2058         \li Easing curve for a quintic (t^5) function: accelerating from zero velocity.
2059         \li \inlineimage qeasingcurve-inquint.png
2060     \row
2061         \li \c Easing.OutQuint
2062         \li Easing curve for a quintic (t^5) function: decelerating from zero velocity.
2063         \li \inlineimage qeasingcurve-outquint.png
2064     \row
2065         \li \c Easing.InOutQuint
2066         \li Easing curve for a quintic (t^5) function: acceleration until halfway, then deceleration.
2067         \li \inlineimage qeasingcurve-inoutquint.png
2068     \row
2069         \li \c Easing.OutInQuint
2070         \li Easing curve for a quintic (t^5) function: deceleration until halfway, then acceleration.
2071         \li \inlineimage qeasingcurve-outinquint.png
2072     \row
2073         \li \c Easing.InSine
2074         \li Easing curve for a sinusoidal (sin(t)) function: accelerating from zero velocity.
2075         \li \inlineimage qeasingcurve-insine.png
2076     \row
2077         \li \c Easing.OutSine
2078         \li Easing curve for a sinusoidal (sin(t)) function: decelerating from zero velocity.
2079         \li \inlineimage qeasingcurve-outsine.png
2080     \row
2081         \li \c Easing.InOutSine
2082         \li Easing curve for a sinusoidal (sin(t)) function: acceleration until halfway, then deceleration.
2083         \li \inlineimage qeasingcurve-inoutsine.png
2084     \row
2085         \li \c Easing.OutInSine
2086         \li Easing curve for a sinusoidal (sin(t)) function: deceleration until halfway, then acceleration.
2087         \li \inlineimage qeasingcurve-outinsine.png
2088     \row
2089         \li \c Easing.InExpo
2090         \li Easing curve for an exponential (2^t) function: accelerating from zero velocity.
2091         \li \inlineimage qeasingcurve-inexpo.png
2092     \row
2093         \li \c Easing.OutExpo
2094         \li Easing curve for an exponential (2^t) function: decelerating from zero velocity.
2095         \li \inlineimage qeasingcurve-outexpo.png
2096     \row
2097         \li \c Easing.InOutExpo
2098         \li Easing curve for an exponential (2^t) function: acceleration until halfway, then deceleration.
2099         \li \inlineimage qeasingcurve-inoutexpo.png
2100     \row
2101         \li \c Easing.OutInExpo
2102         \li Easing curve for an exponential (2^t) function: deceleration until halfway, then acceleration.
2103         \li \inlineimage qeasingcurve-outinexpo.png
2104     \row
2105         \li \c Easing.InCirc
2106         \li Easing curve for a circular (sqrt(1-t^2)) function: accelerating from zero velocity.
2107         \li \inlineimage qeasingcurve-incirc.png
2108     \row
2109         \li \c Easing.OutCirc
2110         \li Easing curve for a circular (sqrt(1-t^2)) function: decelerating from zero velocity.
2111         \li \inlineimage qeasingcurve-outcirc.png
2112     \row
2113         \li \c Easing.InOutCirc
2114         \li Easing curve for a circular (sqrt(1-t^2)) function: acceleration until halfway, then deceleration.
2115         \li \inlineimage qeasingcurve-inoutcirc.png
2116     \row
2117         \li \c Easing.OutInCirc
2118         \li Easing curve for a circular (sqrt(1-t^2)) function: deceleration until halfway, then acceleration.
2119         \li \inlineimage qeasingcurve-outincirc.png
2120     \row
2121         \li \c Easing.InElastic
2122         \li Easing curve for an elastic (exponentially decaying sine wave) function: accelerating from zero velocity.
2123         \br The peak amplitude can be set with the \e amplitude parameter, and the period of decay by the \e period parameter.
2124         \li \inlineimage qeasingcurve-inelastic.png
2125     \row
2126         \li \c Easing.OutElastic
2127         \li Easing curve for an elastic (exponentially decaying sine wave) function: decelerating from zero velocity.
2128         \br The peak amplitude can be set with the \e amplitude parameter, and the period of decay by the \e period parameter.
2129         \li \inlineimage qeasingcurve-outelastic.png
2130     \row
2131         \li \c Easing.InOutElastic
2132         \li Easing curve for an elastic (exponentially decaying sine wave) function: acceleration until halfway, then deceleration.
2133         \li \inlineimage qeasingcurve-inoutelastic.png
2134     \row
2135         \li \c Easing.OutInElastic
2136         \li Easing curve for an elastic (exponentially decaying sine wave) function: deceleration until halfway, then acceleration.
2137         \li \inlineimage qeasingcurve-outinelastic.png
2138     \row
2139         \li \c Easing.InBack
2140         \li Easing curve for a back (overshooting cubic function: (s+1)*t^3 - s*t^2) easing in: accelerating from zero velocity.
2141         \li \inlineimage qeasingcurve-inback.png
2142     \row
2143         \li \c Easing.OutBack
2144         \li Easing curve for a back (overshooting cubic function: (s+1)*t^3 - s*t^2) easing out: decelerating to zero velocity.
2145         \li \inlineimage qeasingcurve-outback.png
2146     \row
2147         \li \c Easing.InOutBack
2148         \li Easing curve for a back (overshooting cubic function: (s+1)*t^3 - s*t^2) easing in/out: acceleration until halfway, then deceleration.
2149         \li \inlineimage qeasingcurve-inoutback.png
2150     \row
2151         \li \c Easing.OutInBack
2152         \li Easing curve for a back (overshooting cubic easing: (s+1)*t^3 - s*t^2) easing out/in: deceleration until halfway, then acceleration.
2153         \li \inlineimage qeasingcurve-outinback.png
2154     \row
2155         \li \c Easing.InBounce
2156         \li Easing curve for a bounce (exponentially decaying parabolic bounce) function: accelerating from zero velocity.
2157         \li \inlineimage qeasingcurve-inbounce.png
2158     \row
2159         \li \c Easing.OutBounce
2160         \li Easing curve for a bounce (exponentially decaying parabolic bounce) function: decelerating from zero velocity.
2161         \li \inlineimage qeasingcurve-outbounce.png
2162     \row
2163         \li \c Easing.InOutBounce
2164         \li Easing curve for a bounce (exponentially decaying parabolic bounce) function easing in/out: acceleration until halfway, then deceleration.
2165         \li \inlineimage qeasingcurve-inoutbounce.png
2166     \row
2167         \li \c Easing.OutInBounce
2168         \li Easing curve for a bounce (exponentially decaying parabolic bounce) function easing out/in: deceleration until halfway, then acceleration.
2169         \li \inlineimage qeasingcurve-outinbounce.png
2170     \row
2171         \li \c Easing.Bezier
2172         \li Custom easing curve defined by the easing.bezierCurve property.
2173         \li
2174     \endtable
2175
2176     \c easing.amplitude is only applicable for bounce and elastic curves (curves of type
2177     \c Easing.InBounce, \c Easing.OutBounce, \c Easing.InOutBounce, \c Easing.OutInBounce, \c Easing.InElastic,
2178     \c Easing.OutElastic, \c Easing.InOutElastic or \c Easing.OutInElastic).
2179
2180     \c easing.overshoot is only applicable if \c easing.type is: \c Easing.InBack, \c Easing.OutBack,
2181     \c Easing.InOutBack or \c Easing.OutInBack.
2182
2183     \c easing.period is only applicable if easing.type is: \c Easing.InElastic, \c Easing.OutElastic,
2184     \c Easing.InOutElastic or \c Easing.OutInElastic.
2185
2186     \c easing.bezierCurve is only applicable if easing.type is: \c Easing.Bezier.  This property is a list<real> containing
2187     groups of three points defining a curve from 0,0 to 1,1 - control1, control2,
2188     end point: [cx1, cy1, cx2, cy2, endx, endy, ...].  The last point must be 1,1.
2189
2190     See the \l {qml/animation/easing}{easing} example for a demonstration of
2191     the different easing settings.
2192 */
2193 QEasingCurve QQuickPropertyAnimation::easing() const
2194 {
2195     Q_D(const QQuickPropertyAnimation);
2196     return d->easing;
2197 }
2198
2199 void QQuickPropertyAnimation::setEasing(const QEasingCurve &e)
2200 {
2201     Q_D(QQuickPropertyAnimation);
2202     if (d->easing == e)
2203         return;
2204
2205     d->easing = e;
2206     emit easingChanged(e);
2207 }
2208
2209 QObject *QQuickPropertyAnimation::target() const
2210 {
2211     Q_D(const QQuickPropertyAnimation);
2212     return d->target;
2213 }
2214
2215 void QQuickPropertyAnimation::setTargetObject(QObject *o)
2216 {
2217     Q_D(QQuickPropertyAnimation);
2218     if (d->target == o)
2219         return;
2220     d->target = o;
2221     emit targetChanged();
2222 }
2223
2224 QString QQuickPropertyAnimation::property() const
2225 {
2226     Q_D(const QQuickPropertyAnimation);
2227     return d->propertyName;
2228 }
2229
2230 void QQuickPropertyAnimation::setProperty(const QString &n)
2231 {
2232     Q_D(QQuickPropertyAnimation);
2233     if (d->propertyName == n)
2234         return;
2235     d->propertyName = n;
2236     emit propertyChanged();
2237 }
2238
2239 QString QQuickPropertyAnimation::properties() const
2240 {
2241     Q_D(const QQuickPropertyAnimation);
2242     return d->properties;
2243 }
2244
2245 void QQuickPropertyAnimation::setProperties(const QString &prop)
2246 {
2247     Q_D(QQuickPropertyAnimation);
2248     if (d->properties == prop)
2249         return;
2250
2251     d->properties = prop;
2252     emit propertiesChanged(prop);
2253 }
2254
2255 /*!
2256     \qmlproperty string QtQuick2::PropertyAnimation::properties
2257     \qmlproperty list<Object> QtQuick2::PropertyAnimation::targets
2258     \qmlproperty string QtQuick2::PropertyAnimation::property
2259     \qmlproperty Object QtQuick2::PropertyAnimation::target
2260
2261     These properties are used as a set to determine which properties should be animated.
2262     The singular and plural forms are functionally identical, e.g.
2263     \qml
2264     NumberAnimation { target: theItem; property: "x"; to: 500 }
2265     \endqml
2266     has the same meaning as
2267     \qml
2268     NumberAnimation { targets: theItem; properties: "x"; to: 500 }
2269     \endqml
2270     The singular forms are slightly optimized, so if you do have only a single target/property
2271     to animate you should try to use them.
2272
2273     The \c targets property allows multiple targets to be set. For example, this animates the
2274     \c x property of both \c itemA and \c itemB:
2275
2276     \qml
2277     NumberAnimation { targets: [itemA, itemB]; properties: "x"; to: 500 }
2278     \endqml
2279
2280     In many cases these properties do not need to be explicitly specified, as they can be
2281     inferred from the animation framework:
2282
2283     \table 80%
2284     \row
2285     \li Value Source / Behavior
2286     \li When an animation is used as a value source or in a Behavior, the default target and property
2287        name to be animated can both be inferred.
2288        \qml
2289        Rectangle {
2290            id: theRect
2291            width: 100; height: 100
2292            color: Qt.rgba(0,0,1)
2293            NumberAnimation on x { to: 500; loops: Animation.Infinite } //animate theRect's x property
2294            Behavior on y { NumberAnimation {} } //animate theRect's y property
2295        }
2296        \endqml
2297     \row
2298     \li Transition
2299     \li When used in a transition, a property animation is assumed to match \e all targets
2300        but \e no properties. In practice, that means you need to specify at least the properties
2301        in order for the animation to do anything.
2302        \qml
2303        Rectangle {
2304            id: theRect
2305            width: 100; height: 100
2306            color: Qt.rgba(0,0,1)
2307            Item { id: uselessItem }
2308            states: State {
2309                name: "state1"
2310                PropertyChanges { target: theRect; x: 200; y: 200; z: 4 }
2311                PropertyChanges { target: uselessItem; x: 10; y: 10; z: 2 }
2312            }
2313            transitions: Transition {
2314                //animate both theRect's and uselessItem's x and y to their final values
2315                NumberAnimation { properties: "x,y" }
2316
2317                //animate theRect's z to its final value
2318                NumberAnimation { target: theRect; property: "z" }
2319            }
2320        }
2321        \endqml
2322     \row
2323     \li Standalone
2324     \li When an animation is used standalone, both the target and property need to be
2325        explicitly specified.
2326        \qml
2327        Rectangle {
2328            id: theRect
2329            width: 100; height: 100
2330            color: Qt.rgba(0,0,1)
2331            //need to explicitly specify target and property
2332            NumberAnimation { id: theAnim; target: theRect; property: "x"; to: 500 }
2333            MouseArea {
2334                anchors.fill: parent
2335                onClicked: theAnim.start()
2336            }
2337        }
2338        \endqml
2339     \endtable
2340
2341     As seen in the above example, properties is specified as a comma-separated string of property names to animate.
2342
2343     \sa exclude, {QML Animation and Transitions}
2344 */
2345 QQmlListProperty<QObject> QQuickPropertyAnimation::targets()
2346 {
2347     Q_D(QQuickPropertyAnimation);
2348     return QQmlListProperty<QObject>(this, d->targets);
2349 }
2350
2351 /*!
2352     \qmlproperty list<Object> QtQuick2::PropertyAnimation::exclude
2353     This property holds the items not to be affected by this animation.
2354     \sa PropertyAnimation::targets
2355 */
2356 QQmlListProperty<QObject> QQuickPropertyAnimation::exclude()
2357 {
2358     Q_D(QQuickPropertyAnimation);
2359     return QQmlListProperty<QObject>(this, d->exclude);
2360 }
2361
2362 void QQuickAnimationPropertyUpdater::setValue(qreal v)
2363 {
2364     bool deleted = false;
2365     wasDeleted = &deleted;
2366     if (reverse)
2367         v = 1 - v;
2368     for (int ii = 0; ii < actions.count(); ++ii) {
2369         QQuickAction &action = actions[ii];
2370
2371         if (v == 1.) {
2372             QQmlPropertyPrivate::write(action.property, action.toValue, QQmlPropertyPrivate::BypassInterceptor | QQmlPropertyPrivate::DontRemoveBinding);
2373         } else {
2374             if (!fromSourced && !fromDefined) {
2375                 action.fromValue = action.property.read();
2376                 if (interpolatorType) {
2377                     QQuickPropertyAnimationPrivate::convertVariant(action.fromValue, interpolatorType);
2378                 }
2379             }
2380             if (!interpolatorType) {
2381                 int propType = action.property.propertyType();
2382                 if (!prevInterpolatorType || prevInterpolatorType != propType) {
2383                     prevInterpolatorType = propType;
2384                     interpolator = QVariantAnimationPrivate::getInterpolator(prevInterpolatorType);
2385                 }
2386             }
2387             if (interpolator)
2388                 QQmlPropertyPrivate::write(action.property, interpolator(action.fromValue.constData(), action.toValue.constData(), v), QQmlPropertyPrivate::BypassInterceptor | QQmlPropertyPrivate::DontRemoveBinding);
2389         }
2390         if (deleted)
2391             return;
2392     }
2393     wasDeleted = 0;
2394     fromSourced = true;
2395 }
2396
2397 QQuickStateActions QQuickPropertyAnimation::createTransitionActions(QQuickStateActions &actions,
2398                                                                                 QQmlProperties &modified,
2399                                                                                 QObject *defaultTarget)
2400 {
2401     Q_D(QQuickPropertyAnimation);
2402     QQuickStateActions newActions;
2403
2404     QStringList props = d->properties.isEmpty() ? QStringList() : d->properties.split(QLatin1Char(','));
2405     for (int ii = 0; ii < props.count(); ++ii)
2406         props[ii] = props.at(ii).trimmed();
2407     if (!d->propertyName.isEmpty())
2408         props << d->propertyName;
2409
2410     QList<QObject*> targets = d->targets;
2411     if (d->target)
2412         targets.append(d->target);
2413
2414     bool hasSelectors = !props.isEmpty() || !targets.isEmpty() || !d->exclude.isEmpty();
2415     bool useType = (props.isEmpty() && d->defaultToInterpolatorType) ? true : false;
2416
2417     if (d->defaultProperty.isValid() && !hasSelectors) {
2418         props << d->defaultProperty.name();
2419         targets << d->defaultProperty.object();
2420     }
2421
2422     if (defaultTarget && targets.isEmpty())
2423         targets << defaultTarget;
2424
2425     if (props.isEmpty() && !d->defaultProperties.isEmpty()) {
2426         props << d->defaultProperties.split(QLatin1Char(','));
2427     }
2428
2429     bool hasExplicit = false;
2430     //an explicit animation has been specified
2431     if (d->toIsDefined) {
2432         for (int i = 0; i < props.count(); ++i) {
2433             for (int j = 0; j < targets.count(); ++j) {
2434                 QQuickAction myAction;
2435                 myAction.property = d->createProperty(targets.at(j), props.at(i), this);
2436                 if (myAction.property.isValid()) {
2437                     if (d->fromIsDefined) {
2438                         myAction.fromValue = d->from;
2439                         d->convertVariant(myAction.fromValue, d->interpolatorType ? d->interpolatorType : myAction.property.propertyType());
2440                     }
2441                     myAction.toValue = d->to;
2442                     d->convertVariant(myAction.toValue, d->interpolatorType ? d->interpolatorType : myAction.property.propertyType());
2443                     newActions << myAction;
2444                     hasExplicit = true;
2445                     for (int ii = 0; ii < actions.count(); ++ii) {
2446                         QQuickAction &action = actions[ii];
2447                         if (action.property.object() == myAction.property.object() &&
2448                             myAction.property.name() == action.property.name()) {
2449                             modified << action.property;
2450                             break;  //### any chance there could be multiples?
2451                         }
2452                     }
2453                 }
2454             }
2455         }
2456     }
2457
2458     if (!hasExplicit)
2459     for (int ii = 0; ii < actions.count(); ++ii) {
2460         QQuickAction &action = actions[ii];
2461
2462         QObject *obj = action.property.object();
2463         QString propertyName = action.property.name();
2464         QObject *sObj = action.specifiedObject;
2465         QString sPropertyName = action.specifiedProperty;
2466         bool same = (obj == sObj);
2467
2468         if ((targets.isEmpty() || targets.contains(obj) || (!same && targets.contains(sObj))) &&
2469            (!d->exclude.contains(obj)) && (same || (!d->exclude.contains(sObj))) &&
2470            (props.contains(propertyName) || (!same && props.contains(sPropertyName))
2471                || (useType && action.property.propertyType() == d->interpolatorType))) {
2472             QQuickAction myAction = action;
2473
2474             if (d->fromIsDefined)
2475                 myAction.fromValue = d->from;
2476             else
2477                 myAction.fromValue = QVariant();
2478             if (d->toIsDefined)
2479                 myAction.toValue = d->to;
2480
2481             d->convertVariant(myAction.fromValue, d->interpolatorType ? d->interpolatorType : myAction.property.propertyType());
2482             d->convertVariant(myAction.toValue, d->interpolatorType ? d->interpolatorType : myAction.property.propertyType());
2483
2484             modified << action.property;
2485
2486             newActions << myAction;
2487             action.fromValue = myAction.toValue;
2488         }
2489     }
2490     return newActions;
2491 }
2492
2493 QAbstractAnimationJob* QQuickPropertyAnimation::transition(QQuickStateActions &actions,
2494                                                                      QQmlProperties &modified,
2495                                                                      TransitionDirection direction,
2496                                                                      QObject *defaultTarget)
2497 {
2498     Q_D(QQuickPropertyAnimation);
2499
2500     QQuickStateActions dataActions = createTransitionActions(actions, modified, defaultTarget);
2501
2502     QQuickBulkValueAnimator *animator = new QQuickBulkValueAnimator;
2503     animator->setDuration(d->duration);
2504     animator->setEasingCurve(d->easing);
2505
2506     if (!dataActions.isEmpty()) {
2507         QQuickAnimationPropertyUpdater *data = new QQuickAnimationPropertyUpdater;
2508         data->interpolatorType = d->interpolatorType;
2509         data->interpolator = d->interpolator;
2510         data->reverse = direction == Backward ? true : false;
2511         data->fromSourced = false;
2512         data->fromDefined = d->fromIsDefined;
2513         data->actions = dataActions;
2514         animator->setAnimValue(data);
2515         animator->setFromSourcedValue(&data->fromSourced);
2516         d->actions = &data->actions; //remove this?
2517     }
2518
2519     return initInstance(animator);
2520 }
2521
2522 QT_END_NAMESPACE