diff options
Diffstat (limited to 'src/quick/util/qquickboundaryrule.cpp')
-rw-r--r-- | src/quick/util/qquickboundaryrule.cpp | 574 |
1 files changed, 574 insertions, 0 deletions
diff --git a/src/quick/util/qquickboundaryrule.cpp b/src/quick/util/qquickboundaryrule.cpp new file mode 100644 index 0000000000..3558c8bfa0 --- /dev/null +++ b/src/quick/util/qquickboundaryrule.cpp @@ -0,0 +1,574 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtQuick module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#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_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 finalized = false; + + qreal easedOvershoot(qreal overshootingValue); + void resetOvershoot(); +}; + +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->returnAnimationJob = nullptr; + delete this; + } +} + +/*! + \qmltype BoundaryRule + \instantiates 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} +*/ + +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 QtQuick::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 qreal QtQuick::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 qreal QtQuick::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 qreal QtQuick::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 qreal QtQuick::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 qreal QtQuick::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 qreal QtQuick::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 qreal QtQuick::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 enum QtQuick::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 QtQuick::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. +*/ +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) << "animating from" << d->returnAnimationJob->fromValue << "to" << d->returnAnimationJob->toValue; + d->returnAnimationJob->start(); + } else { + d->resetOvershoot(); + qCDebug(lcBR) << "returned to" << d->property.read(); + } + return true; +} + +/*! + \qmlproperty qreal QtQuick::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 QtQuick::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::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->finalized || QQmlEnginePrivate::designerMode(); + if (bypass) { + QQmlPropertyPrivate::write(d->property, value, + QQmlPropertyData::BypassInterceptor | QQmlPropertyData::DontRemoveBinding); + return; + } + + qmlExecuteDeferred(this); + 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; + + QQmlEnginePrivate *engPriv = QQmlEnginePrivate::get(qmlEngine(this)); + static int finalizedIdx = -1; + if (finalizedIdx < 0) + finalizedIdx = metaObject()->indexOfSlot("componentFinalized()"); + engPriv->registerFinalizeCallback(this, finalizedIdx); +} + +void QQuickBoundaryRule::componentFinalized() +{ + Q_D(QQuickBoundaryRule); + d->finalized = true; +} + +/*! + \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(); + } +} + +QT_END_NAMESPACE + +#include "moc_qquickboundaryrule_p.cpp" |