qquickboundaryrule.cpp

Go to the documentation of this file.

// Copyright (C) 2019 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
 
#include "qquickboundaryrule_p.h"
 
#include <qqmlcontext.h>
#include <qqmlinfo.h>
#include <private/qqmlproperty_p.h>
#include <private/qqmlengine_p.h>
#include <private/qobject_p.h>
#include <private/qquickanimation_p_p.h>
#include <QtCore/qloggingcategory.h>
 
QT_BEGIN_NAMESPACE
 
Q_STATIC_LOGGING_CATEGORY(lcBR, "qt.quick.boundaryrule")
 
class QQuickBoundaryReturnJob;
class QQuickBoundaryRulePrivate : public QObjectPrivate
{
    Q_DECLARE_PUBLIC(QQuickBoundaryRule)
public:
    QQuickBoundaryRulePrivate() {}
 
    QQmlProperty property;
    QEasingCurve easing = QEasingCurve(QEasingCurve::OutQuad);
    QQuickBoundaryReturnJob *returnAnimationJob = nullptr;
    // read-only properties, updated on each write()
    qreal targetValue = 0; // after easing was applied
    qreal peakOvershoot = 0;
    qreal currentOvershoot = 0;
    // settable properties
    qreal minimum = 0;
    qreal maximum = 0;
    qreal minimumOvershoot = 0;
    qreal maximumOvershoot = 0;
    qreal overshootScale = 0.5;
    int returnDuration = 100;
    QQuickBoundaryRule::OvershootFilter overshootFilter = QQuickBoundaryRule::OvershootFilter::None;
    bool enabled = true;
    bool completed = false;
 
    qreal easedOvershoot(qreal overshootingValue);
    void resetOvershoot();
    void onAnimationEnded();
};
 
class QQuickBoundaryReturnJob : public QAbstractAnimationJob
{
public:
    QQuickBoundaryReturnJob(QQuickBoundaryRulePrivate *br, qreal to)
        : QAbstractAnimationJob()
        , boundaryRule(br)
        , fromValue(br->targetValue)
        , toValue(to) {}
 
    int duration() const override { return boundaryRule->returnDuration; }
 
    void updateCurrentTime(int) override;
 
    void updateState(QAbstractAnimationJob::State newState,
                     QAbstractAnimationJob::State oldState) override;
 
    QQuickBoundaryRulePrivate *boundaryRule;
    qreal fromValue;    // snapshot of initial value from which we're returning
    qreal toValue;      // target property value to which we're returning
};
 
void QQuickBoundaryReturnJob::updateCurrentTime(int t)
{
    // The easing property tells how to behave when the property is being
    // externally manipulated beyond the bounds.  During returnToBounds()
    // we run it in reverse, by reversing time.
    qreal progress = (duration() - t) / qreal(duration());
    qreal easingValue = boundaryRule->easing.valueForProgress(progress);
    qreal delta = qAbs(fromValue - toValue) * easingValue;
    qreal value = (fromValue > toValue ? toValue + delta : toValue - delta);
    qCDebug(lcBR) << t << "ms" << qRound(progress * 100) << "% easing" << easingValue << "->" << value;
    QQmlPropertyPrivate::write(boundaryRule->property, value,
                               QQmlPropertyData::BypassInterceptor | QQmlPropertyData::DontRemoveBinding);
}
 
void QQuickBoundaryReturnJob::updateState(QAbstractAnimationJob::State newState, QAbstractAnimationJob::State oldState)
{
    Q_UNUSED(oldState);
    if (newState == QAbstractAnimationJob::Stopped) {
        qCDebug(lcBR) << "return animation done";
        boundaryRule->resetOvershoot();
        boundaryRule->onAnimationEnded();
    }
}
 
/*!
    \qmltype BoundaryRule
//!    \nativetype QQuickBoundaryRule
    \inqmlmodule Qt.labs.animation
    \ingroup qtquick-transitions-animations
    \ingroup qtquick-interceptors
    \brief Defines a restriction on the range of values that can be set on a numeric property.
    \since 5.14
 
    A BoundaryRule defines the range of values that a particular property is
    allowed to have.  When an out-of-range value would otherwise be set,
    it applies "resistance" via an easing curve.
 
    For example, the following BoundaryRule prevents DragHandler from dragging
    the Rectangle too far:
 
    \snippet qml/boundaryRule.qml 0
 
    Note that a property cannot have more than one assigned BoundaryRule.
 
    \sa {Animation and Transitions in Qt Quick}, {Qt Quick Examples - Animation#Behaviors}{Behavior
example}, {Qt Qml}, {Qt Quick Examples - Pointer Handlers}
*/
 
QQuickBoundaryRule::QQuickBoundaryRule(QObject *parent)
    : QObject(*(new QQuickBoundaryRulePrivate), parent)
    , QQmlPropertyValueInterceptor()
{
}
 
QQuickBoundaryRule::~QQuickBoundaryRule()
{
    Q_D(QQuickBoundaryRule);
    // stop any running animation and
    // prevent QQuickBoundaryReturnJob::updateState() from accessing QQuickBoundaryRulePrivate
    delete d->returnAnimationJob;
}
 
/*!
    \qmlproperty bool Qt.labs.animation::BoundaryRule::enabled
 
    This property holds whether the rule will be enforced when the tracked
    property changes value.
 
    By default a BoundaryRule is enabled.
*/
bool QQuickBoundaryRule::enabled() const
{
    Q_D(const QQuickBoundaryRule);
    return d->enabled;
}
 
void QQuickBoundaryRule::setEnabled(bool enabled)
{
    Q_D(QQuickBoundaryRule);
    if (d->enabled == enabled)
        return;
    d->enabled = enabled;
    emit enabledChanged();
}
 
/*!
    \qmlproperty real Qt.labs.animation::BoundaryRule::minimum
 
    This property holds the smallest unconstrained value that the property is
    allowed to have.  If the property is set to a smaller value, it will be
    constrained by \l easing and \l minimumOvershoot.
 
    The default is \c 0.
*/
qreal QQuickBoundaryRule::minimum() const
{
    Q_D(const QQuickBoundaryRule);
    return d->minimum;
}
 
void QQuickBoundaryRule::setMinimum(qreal minimum)
{
    Q_D(QQuickBoundaryRule);
    if (qFuzzyCompare(d->minimum, minimum))
        return;
    d->minimum = minimum;
    emit minimumChanged();
}
 
/*!
    \qmlproperty real Qt.labs.animation::BoundaryRule::minimumOvershoot
 
    This property holds the amount that the property is allowed to be
    less than \l minimum.  Whenever the value is less than \l minimum
    and greater than \c {minimum - minimumOvershoot}, it is constrained
    by the \l easing curve.  When the value attempts to go under
    \c {minimum - minimumOvershoots} there is a hard stop.
 
    The default is \c 0.
*/
qreal QQuickBoundaryRule::minimumOvershoot() const
{
    Q_D(const QQuickBoundaryRule);
    return d->minimumOvershoot;
}
 
void QQuickBoundaryRule::setMinimumOvershoot(qreal minimumOvershoot)
{
    Q_D(QQuickBoundaryRule);
    if (qFuzzyCompare(d->minimumOvershoot, minimumOvershoot))
        return;
    d->minimumOvershoot = minimumOvershoot;
    emit minimumOvershootChanged();
}
 
/*!
    \qmlproperty real Qt.labs.animation::BoundaryRule::maximum
 
    This property holds the largest unconstrained value that the property is
    allowed to have.  If the property is set to a larger value, it will be
    constrained by \l easing and \l maximumOvershoot.
 
    The default is \c 1.
*/
qreal QQuickBoundaryRule::maximum() const
{
    Q_D(const QQuickBoundaryRule);
    return d->maximum;
}
 
void QQuickBoundaryRule::setMaximum(qreal maximum)
{
    Q_D(QQuickBoundaryRule);
    if (qFuzzyCompare(d->maximum, maximum))
        return;
    d->maximum = maximum;
    emit maximumChanged();
}
 
/*!
    \qmlproperty real Qt.labs.animation::BoundaryRule::maximumOvershoot
 
    This property holds the amount that the property is allowed to be
    more than \l maximum.  Whenever the value is greater than \l maximum
    and less than \c {maximum + maximumOvershoot}, it is constrained
    by the \l easing curve.  When the value attempts to exceed
    \c {maximum + maximumOvershoot} there is a hard stop.
 
    The default is 0.
*/
qreal QQuickBoundaryRule::maximumOvershoot() const
{
    Q_D(const QQuickBoundaryRule);
    return d->maximumOvershoot;
}
 
void QQuickBoundaryRule::setMaximumOvershoot(qreal maximumOvershoot)
{
    Q_D(QQuickBoundaryRule);
    if (qFuzzyCompare(d->maximumOvershoot, maximumOvershoot))
        return;
    d->maximumOvershoot = maximumOvershoot;
    emit maximumOvershootChanged();
}
 
/*!
    \qmlproperty real Qt.labs.animation::BoundaryRule::overshootScale
 
    This property holds the amount by which the \l easing is scaled during the
    overshoot condition. For example if an Item is restricted from moving more
    than 100 pixels beyond some limit, and the user (by means of some Input
    Handler) is trying to drag it 100 pixels past the limit, if overshootScale
    is set to 1, the user will succeed: the only effect of the easing curve is
    to change the rate at which the item moves from overshoot 0 to overshoot
    100. But if it is set to 0.5, the BoundaryRule provides resistance such
    that when the user tries to move 100 pixels, the Item will only move 50
    pixels; and the easing curve modulates the rate of movement such that it
    may move in sync with the user's attempted movement at the beginning, and
    then slows down, depending on the shape of the easing curve.
 
    The default is 0.5.
*/
qreal QQuickBoundaryRule::overshootScale() const
{
    Q_D(const QQuickBoundaryRule);
    return d->overshootScale;
}
 
void QQuickBoundaryRule::setOvershootScale(qreal overshootScale)
{
    Q_D(QQuickBoundaryRule);
    if (qFuzzyCompare(d->overshootScale, overshootScale))
        return;
    d->overshootScale = overshootScale;
    emit overshootScaleChanged();
}
 
/*!
    \qmlproperty real Qt.labs.animation::BoundaryRule::currentOvershoot
 
    This property holds the amount by which the most recently set value of the
    intercepted property exceeds \l maximum or is less than \l minimum.
 
    It is positive if the property value exceeds \l maximum, negative if the
    property value is less than \l minimum, or 0 if the property value is
    within both boundaries.
*/
qreal QQuickBoundaryRule::currentOvershoot() const
{
    Q_D(const QQuickBoundaryRule);
    return d->currentOvershoot;
}
 
/*!
    \qmlproperty real Qt.labs.animation::BoundaryRule::peakOvershoot
 
    This property holds the most-positive or most-negative value of
    \l currentOvershoot that has been seen, until \l returnToBounds() is called.
 
    This can be useful when the intercepted property value is known to
    fluctuate, and you want to find and react to the maximum amount of
    overshoot rather than to the fluctuations.
 
    \sa overshootFilter
*/
qreal QQuickBoundaryRule::peakOvershoot() const
{
    Q_D(const QQuickBoundaryRule);
    return d->peakOvershoot;
}
 
/*!
    \qmlproperty enumeration Qt.labs.animation::BoundaryRule::overshootFilter
 
    This property specifies the aggregation function that will be applied to
    the intercepted property value.
 
    If this is set to \c BoundaryRule.None (the default), the intercepted
    property will hold a value whose overshoot is limited to \l currentOvershoot.
    If this is set to \c BoundaryRule.Peak, the intercepted property will hold
    a value whose overshoot is limited to \l peakOvershoot.
*/
QQuickBoundaryRule::OvershootFilter QQuickBoundaryRule::overshootFilter() const
{
    Q_D(const QQuickBoundaryRule);
    return d->overshootFilter;
}
 
void QQuickBoundaryRule::setOvershootFilter(OvershootFilter overshootFilter)
{
    Q_D(QQuickBoundaryRule);
    if (d->overshootFilter == overshootFilter)
        return;
    d->overshootFilter = overshootFilter;
    emit overshootFilterChanged();
}
 
/*!
    \qmlmethod bool Qt.labs.animation::BoundaryRule::returnToBounds
 
    Returns the intercepted property to a value between \l minimum and
    \l maximum, such that \l currentOvershoot and \l peakOvershoot are both
    zero. This will be animated if \l returnDuration is greater than zero.
 
    Returns true if the value needed to be adjusted, or false if it was already
    within bounds.
 
    \sa returnedToBounds
*/
bool QQuickBoundaryRule::returnToBounds()
{
    Q_D(QQuickBoundaryRule);
    if (d->returnAnimationJob) {
        qCDebug(lcBR) << "animation already in progress";
        return true;
    }
    if (currentOvershoot() > 0) {
        if (d->returnDuration > 0)
            d->returnAnimationJob = new QQuickBoundaryReturnJob(d, maximum());
        else
            write(maximum());
    } else if (currentOvershoot() < 0) {
        if (d->returnDuration > 0)
            d->returnAnimationJob = new QQuickBoundaryReturnJob(d, minimum());
        else
            write(minimum());
    } else {
        return false;
    }
    if (d->returnAnimationJob) {
        qCDebug(lcBR) << d->property.name() << "on" << d->property.object()
                      << ": animating from" << d->returnAnimationJob->fromValue << "to" << d->returnAnimationJob->toValue;
        d->returnAnimationJob->start();
    } else {
        d->resetOvershoot();
        qCDebug(lcBR) << d->property.name() << "on" << d->property.object() << ": returned to" << d->property.read();
        emit returnedToBounds();
    }
    return true;
}
 
/*!
    \qmlsignal Qt.labs.animation::BoundaryRule::returnedToBounds()
 
    This signal is emitted when \l currentOvershoot returns to \c 0 again,
    after the \l maximum or \l minimum constraint has been violated.
    If the return is animated, the signal is emitted when the animation
    completes.
 
    \sa returnDuration, returnToBounds()
*/
 
/*!
    \qmlproperty enumeration Qt.labs.animation::BoundaryRule::easing
 
    This property holds the easing curve to be applied in overshoot mode
    (whenever the \l minimum or \l maximum constraint is violated, while
    the value is still within the respective overshoot range).
 
    The default easing curve is \l QEasingCurve::OutQuad.
*/
QEasingCurve QQuickBoundaryRule::easing() const
{
    Q_D(const QQuickBoundaryRule);
    return d->easing;
}
 
void QQuickBoundaryRule::setEasing(const QEasingCurve &easing)
{
    Q_D(QQuickBoundaryRule);
    if (d->easing == easing)
        return;
    d->easing = easing;
    emit easingChanged();
}
 
/*!
    \qmlproperty int Qt.labs.animation::BoundaryRule::returnDuration
 
    This property holds the amount of time in milliseconds that
    \l returnToBounds() will take to return the target property to the nearest bound.
    If it is set to 0, returnToBounds() will set the property immediately
    rather than creating an animation job.
 
    The default is 100 ms.
*/
int QQuickBoundaryRule::returnDuration() const
{
    Q_D(const QQuickBoundaryRule);
    return d->returnDuration;
}
 
void QQuickBoundaryRule::setReturnDuration(int duration)
{
    Q_D(QQuickBoundaryRule);
    if (d->returnDuration == duration)
        return;
    d->returnDuration = duration;
    emit returnDurationChanged();
}
 
void QQuickBoundaryRule::classBegin()
{
 
}
 
void QQuickBoundaryRule::componentComplete()
{
    Q_D(QQuickBoundaryRule);
    d->completed = true;
}
 
void QQuickBoundaryRule::write(const QVariant &value)
{
    bool conversionOk = false;
    qreal rValue = value.toReal(&conversionOk);
    if (!conversionOk) {
        qWarning() << "BoundaryRule doesn't work with non-numeric values:" << value;
        return;
    }
    Q_D(QQuickBoundaryRule);
    bool bypass = !d->enabled || !d->completed || QQmlEnginePrivate::designerMode();
    if (bypass) {
        QQmlPropertyPrivate::write(d->property, value,
                                   QQmlPropertyData::BypassInterceptor | QQmlPropertyData::DontRemoveBinding);
        return;
    }
 
    d->targetValue = d->easedOvershoot(rValue);
    QQmlPropertyPrivate::write(d->property, d->targetValue,
                               QQmlPropertyData::BypassInterceptor | QQmlPropertyData::DontRemoveBinding);
}
 
void QQuickBoundaryRule::setTarget(const QQmlProperty &property)
{
    Q_D(QQuickBoundaryRule);
    d->property = property;
}
 
/*!
    \internal
    Given that something is trying to set the target property to \a value,
    this function applies the easing curve and returns the value that the
    property should actually get instead.
*/
qreal QQuickBoundaryRulePrivate::easedOvershoot(qreal value)
{
    qreal ret = value;
    Q_Q(QQuickBoundaryRule);
    if (value > maximum) {
        qreal overshootWas = currentOvershoot;
        currentOvershoot = value - maximum;
        if (!qFuzzyCompare(overshootWas, currentOvershoot))
            emit q->currentOvershootChanged();
        overshootWas = peakOvershoot;
        peakOvershoot = qMax(currentOvershoot, peakOvershoot);
        if (!qFuzzyCompare(overshootWas, peakOvershoot))
            emit q->peakOvershootChanged();
        ret = maximum + maximumOvershoot * easing.valueForProgress(
                    (overshootFilter == QQuickBoundaryRule::OvershootFilter::Peak ? peakOvershoot : currentOvershoot)
                    * overshootScale / maximumOvershoot);
        qCDebug(lcBR).nospace() << value << " overshoots maximum " << maximum << " by "
                                << currentOvershoot << " (peak " << peakOvershoot << "): eased to " << ret;
    } else if (value < minimum) {
        qreal overshootWas = currentOvershoot;
        currentOvershoot = value - minimum;
        if (!qFuzzyCompare(overshootWas, currentOvershoot))
            emit q->currentOvershootChanged();
        overshootWas = peakOvershoot;
        peakOvershoot = qMin(currentOvershoot, peakOvershoot);
        if (!qFuzzyCompare(overshootWas, peakOvershoot))
            emit q->peakOvershootChanged();
        ret = minimum - minimumOvershoot * easing.valueForProgress(
                    -(overshootFilter == QQuickBoundaryRule::OvershootFilter::Peak ? peakOvershoot : currentOvershoot)
                    * overshootScale / minimumOvershoot);
        qCDebug(lcBR).nospace() << value << " overshoots minimum " << minimum << " by "
                                << currentOvershoot << " (peak " << peakOvershoot << "): eased to " << ret;
    } else {
        resetOvershoot();
    }
    return ret;
}
 
/*!
    \internal
    Resets the currentOvershoot and peakOvershoot
    properties to zero.
*/
void QQuickBoundaryRulePrivate::resetOvershoot()
{
    Q_Q(QQuickBoundaryRule);
    if (!qFuzzyCompare(peakOvershoot, 0)) {
        peakOvershoot = 0;
        emit q->peakOvershootChanged();
    }
    if (!qFuzzyCompare(currentOvershoot, 0)) {
        currentOvershoot = 0;
        emit q->currentOvershootChanged();
    }
}
 
void QQuickBoundaryRulePrivate::onAnimationEnded()
{
    Q_Q(QQuickBoundaryRule);
    delete returnAnimationJob;
    returnAnimationJob = nullptr;
    emit q->returnedToBounds();
}
 
QT_END_NAMESPACE
 
#include "moc_qquickboundaryrule_p.cpp"