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

     2 **

     3 ** Copyright (C) 2010 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 QtDeclarative 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 #include "qdeclarativesmoothedfollow_p.h"

    43 #include "qdeclarativesmoothedanimation_p_p.h"

    44 

    45 #include <private/qobject_p.h>

    46 #include <QtCore/qnumeric.h>

    47 

    48 #include "qdeclarativeglobal_p.h"

    49 

    50 

    51 QT_BEGIN_NAMESPACE

    52 

    53 class QDeclarativeSmoothedFollowPrivate : public QObjectPrivate

    54 {

    55     Q_DECLARE_PUBLIC(QDeclarativeSmoothedFollow)

    56 public:

    57     QDeclarativeSmoothedFollowPrivate();

    58 

    59     bool enabled;

    60     QSmoothedAnimation *anim;

    61 };

    62 

    63 /*!

    64     \qmlclass SmoothedFollow QDeclarativeSmoothedFollow

    65     \since 4.7

    66     \inherits NumberAnimation

    67     \brief The SmoothedFollow element allows a property to smoothly track a value.

    68 

    69     The SmoothedFollow animates a property's value to a set target value

    70     using an ease in/out quad easing curve.  If the animation is restarted

    71     with a different target value, the easing curves used to animate to the old

    72     and the new target values are smoothly spliced together to avoid any obvious

    73     visual glitches by maintaining the current velocity.

    74 

    75     The property animation is configured by setting the velocity at which the

    76     animation should occur, or the duration that the animation should take.

    77     If both a velocity and a duration are specified, the one that results in

    78     the quickest animation is chosen for each change in the target value.

    79 

    80     For example, animating from 0 to 800 will take 4 seconds if a velocity

    81     of 200 is set, will take 8 seconds with a duration of 8000 set, and will

    82     take 4 seconds with both a velocity of 200 and a duration of 8000 set.

    83     Animating from 0 to 20000 will take 10 seconds if a velocity of 200 is set,

    84     will take 8 seconds with a duration of 8000 set, and will take 8 seconds

    85     with both a velocity of 200 and a duration of 8000 set.

    86 

    87     The follow example shows one rectangle tracking the position of another.

    88 \code

    89 import Qt 4.7

    90 

    91 Rectangle {

    92     width: 800; height: 600; color: "blue"

    93 

    94     Rectangle {

    95         color: "green"

    96         width: 60; height: 60;

    97         SmoothedFollow on x { to: rect1.x - 5; velocity: 200 }

    98         SmoothedFollow on y { to: rect1.y - 5; velocity: 200 }

    99     }

   100 

   101     Rectangle {

   102         id: rect1

   103         color: "red"

   104         width: 50; height: 50;

   105     }

   106 

   107     focus: true

   108     Keys.onRightPressed: rect1.x = rect1.x + 100

   109     Keys.onLeftPressed: rect1.x = rect1.x - 100

   110     Keys.onUpPressed: rect1.y = rect1.y - 100

   111     Keys.onDownPressed: rect1.y = rect1.y + 100

   112 }

   113 \endcode

   114 

   115     The default velocity of SmoothedFollow is 200 units/second.  Note that if the range of the

   116     value being animated is small, then the velocity will need to be adjusted

   117     appropriately.  For example, the opacity of an item ranges from 0 - 1.0.

   118     To enable a smooth animation in this range the velocity will need to be

   119     set to a value such as 0.5 units/second.  Animating from 0 to 1.0 with a velocity

   120     of 0.5 will take 2000 ms to complete.

   121 

   122     \sa SpringFollow

   123 */

   124 

   125 QDeclarativeSmoothedFollow::QDeclarativeSmoothedFollow(QObject *parent)

   126     : QObject(*(new QDeclarativeSmoothedFollowPrivate), parent)

   127 {

   128 }

   129 

   130 QDeclarativeSmoothedFollow::~QDeclarativeSmoothedFollow()

   131 {

   132 }

   133 

   134 QDeclarativeSmoothedFollowPrivate::QDeclarativeSmoothedFollowPrivate()

   135     : enabled(true), anim(new QSmoothedAnimation)

   136 {

   137     Q_Q(QDeclarativeSmoothedFollow);

   138     QDeclarative_setParent_noEvent(anim, q);

   139 }

   140 

   141 /*!

   142     \qmlproperty enumeration SmoothedFollow::reversingMode

   143 

   144     Sets how the SmoothedFollow behaves if an animation direction is reversed.

   145 

   146     If reversing mode is \c SmoothedFollow.Eased, the animation will smoothly decelerate, and

   147     then reverse direction.  If the reversing mode is \c SmoothedFollow.Immediate, the

   148     animation will immediately begin accelerating in the reverse direction,

   149     begining with a velocity of 0.  If the reversing mode is \c SmoothedFollow.Sync, the

   150     property is immediately set to the target value.

   151 */

   152 QDeclarativeSmoothedFollow::ReversingMode QDeclarativeSmoothedFollow::reversingMode() const

   153 {

   154     Q_D(const QDeclarativeSmoothedFollow);

   155     return (ReversingMode) d->anim->reversingMode;

   156 }

   157 

   158 void QDeclarativeSmoothedFollow::setReversingMode(ReversingMode m)

   159 {

   160     Q_D(QDeclarativeSmoothedFollow);

   161     if (d->anim->reversingMode == (QDeclarativeSmoothedAnimation::ReversingMode) m)

   162         return;

   163 

   164     d->anim->reversingMode = (QDeclarativeSmoothedAnimation::ReversingMode) m;

   165     emit reversingModeChanged();

   166 }

   167 

   168 /*!

   169     \qmlproperty int SmoothedFollow::duration

   170 

   171     This property holds the animation duration, in msecs, used when tracking the source.

   172 

   173     Setting this to -1 (the default) disables the duration value.

   174 */

   175 int QDeclarativeSmoothedFollow::duration() const

   176 {

   177     Q_D(const QDeclarativeSmoothedFollow);

   178     return d->anim->userDuration;

   179 }

   180 

   181 void QDeclarativeSmoothedFollow::setDuration(int duration)

   182 {

   183     Q_D(QDeclarativeSmoothedFollow);

   184     if (duration == d->anim->duration())

   185         return;

   186 

   187     d->anim->userDuration = duration;

   188     emit durationChanged();

   189 }

   190 

   191 qreal QDeclarativeSmoothedFollow::velocity() const

   192 {

   193     Q_D(const QDeclarativeSmoothedFollow);

   194     return d->anim->velocity;

   195 }

   196 

   197 /*!

   198     \qmlproperty real SmoothedFollow::velocity

   199 

   200     This property holds the average velocity allowed when tracking the 'to' value.

   201 

   202     The default velocity of SmoothedFollow is 200 units/second.

   203 

   204     Setting this to -1 disables the velocity value.

   205 */

   206 void QDeclarativeSmoothedFollow::setVelocity(qreal v)

   207 {

   208     Q_D(QDeclarativeSmoothedFollow);

   209     if (d->anim->velocity == v)

   210         return;

   211 

   212     d->anim->velocity = v;

   213     emit velocityChanged();

   214 }

   215 

   216 /*!

   217     \qmlproperty int SmoothedFollow::maximumEasingTime

   218 

   219     This property specifies the maximum time, in msecs, an "eases" during the follow should take.

   220     Setting this property causes the velocity to "level out" after at a time.  Setting

   221     a negative value reverts to the normal mode of easing over the entire animation

   222     duration.

   223 

   224     The default value is -1.

   225 */

   226 int QDeclarativeSmoothedFollow::maximumEasingTime() const

   227 {

   228     Q_D(const QDeclarativeSmoothedFollow);

   229     return d->anim->maximumEasingTime;

   230 }

   231 

   232 void QDeclarativeSmoothedFollow::setMaximumEasingTime(int v)

   233 {

   234     Q_D(QDeclarativeSmoothedFollow);

   235     d->anim->maximumEasingTime = v;

   236     emit maximumEasingTimeChanged();

   237 }

   238 

   239 /*!

   240     \qmlproperty real SmoothedFollow::to

   241     This property holds the ending value.

   242     If not set, then the value defined in the end state of the transition or Behavior.

   243 */

   244 qreal QDeclarativeSmoothedFollow::to() const

   245 {

   246     Q_D(const QDeclarativeSmoothedFollow);

   247     return d->anim->to;

   248 }

   249 

   250 void QDeclarativeSmoothedFollow::setTo(qreal t)

   251 {

   252     Q_D(QDeclarativeSmoothedFollow);

   253 

   254     if (qIsNaN(t))

   255         return;

   256 

   257     if (d->anim->to == t)

   258         return;

   259 

   260     d->anim->to = t;

   261 

   262     if (d->enabled)

   263         d->anim->restart();

   264 }

   265 

   266 /*!

   267     \qmlproperty bool SmoothedFollow::enabled

   268     This property whether this animation should automatically restart when

   269     the 'to' property is upated.

   270 

   271     The default value of this property is 'true'.

   272 */

   273 bool QDeclarativeSmoothedFollow::enabled() const

   274 {

   275     Q_D(const QDeclarativeSmoothedFollow);

   276     return d->enabled;

   277 }

   278 

   279 void QDeclarativeSmoothedFollow::setEnabled(bool e)

   280 {

   281     Q_D(QDeclarativeSmoothedFollow);

   282     if (d->enabled == e)

   283         return;

   284     d->enabled = e;

   285 

   286     if (d->enabled)

   287         d->anim->restart();

   288     else

   289         d->anim->stop();

   290     emit enabledChanged();

   291 }

   292 

   293 void QDeclarativeSmoothedFollow::setTarget(const QDeclarativeProperty &t)

   294 {

   295     Q_D(QDeclarativeSmoothedFollow);

   296     d->anim->target = t;

   297 }

   298 

   299 QT_END_NAMESPACE