qquickdial.cpp

Go to the documentation of this file.

// Copyright (C) 2017 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
 
#include "qquickdial_p.h"
#include "qquickdeferredexecute_p_p.h"
 
#include <QtCore/qmath.h>
#include <QtQuick/private/qquickflickable_p.h>
#include <QtQuickTemplates2/private/qquickcontrol_p_p.h>
 
#include <cmath>
 
QT_BEGIN_NAMESPACE
 
 
// The user angle is the clockwise angle between the position and the vertical
// y-axis (12 o clock position).
// Using radians for logic (atan2(...)) and degree for user interface
constexpr qreal toUserAngleDeg(qreal logicAngleRad) {
    // minus to turn clockwise, add 90 deg clockwise
    return -logicAngleRad / M_PI * 180. + 90;
}
 
static const qreal defaultStartAngle = -140;
static const qreal defaultEndAngle = 140;
 
class QQuickDialPrivate : public QQuickControlPrivate
{
    Q_DECLARE_PUBLIC(QQuickDial)
 
public:
    qreal valueAt(qreal position) const;
    qreal snapPosition(qreal position) const;
    qreal positionAt(const QPointF &point) const;
    qreal circularPositionAt(const QPointF &point) const;
    qreal linearPositionAt(const QPointF &point) const;
    void setPosition(qreal position);
    void updatePosition();
    bool isLargeChange(qreal proposedPosition) const;
    bool isHorizontalOrVertical() const;
 
    bool handlePress(const QPointF &point, ulong timestamp) override;
    bool handleMove(const QPointF &point, ulong timestamp) override;
    bool handleRelease(const QPointF &point, ulong timestamp) override;
    void handleUngrab() override;
 
    void cancelHandle();
    void executeHandle(bool complete = false);
 
    void updateAllValuesAreInteger();
 
    void maybeEmitWrapAround(qreal pos);
 
    qreal from = 0;
    qreal to = 1;
    qreal value = 0;
    qreal position = 0;
    qreal startAngle = defaultStartAngle;
    qreal endAngle = defaultEndAngle;
    qreal angle = startAngle;
    qreal stepSize = 0;
    QPointF pressPoint;
    qreal positionBeforePress = 0;
    QQuickDial::SnapMode snapMode = QQuickDial::NoSnap;
    QQuickDial::InputMode inputMode = QQuickDial::Circular;
    QQuickDeferredPointer<QQuickItem> handle;
    bool wrap = false;
    bool live = true;
    bool pressed = false;
    bool allValuesAreInteger = false;
};
 
qreal QQuickDialPrivate::valueAt(qreal position) const
{
    qreal value = from + (to - from) * position;
 
    /* play nice with users expecting that integer from, to and stepSize leads to
       integer values - given that we are using floating point internally (and in
       the API of value), this does not hold, but it is easy enough to handle
    */
    if (allValuesAreInteger)
        value = qRound(value);
 
    return value;
}
 
qreal QQuickDialPrivate::snapPosition(qreal position) const
{
    const qreal range = to - from;
    if (qFuzzyIsNull(range))
        return position;
 
    const qreal effectiveStep = stepSize / range;
    if (qFuzzyIsNull(effectiveStep))
        return position;
 
    return qRound(position / effectiveStep) * effectiveStep;
}
 
qreal QQuickDialPrivate::positionAt(const QPointF &point) const
{
    return inputMode == QQuickDial::Circular ? circularPositionAt(point) : linearPositionAt(point);
}
 
qreal QQuickDialPrivate::circularPositionAt(const QPointF &point) const
{
    qreal yy = height / 2.0 - point.y();
    qreal xx = point.x() - width / 2.0;
    qreal alpha = (xx || yy) ? toUserAngleDeg(std::atan2(yy, xx)) : 0;
 
    // Move around the circle to reach the interval.
    if (alpha < startAngle && alpha + 360. < endAngle)
        alpha += 360.;
    else if (alpha >= endAngle && alpha - 360. >= startAngle)
        alpha -= 360.;
 
    // If wrap is on and we are out of the interval [startAngle, endAngle],
    // we want to jump to the closest border to make it feel nice and responsive
    if ((alpha < startAngle || alpha > endAngle) && wrap) {
        if (abs(alpha - startAngle) > abs(endAngle - alpha - 360.))
            alpha += 360.;
        else if (abs(alpha - startAngle - 360.) < abs(endAngle - alpha))
            alpha -= 360.;
    }
 
    // If wrap is off,
    // we want to stay as close as possible to the current angle.
    // This is important to allow easy setting of boundary values (0,1)
    if (!wrap) {
        if (abs(angle - alpha) > abs(angle - (alpha + 360.)))
            alpha += 360.;
        if (abs(angle - alpha) > abs(angle - (alpha - 360.)))
            alpha -= 360.;
    }
 
    return (alpha - startAngle) / (endAngle - startAngle);
}
 
qreal QQuickDialPrivate::linearPositionAt(const QPointF &point) const
{
    // This value determines the range (either horizontal or vertical)
    // within which the dial can be dragged.
    // The larger this value is, the further the drag distance
    // must be to go from a position of e.g. 0.0 to 1.0.
    qreal dragArea = 0;
 
    // The linear input mode uses a "relative" input system,
    // where the distance from the press point is used to calculate
    // the change in position. Moving the mouse above the press
    // point increases the position (when inputMode is Vertical),
    // and vice versa. This prevents the dial from jumping when clicked.
    qreal dragDistance = 0;
 
    if (inputMode == QQuickDial::Horizontal) {
        dragArea = width * 2;
        dragDistance = pressPoint.x() - point.x();
    } else {
        dragArea = height * 2;
        dragDistance = point.y() - pressPoint.y();
    }
    const qreal normalisedDifference = dragDistance / dragArea;
    return qBound(qreal(0), positionBeforePress - normalisedDifference, qreal(1));
}
 
void QQuickDialPrivate::setPosition(qreal pos)
{
    Q_Q(QQuickDial);
    pos = qBound<qreal>(qreal(0), pos, qreal(1));
    const qreal alpha = startAngle + pos * qAbs(endAngle - startAngle);
    if (qFuzzyCompare(position, pos) && qFuzzyCompare(angle, alpha))
        return;
 
    angle = alpha;
    position = pos;
 
 
    emit q->positionChanged();
    emit q->angleChanged();
}
 
void QQuickDialPrivate::updatePosition()
{
    qreal pos = 0;
    if (!qFuzzyCompare(from, to))
        pos = (value - from) / (to - from);
    setPosition(pos);
}
 
bool QQuickDialPrivate::isLargeChange(qreal proposedPosition) const
{
    if (endAngle - startAngle < 180.0)
        return false;
    return qAbs(proposedPosition - position) > qreal(0.5);
}
 
bool QQuickDialPrivate::isHorizontalOrVertical() const
{
    return inputMode == QQuickDial::Horizontal || inputMode == QQuickDial::Vertical;
}
 
bool QQuickDialPrivate::handlePress(const QPointF &point, ulong timestamp)
{
    Q_Q(QQuickDial);
    QQuickControlPrivate::handlePress(point, timestamp);
    pressPoint = point;
    positionBeforePress = position;
    q->setPressed(true);
    return true;
}
 
bool QQuickDialPrivate::handleMove(const QPointF &point, ulong timestamp)
{
    Q_Q(QQuickDial);
    QQuickControlPrivate::handleMove(point, timestamp);
    const qreal oldPos = position;
    qreal pos = qBound(0.0, positionAt(point), 1.0);
    if (snapMode == QQuickDial::SnapAlways)
        pos = snapPosition(pos);
 
    maybeEmitWrapAround(pos);
 
    if (wrap || isHorizontalOrVertical() || !isLargeChange(pos)) {
        if (live)
            q->setValue(valueAt(pos));
        else
            setPosition(pos);
        if (!qFuzzyCompare(pos, oldPos))
            emit q->moved();
    }
    return true;
}
 
bool QQuickDialPrivate::handleRelease(const QPointF &point, ulong timestamp)
{
    Q_Q(QQuickDial);
    QQuickControlPrivate::handleRelease(point, timestamp);
    if (q->keepMouseGrab() || q->keepTouchGrab()) {
        const qreal oldPos = position;
        qreal pos = positionAt(point);
        if (snapMode != QQuickDial::NoSnap)
            pos = snapPosition(pos);
 
        maybeEmitWrapAround(pos);
 
        if (wrap || isHorizontalOrVertical() || !isLargeChange(pos))
            q->setValue(valueAt(pos));
        if (!qFuzzyCompare(pos, oldPos))
            emit q->moved();
 
        q->setKeepMouseGrab(false);
        q->setKeepTouchGrab(false);
    }
 
    q->setPressed(false);
    pressPoint = QPointF();
    positionBeforePress = 0;
    return true;
}
 
void QQuickDialPrivate::handleUngrab()
{
    Q_Q(QQuickDial);
    QQuickControlPrivate::handleUngrab();
    pressPoint = QPointF();
    positionBeforePress = 0;
    q->setPressed(false);
}
 
void QQuickDialPrivate::cancelHandle()
{
    Q_Q(QQuickDial);
    quickCancelDeferred(q, handleName());
}
 
void QQuickDialPrivate::executeHandle(bool complete)
{
    Q_Q(QQuickDial);
    if (handle.wasExecuted())
        return;
 
    if (!handle || complete)
        quickBeginDeferred(q, handleName(), handle);
    if (complete)
        quickCompleteDeferred(q, handleName(), handle);
}
 
template<typename ...Real>
static bool areRepresentableAsInteger(Real... numbers) {
    auto check = [](qreal number) -> bool { return std::nearbyint(number) == number; };
    return (... && check(numbers));
}
 
void QQuickDialPrivate::updateAllValuesAreInteger()
{
    allValuesAreInteger = areRepresentableAsInteger(to, from, stepSize) && stepSize != 0.0;
}
 
void QQuickDialPrivate::maybeEmitWrapAround(qreal pos)
{
    Q_Q(QQuickDial);
 
    if (wrap && isLargeChange(pos))
        emit q->wrapped((pos < q->position()) ? QQuickDial::Clockwise : QQuickDial::CounterClockwise);
}
 
QQuickDial::QQuickDial(QQuickItem *parent)
    : QQuickControl(*(new QQuickDialPrivate), parent)
{
    setActiveFocusOnTab(true);
    setAcceptedMouseButtons(Qt::LeftButton);
#if QT_CONFIG(quicktemplates2_multitouch)
    setAcceptTouchEvents(true);
#endif
#if QT_CONFIG(cursor)
    setCursor(Qt::ArrowCursor);
#endif
    Q_D(QQuickDial);
    d->setSizePolicy(QLayoutPolicy::Preferred, QLayoutPolicy::Preferred);
}
 
qreal QQuickDial::from() const
{
    Q_D(const QQuickDial);
    return d->from;
}
 
void QQuickDial::setFrom(qreal from)
{
    Q_D(QQuickDial);
    if (qFuzzyCompare(d->from, from))
        return;
 
    d->from = from;
    emit fromChanged();
    d->updateAllValuesAreInteger();
    if (isComponentComplete()) {
        setValue(d->value);
        d->updatePosition();
    }
}
 
qreal QQuickDial::to() const
{
    Q_D(const QQuickDial);
    return d->to;
}
 
void QQuickDial::setTo(qreal to)
{
    Q_D(QQuickDial);
    if (qFuzzyCompare(d->to, to))
        return;
 
    d->to = to;
    d->updateAllValuesAreInteger();
    emit toChanged();
    if (isComponentComplete()) {
        setValue(d->value);
        d->updatePosition();
    }
}
 
qreal QQuickDial::value() const
{
    Q_D(const QQuickDial);
    return d->value;
}
 
void QQuickDial::setValue(qreal value)
{
    Q_D(QQuickDial);
    if (isComponentComplete())
        value = d->from > d->to ? qBound(d->to, value, d->from) : qBound(d->from, value, d->to);
 
    if (qFuzzyCompare(d->value, value))
        return;
 
    d->value = value;
    d->updatePosition();
    emit valueChanged();
}
 
qreal QQuickDial::position() const
{
    Q_D(const QQuickDial);
    return d->position;
}
 
qreal QQuickDial::angle() const
{
    Q_D(const QQuickDial);
    return d->angle;
}
 
qreal QQuickDial::stepSize() const
{
    Q_D(const QQuickDial);
    return d->stepSize;
}
 
void QQuickDial::setStepSize(qreal step)
{
    Q_D(QQuickDial);
    if (qFuzzyCompare(d->stepSize, step))
        return;
 
    d->stepSize = step;
    d->updateAllValuesAreInteger();
    emit stepSizeChanged();
}
 
 
qreal QQuickDial::startAngle() const
{
    Q_D(const QQuickDial);
    return d->startAngle;
}
 
void QQuickDial::setStartAngle(qreal startAngle)
{
    Q_D(QQuickDial);
    if (!d->componentComplete) {
        // Binding evaluation order can cause warnings with certain combinations
        // of start and end angles, so delay the actual setting until after component completion.
        // Store the requested value in the existing member to avoid the need for an extra one.
        d->startAngle = startAngle;
        return;
    }
 
    if (qFuzzyCompare(d->startAngle, startAngle))
        return;
 
    // do not allow to change direction
    if (startAngle >= d->endAngle) {
        qmlWarning(this) << "startAngle (" << startAngle
            << ") cannot be greater than or equal to endAngle (" << d->endAngle << ")";
        return;
    }
 
    // Keep the interval around 0
    if (startAngle <= -360.) {
        qmlWarning(this) << "startAngle (" << startAngle << ") cannot be less than or equal to -360";
        return;
    }
 
    // keep the interval [startAngle, endAngle] unique
    if (startAngle < d->endAngle - 360.) {
        qmlWarning(this) << "Difference between startAngle (" << startAngle
            << ") and endAngle (" << d->endAngle << ") cannot be greater than 360."
            << " Changing endAngle to avoid overlaps.";
        d->endAngle = startAngle + 360.;
        emit endAngleChanged();
    }
 
    d->startAngle = startAngle;
    // changing the startAngle will change the angle
    // if the value is kept constant
    d->updatePosition();
    emit startAngleChanged();
}
 
qreal QQuickDial::endAngle() const
{
    Q_D(const QQuickDial);
    return d->endAngle;
 
}
 
void QQuickDial::setEndAngle(qreal endAngle)
{
    Q_D(QQuickDial);
    if (!d->componentComplete) {
        // Binding evaluation order can cause warnings with certain combinations
        // of start and end angles, so delay the actual setting until after component completion.
        // Store the requested value in the existing member to avoid the need for an extra one.
        d->endAngle = endAngle;
        return;
    }
 
    if (qFuzzyCompare(d->endAngle, endAngle))
        return;
 
    if (endAngle <= d->startAngle) {
        qmlWarning(this) << "endAngle (" << endAngle
            << ") cannot be less than or equal to startAngle (" << d->startAngle << ")";
        return;
    }
 
    // Keep the interval around 0
    if (endAngle >= 720.) {
        qmlWarning(this) << "endAngle (" << endAngle << ") cannot be greater than or equal to 720";
        return;
    }
 
    // keep the interval [startAngle, endAngle] unique
    if (endAngle > d->startAngle + 360.) {
        qmlWarning(this) << "Difference between startAngle (" << d->startAngle
            << ") and endAngle (" << endAngle << ") cannot be greater than 360."
            << " Changing startAngle to avoid overlaps.";
        d->startAngle = endAngle - 360.;
        emit startAngleChanged();
    }
 
    d->endAngle = endAngle;
    // changing the startAngle will change the angle
    // if the value is kept constant
    d->updatePosition();
    emit endAngleChanged();
}
 
QQuickDial::SnapMode QQuickDial::snapMode() const
{
    Q_D(const QQuickDial);
    return d->snapMode;
}
 
void QQuickDial::setSnapMode(SnapMode mode)
{
    Q_D(QQuickDial);
    if (d->snapMode == mode)
        return;
 
    d->snapMode = mode;
    emit snapModeChanged();
}
 
QQuickDial::InputMode QQuickDial::inputMode() const
{
    Q_D(const QQuickDial);
    return d->inputMode;
}
 
void QQuickDial::setInputMode(QQuickDial::InputMode mode)
{
    Q_D(QQuickDial);
    if (d->inputMode == mode)
        return;
 
    d->inputMode = mode;
    emit inputModeChanged();
}
 
bool QQuickDial::wrap() const
{
    Q_D(const QQuickDial);
    return d->wrap;
}
 
void QQuickDial::setWrap(bool wrap)
{
    Q_D(QQuickDial);
    if (d->wrap == wrap)
        return;
 
    d->wrap = wrap;
    emit wrapChanged();
}
 
bool QQuickDial::isPressed() const
{
    Q_D(const QQuickDial);
    return d->pressed;
}
 
void QQuickDial::setPressed(bool pressed)
{
    Q_D(QQuickDial);
    if (d->pressed == pressed)
        return;
 
    d->pressed = pressed;
    setAccessibleProperty("pressed", pressed);
    emit pressedChanged();
}
 
QQuickItem *QQuickDial::handle() const
{
    QQuickDialPrivate *d = const_cast<QQuickDialPrivate *>(d_func());
    if (!d->handle)
        d->executeHandle();
    return d->handle;
}
 
void QQuickDial::setHandle(QQuickItem *handle)
{
    Q_D(QQuickDial);
    if (handle == d->handle)
        return;
 
    QQuickControlPrivate::warnIfCustomizationNotSupported(this, handle, QStringLiteral("handle"));
 
    if (!d->handle.isExecuting())
        d->cancelHandle();
 
    QQuickControlPrivate::hideOldItem(d->handle);
    d->handle = handle;
    if (d->handle && !d->handle->parentItem())
        d->handle->setParentItem(this);
    if (!d->handle.isExecuting())
        emit handleChanged();
}
 
bool QQuickDial::live() const
{
    Q_D(const QQuickDial);
    return d->live;
}
 
void QQuickDial::setLive(bool live)
{
    Q_D(QQuickDial);
    if (d->live == live)
        return;
 
    d->live = live;
    emit liveChanged();
}
 
void QQuickDial::increase()
{
    Q_D(QQuickDial);
    qreal step = qFuzzyIsNull(d->stepSize) ? 0.1 : d->stepSize;
    setValue(d->value + step);
}
 
void QQuickDial::decrease()
{
    Q_D(QQuickDial);
    qreal step = qFuzzyIsNull(d->stepSize) ? 0.1 : d->stepSize;
    setValue(d->value - step);
}
 
void QQuickDial::keyPressEvent(QKeyEvent *event)
{
    Q_D(QQuickDial);
    const qreal oldValue = d->value;
    switch (event->key()) {
    case Qt::Key_Left:
    case Qt::Key_Down:
        setPressed(true);
        if (isMirrored())
            increase();
        else
            decrease();
        break;
 
    case Qt::Key_Right:
    case Qt::Key_Up:
        setPressed(true);
        if (isMirrored())
            decrease();
        else
            increase();
        break;
 
    case Qt::Key_Home:
        setPressed(true);
        setValue(isMirrored() ? d->to : d->from);
        break;
 
    case Qt::Key_End:
        setPressed(true);
        setValue(isMirrored() ? d->from : d->to);
        break;
 
    default:
        event->ignore();
        QQuickControl::keyPressEvent(event);
        break;
    }
    if (!qFuzzyCompare(d->value, oldValue))
        emit moved();
}
 
void QQuickDial::keyReleaseEvent(QKeyEvent *event)
{
    QQuickControl::keyReleaseEvent(event);
    setPressed(false);
}
 
void QQuickDial::mousePressEvent(QMouseEvent *event)
{
    Q_D(QQuickDial);
    QQuickControl::mousePressEvent(event);
    d->handleMove(event->position(), event->timestamp());
    setKeepMouseGrab(true);
}
 
#if QT_CONFIG(quicktemplates2_multitouch)
void QQuickDial::touchEvent(QTouchEvent *event)
{
    Q_D(QQuickDial);
    switch (event->type()) {
    case QEvent::TouchUpdate:
        for (const QTouchEvent::TouchPoint &point : event->points()) {
            if (!d->acceptTouch(point))
                continue;
 
            switch (point.state()) {
            case QEventPoint::Updated:
                if (!keepTouchGrab()) {
                    bool overXDragThreshold = QQuickWindowPrivate::dragOverThreshold(point.position().x() - d->pressPoint.x(), Qt::XAxis, &point);
                    setKeepTouchGrab(overXDragThreshold);
 
                    if (!overXDragThreshold) {
                        bool overYDragThreshold = QQuickWindowPrivate::dragOverThreshold(point.position().y() - d->pressPoint.y(), Qt::YAxis, &point);
                        setKeepTouchGrab(overYDragThreshold);
                    }
                }
                if (keepTouchGrab())
                    d->handleMove(point.position(), event->timestamp());
                break;
 
            default:
                QQuickControl::touchEvent(event);
                break;
            }
        }
        break;
 
    default:
        QQuickControl::touchEvent(event);
        break;
    }
}
#endif
 
#if QT_CONFIG(wheelevent)
void QQuickDial::wheelEvent(QWheelEvent *event)
{
    Q_D(QQuickDial);
    QQuickControl::wheelEvent(event);
    if (d->wheelEnabled) {
        const qreal oldValue = d->value;
        const QPointF angle = event->angleDelta();
        const qreal delta = (qFuzzyIsNull(angle.y()) ? angle.x() : (event->inverted() ? -angle.y() : angle.y())) / int(QWheelEvent::DefaultDeltasPerStep);
        const qreal step = qFuzzyIsNull(d->stepSize) ? 0.1 : d->stepSize;
        setValue(oldValue + step * delta);
        event->setAccepted(!qFuzzyCompare(d->value, oldValue));
    }
}
#endif
 
void QQuickDial::mirrorChange()
{
    QQuickControl::mirrorChange();
    emit angleChanged();
}
 
void QQuickDial::componentComplete()
{
    Q_D(QQuickDial);
    d->executeHandle(true);
    QQuickControl::componentComplete();
 
    // Set the (delayed) start and end angles, if necessary (see the setters for more info).
    if (!qFuzzyCompare(d->startAngle, defaultStartAngle)) {
        const qreal startAngle = d->startAngle;
        // Temporarily set it to something else so that it sees that it has changed.
        d->startAngle = defaultStartAngle;
        setStartAngle(startAngle);
    }
 
    if (!qFuzzyCompare(d->endAngle, defaultEndAngle)) {
        const qreal endAngle = d->endAngle;
        d->endAngle = defaultEndAngle;
        setEndAngle(endAngle);
    }
 
    setValue(d->value);
    d->updatePosition();
}
 
#if QT_CONFIG(accessibility)
void QQuickDial::accessibilityActiveChanged(bool active)
{
    QQuickControl::accessibilityActiveChanged(active);
 
    Q_D(QQuickDial);
    if (active)
        setAccessibleProperty("pressed", d->pressed);
}
 
QAccessible::Role QQuickDial::accessibleRole() const
{
    return QAccessible::Dial;
}
#endif
 
QT_END_NAMESPACE
 
#include "moc_qquickdial_p.cpp"