1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \class QGraphicsItemAnimation

    44     \brief The QGraphicsItemAnimation class provides simple animation

    45     support for QGraphicsItem.

    46     \since 4.2

    47     \ingroup graphicsview-api

    48 

    49     The QGraphicsItemAnimation class animates a QGraphicsItem. You can

    50     schedule changes to the item's transformation matrix at

    51     specified steps. The QGraphicsItemAnimation class has a 

    52     current step value. When this value changes the transformations 

    53     scheduled at that step are performed. The current step of the 

    54     animation is set with the \c setStep() function.

    55 

    56     QGraphicsItemAnimation will do a simple linear interpolation

    57     between the nearest adjacent scheduled changes to calculate the 

    58     matrix. For instance, if you set the position of an item at values

    59     0.0 and 1.0, the animation will show the item moving in a straight

    60     line between these positions. The same is true for scaling and 

    61     rotation.

    62 

    63     It is usual to use the class with a QTimeLine. The timeline's

    64     \l{QTimeLine::}{valueChanged()} signal is then connected to the 

    65     \c setStep() slot. For example, you can set up an item for rotation

    66     by calling \c setRotationAt() for different step values.

    67     The animations timeline is set with the setTimeLine() function.

    68 

    69     An example animation with a timeline follows:

    70 

    71     \snippet doc/src/snippets/timeline/main.cpp 0

    72 

    73     Note that steps lie between 0.0 and 1.0. It may be necessary to use

    74     \l{QTimeLine::}{setUpdateInterval()}. The default update interval

    75     is 40 ms. A scheduled transformation cannot be removed when set,

    76     so scheduling several transformations of the same kind (e.g.,

    77     rotations) at the same step is not recommended.

    78 

    79     \sa QTimeLine, {The Graphics View Framework}

    80 */

    81 

    82 #include "qgraphicsitemanimation.h"

    83 

    84 #ifndef QT_NO_GRAPHICSVIEW

    85 

    86 #include "qgraphicsitem.h"

    87 

    88 #include <QtCore/qtimeline.h>

    89 #include <QtCore/qpoint.h>

    90 #include <QtCore/qpointer.h>

    91 #include <QtCore/qpair.h>

    92 #include <QtGui/qmatrix.h>

    93 

    94 QT_BEGIN_NAMESPACE

    95 

    96 class QGraphicsItemAnimationPrivate

    97 {

    98 public:

    99     inline QGraphicsItemAnimationPrivate()

   100         : q(0), timeLine(0), item(0), step(0)

   101     { }

   102 

   103     QGraphicsItemAnimation *q;

   104 

   105     QPointer<QTimeLine> timeLine;

   106     QGraphicsItem *item;

   107 

   108     QPointF startPos;

   109     QMatrix startMatrix;

   110 

   111     qreal step;

   112 

   113     struct Pair {

   114         Pair(qreal a, qreal b) : step(a), value(b) {}

   115         bool operator <(const Pair &other) const

   116         { return step < other.step; }

   117         bool operator==(const Pair &other) const

   118         { return step == other.step; }

   119         qreal step;

   120         qreal value;

   121     };

   122     QList<Pair> xPosition;

   123     QList<Pair> yPosition;

   124     QList<Pair> rotation;

   125     QList<Pair> verticalScale;

   126     QList<Pair> horizontalScale;

   127     QList<Pair> verticalShear;

   128     QList<Pair> horizontalShear;

   129     QList<Pair> xTranslation;

   130     QList<Pair> yTranslation;

   131 

   132     qreal linearValueForStep(qreal step, QList<Pair> *source, qreal defaultValue = 0);

   133     void insertUniquePair(qreal step, qreal value, QList<Pair> *binList, const char* method);

   134 };

   135 

   136 qreal QGraphicsItemAnimationPrivate::linearValueForStep(qreal step, QList<Pair> *source, qreal defaultValue)

   137 {

   138     if (source->isEmpty())

   139         return defaultValue;

   140     step = qMin<qreal>(qMax<qreal>(step, 0), 1);

   141 

   142     if (step == 1)

   143         return source->last().value;

   144 

   145     qreal stepBefore = 0;

   146     qreal stepAfter = 1;

   147     qreal valueBefore = source->first().step == 0 ? source->first().value : defaultValue;

   148     qreal valueAfter = source->last().value;

   149 

   150     // Find the closest step and value before the given step.

   151     for (int i = 0; i < source->size() && step >= source->at(i).step; ++i) {

   152         stepBefore = source->at(i).step;

   153         valueBefore = source->at(i).value;

   154     }

   155 

   156     // Find the closest step and value after the given step.

   157     for (int j = source->size() - 1; j >= 0 && step < source->at(j).step; --j) {

   158         stepAfter = source->at(j).step;

   159         valueAfter = source->at(j).value;

   160     }

   161 

   162     // Do a simple linear interpolation.

   163     return valueBefore + (valueAfter - valueBefore) * ((step - stepBefore) / (stepAfter - stepBefore));

   164 }

   165 

   166 void QGraphicsItemAnimationPrivate::insertUniquePair(qreal step, qreal value, QList<Pair> *binList, const char* method)

   167 {

   168     if (step < 0.0 || step > 1.0) {

   169         qWarning("QGraphicsItemAnimation::%s: invalid step = %f", method, step);

   170         return;

   171     }

   172 

   173     Pair pair(step, value);

   174 

   175     QList<Pair>::iterator result = qBinaryFind(binList->begin(), binList->end(), pair);

   176     if (result != binList->end())

   177         result->value = value;

   178     else {

   179         *binList << pair;

   180         qSort(binList->begin(), binList->end());

   181     }

   182 }

   183 

   184 /*!

   185   Constructs an animation object with the given \a parent.

   186 */

   187 QGraphicsItemAnimation::QGraphicsItemAnimation(QObject *parent)

   188     : QObject(parent), d(new QGraphicsItemAnimationPrivate)

   189 {

   190     d->q = this;

   191 }

   192 

   193 /*!

   194   Destroys the animation object.

   195 */

   196 QGraphicsItemAnimation::~QGraphicsItemAnimation()

   197 {

   198     delete d;

   199 }

   200 

   201 /*!

   202   Returns the item on which the animation object operates.

   203 

   204   \sa setItem()

   205 */

   206 QGraphicsItem *QGraphicsItemAnimation::item() const

   207 {

   208     return d->item;

   209 }

   210 

   211 /*!

   212   Sets the specified \a item to be used in the animation.

   213 

   214   \sa item()

   215 */

   216 void QGraphicsItemAnimation::setItem(QGraphicsItem *item)

   217 {

   218     d->item = item;

   219     d->startPos = d->item->pos();

   220 }

   221 

   222 /*!

   223   Returns the timeline object used to control the rate at which the animation

   224   occurs.

   225 

   226   \sa setTimeLine()

   227 */

   228 QTimeLine *QGraphicsItemAnimation::timeLine() const

   229 {

   230     return d->timeLine;

   231 }

   232 

   233 /*!

   234   Sets the timeline object used to control the rate of animation to the \a timeLine

   235   specified.

   236 

   237   \sa timeLine()

   238 */

   239 void QGraphicsItemAnimation::setTimeLine(QTimeLine *timeLine)

   240 {

   241     if (d->timeLine == timeLine)

   242         return;

   243     if (d->timeLine)

   244         delete d->timeLine;

   245     if (!timeLine)

   246         return;

   247     d->timeLine = timeLine;

   248     connect(timeLine, SIGNAL(valueChanged(qreal)), this, SLOT(setStep(qreal)));

   249 }

   250 

   251 /*!

   252   Returns the position of the item at the given \a step value.

   253 

   254   \sa setPosAt()

   255 */

   256 QPointF QGraphicsItemAnimation::posAt(qreal step) const

   257 {

   258     if (step < 0.0 || step > 1.0)

   259         qWarning("QGraphicsItemAnimation::posAt: invalid step = %f", step);

   260 

   261     return QPointF(d->linearValueForStep(step, &d->xPosition, d->startPos.x()),

   262                    d->linearValueForStep(step, &d->yPosition, d->startPos.y()));

   263 }

   264 

   265 /*!

   266   \fn void QGraphicsItemAnimation::setPosAt(qreal step, const QPointF &point)

   267 

   268   Sets the position of the item at the given \a step value to the \a point specified.

   269 

   270   \sa posAt()

   271 */

   272 void QGraphicsItemAnimation::setPosAt(qreal step, const QPointF &pos)

   273 {

   274     d->insertUniquePair(step, pos.x(), &d->xPosition, "setPosAt");

   275     d->insertUniquePair(step, pos.y(), &d->yPosition, "setPosAt");

   276 }

   277 

   278 /*!

   279   Returns all explicitly inserted positions.

   280 

   281   \sa posAt(), setPosAt()

   282 */

   283 QList<QPair<qreal, QPointF> > QGraphicsItemAnimation::posList() const

   284 {

   285     QList<QPair<qreal, QPointF> > list;

   286     for (int i = 0; i < d->xPosition.size(); ++i)

   287         list << QPair<qreal, QPointF>(d->xPosition.at(i).step, QPointF(d->xPosition.at(i).value, d->yPosition.at(i).value));

   288     

   289     return list;

   290 }

   291 

   292 /*!

   293   Returns the matrix used to transform the item at the specified \a step value.

   294 */

   295 QMatrix QGraphicsItemAnimation::matrixAt(qreal step) const

   296 {

   297     if (step < 0.0 || step > 1.0)

   298         qWarning("QGraphicsItemAnimation::matrixAt: invalid step = %f", step);

   299 

   300     QMatrix matrix;

   301     if (!d->rotation.isEmpty())

   302         matrix.rotate(rotationAt(step));

   303     if (!d->verticalScale.isEmpty())

   304         matrix.scale(horizontalScaleAt(step), verticalScaleAt(step));

   305     if (!d->verticalShear.isEmpty())

   306         matrix.shear(horizontalShearAt(step), verticalShearAt(step));

   307     if (!d->xTranslation.isEmpty())

   308         matrix.translate(xTranslationAt(step), yTranslationAt(step));

   309     return matrix;

   310 }

   311 

   312 /*!

   313   Returns the angle at which the item is rotated at the specified \a step value.

   314 

   315   \sa setRotationAt()

   316 */

   317 qreal QGraphicsItemAnimation::rotationAt(qreal step) const

   318 {

   319     if (step < 0.0 || step > 1.0)

   320         qWarning("QGraphicsItemAnimation::rotationAt: invalid step = %f", step);

   321 

   322     return d->linearValueForStep(step, &d->rotation);

   323 }

   324 

   325 /*!

   326   Sets the rotation of the item at the given \a step value to the \a angle specified.

   327 

   328   \sa rotationAt()

   329 */

   330 void QGraphicsItemAnimation::setRotationAt(qreal step, qreal angle)

   331 {

   332     d->insertUniquePair(step, angle, &d->rotation, "setRotationAt");

   333 }

   334 

   335 /*!

   336   Returns all explicitly inserted rotations.

   337 

   338   \sa rotationAt(), setRotationAt()

   339 */

   340 QList<QPair<qreal, qreal> > QGraphicsItemAnimation::rotationList() const

   341 {

   342     QList<QPair<qreal, qreal> > list;

   343     for (int i = 0; i < d->rotation.size(); ++i)

   344         list << QPair<qreal, qreal>(d->rotation.at(i).step, d->rotation.at(i).value);

   345     

   346     return list;

   347 }

   348 

   349 /*!

   350   Returns the horizontal translation of the item at the specified \a step value.

   351 

   352   \sa setTranslationAt()

   353 */

   354 qreal QGraphicsItemAnimation::xTranslationAt(qreal step) const

   355 {

   356     if (step < 0.0 || step > 1.0)

   357         qWarning("QGraphicsItemAnimation::xTranslationAt: invalid step = %f", step);

   358 

   359     return d->linearValueForStep(step, &d->xTranslation);

   360 }

   361 

   362 /*!

   363   Returns the vertical translation of the item at the specified \a step value.

   364 

   365   \sa setTranslationAt()

   366 */

   367 qreal QGraphicsItemAnimation::yTranslationAt(qreal step) const

   368 {

   369     if (step < 0.0 || step > 1.0)

   370         qWarning("QGraphicsItemAnimation::yTranslationAt: invalid step = %f", step);

   371 

   372     return d->linearValueForStep(step, &d->yTranslation);

   373 }

   374 

   375 /*!

   376   Sets the translation of the item at the given \a step value using the horizontal

   377   and vertical coordinates specified by \a dx and \a dy.

   378 

   379   \sa xTranslationAt(), yTranslationAt()

   380 */

   381 void QGraphicsItemAnimation::setTranslationAt(qreal step, qreal dx, qreal dy)

   382 {

   383     d->insertUniquePair(step, dx, &d->xTranslation, "setTranslationAt");

   384     d->insertUniquePair(step, dy, &d->yTranslation, "setTranslationAt");

   385 }

   386 

   387 /*!

   388   Returns all explicitly inserted translations.

   389 

   390   \sa xTranslationAt(), yTranslationAt(), setTranslationAt()

   391 */

   392 QList<QPair<qreal, QPointF> > QGraphicsItemAnimation::translationList() const

   393 {

   394     QList<QPair<qreal, QPointF> > list;

   395     for (int i = 0; i < d->xTranslation.size(); ++i)

   396         list << QPair<qreal, QPointF>(d->xTranslation.at(i).step, QPointF(d->xTranslation.at(i).value, d->yTranslation.at(i).value));

   397     

   398     return list;

   399 }

   400 

   401 /*!

   402   Returns the vertical scale for the item at the specified \a step value.

   403 

   404   \sa setScaleAt()

   405 */

   406 qreal QGraphicsItemAnimation::verticalScaleAt(qreal step) const

   407 {

   408     if (step < 0.0 || step > 1.0)

   409         qWarning("QGraphicsItemAnimation::verticalScaleAt: invalid step = %f", step);

   410 

   411     return d->linearValueForStep(step, &d->verticalScale, 1);

   412 }

   413 

   414 /*!

   415   Returns the horizontal scale for the item at the specified \a step value.

   416 

   417   \sa setScaleAt()

   418 */

   419 qreal QGraphicsItemAnimation::horizontalScaleAt(qreal step) const

   420 {

   421     if (step < 0.0 || step > 1.0)

   422         qWarning("QGraphicsItemAnimation::horizontalScaleAt: invalid step = %f", step);

   423 

   424     return d->linearValueForStep(step, &d->horizontalScale, 1);

   425 }

   426 

   427 /*!

   428   Sets the scale of the item at the given \a step value using the horizontal and

   429   vertical scale factors specified by \a sx and \a sy.

   430 

   431   \sa verticalScaleAt(), horizontalScaleAt()

   432 */

   433 void QGraphicsItemAnimation::setScaleAt(qreal step, qreal sx, qreal sy)

   434 {

   435     d->insertUniquePair(step, sx, &d->horizontalScale, "setScaleAt");

   436     d->insertUniquePair(step, sy, &d->verticalScale, "setScaleAt");

   437 }

   438 

   439 /*!

   440   Returns all explicitly inserted scales.

   441 

   442   \sa verticalScaleAt(), horizontalScaleAt(), setScaleAt()

   443 */

   444 QList<QPair<qreal, QPointF> > QGraphicsItemAnimation::scaleList() const

   445 {

   446     QList<QPair<qreal, QPointF> > list;

   447     for (int i = 0; i < d->horizontalScale.size(); ++i)

   448         list << QPair<qreal, QPointF>(d->horizontalScale.at(i).step, QPointF(d->horizontalScale.at(i).value, d->verticalScale.at(i).value));

   449     

   450     return list;

   451 }

   452 

   453 /*!

   454   Returns the vertical shear for the item at the specified \a step value.

   455 

   456   \sa setShearAt()

   457 */

   458 qreal QGraphicsItemAnimation::verticalShearAt(qreal step) const

   459 {

   460     if (step < 0.0 || step > 1.0)

   461         qWarning("QGraphicsItemAnimation::verticalShearAt: invalid step = %f", step);

   462 

   463     return d->linearValueForStep(step, &d->verticalShear, 0);

   464 }

   465 

   466 /*!

   467   Returns the horizontal shear for the item at the specified \a step value.

   468 

   469   \sa setShearAt()

   470 */

   471 qreal QGraphicsItemAnimation::horizontalShearAt(qreal step) const

   472 {

   473     if (step < 0.0 || step > 1.0)

   474         qWarning("QGraphicsItemAnimation::horizontalShearAt: invalid step = %f", step);

   475 

   476     return d->linearValueForStep(step, &d->horizontalShear, 0);

   477 }

   478 

   479 /*!

   480   Sets the shear of the item at the given \a step value using the horizontal and

   481   vertical shear factors specified by \a sh and \a sv.

   482 

   483   \sa verticalShearAt(), horizontalShearAt()

   484 */

   485 void QGraphicsItemAnimation::setShearAt(qreal step, qreal sh, qreal sv)

   486 {

   487     d->insertUniquePair(step, sh, &d->horizontalShear, "setShearAt");

   488     d->insertUniquePair(step, sv, &d->verticalShear, "setShearAt");

   489 }

   490 

   491 /*!

   492   Returns all explicitly inserted shears.

   493 

   494   \sa verticalShearAt(), horizontalShearAt(), setShearAt()

   495 */

   496 QList<QPair<qreal, QPointF> > QGraphicsItemAnimation::shearList() const

   497 {

   498     QList<QPair<qreal, QPointF> > list;

   499     for (int i = 0; i < d->horizontalShear.size(); ++i)

   500         list << QPair<qreal, QPointF>(d->horizontalShear.at(i).step, QPointF(d->horizontalShear.at(i).value, d->verticalShear.at(i).value));

   501     

   502     return list;

   503 }

   504 

   505 /*!

   506   Clears the scheduled transformations used for the animation, but

   507   retains the item and timeline.

   508 */

   509 void QGraphicsItemAnimation::clear()

   510 {

   511     d->xPosition.clear();

   512     d->yPosition.clear();

   513     d->rotation.clear();

   514     d->verticalScale.clear();

   515     d->horizontalScale.clear();

   516     d->verticalShear.clear();

   517     d->horizontalShear.clear();

   518     d->xTranslation.clear();

   519     d->yTranslation.clear();

   520 }

   521 

   522 /*!

   523   \fn void QGraphicsItemAnimation::setStep(qreal step)

   524 

   525   Sets the current \a step value for the animation, causing the

   526   transformations scheduled at this step to be performed.

   527 */

   528 void QGraphicsItemAnimation::setStep(qreal x)

   529 {

   530     if (x < 0.0 || x > 1.0) {

   531         qWarning("QGraphicsItemAnimation::setStep: invalid step = %f", x);

   532         return;

   533     }

   534 

   535     beforeAnimationStep(x);

   536 

   537     d->step = x;

   538     if (d->item) {

   539         if (!d->xPosition.isEmpty() || !d->yPosition.isEmpty())

   540             d->item->setPos(posAt(x));

   541         if (!d->rotation.isEmpty()

   542             || !d->verticalScale.isEmpty()

   543             || !d->horizontalScale.isEmpty()

   544             || !d->verticalShear.isEmpty()

   545             || !d->horizontalShear.isEmpty()

   546             || !d->xTranslation.isEmpty()

   547             || !d->yTranslation.isEmpty()) {

   548             d->item->setMatrix(d->startMatrix * matrixAt(x));

   549         }

   550     }

   551 

   552     afterAnimationStep(x);

   553 }

   554 

   555 /*!

   556     Resets the item to its starting position and transformation.

   557 

   558     \obsolete

   559 

   560     You can call setStep(0) instead.

   561 */

   562 void QGraphicsItemAnimation::reset()

   563 {

   564     if (!d->item)

   565         return;

   566     d->startPos = d->item->pos();

   567     d->startMatrix = d->item->matrix();

   568 }

   569 

   570 /*!

   571   \fn void QGraphicsItemAnimation::beforeAnimationStep(qreal step)

   572 

   573   This method is meant to be overridden by subclassed that needs to

   574   execute additional code before a new step takes place. The

   575   animation \a step is provided for use in cases where the action

   576   depends on its value.

   577 */

   578 void QGraphicsItemAnimation::beforeAnimationStep(qreal step)

   579 {

   580     Q_UNUSED(step);

   581 }

   582 

   583 /*!

   584   \fn void QGraphicsItemAnimation::afterAnimationStep(qreal step)

   585 

   586   This method is meant to be overridden in subclasses that need to

   587   execute additional code after a new step has taken place. The

   588   animation \a step is provided for use in cases where the action

   589   depends on its value.

   590 */

   591 void QGraphicsItemAnimation::afterAnimationStep(qreal step)

   592 {

   593     Q_UNUSED(step);

   594 }

   595 

   596 QT_END_NAMESPACE

   597 

   598 #endif // QT_NO_GRAPHICSVIEW