From fe98a60d904cafb9a82a28aa27bd2836dada67f9 Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Wed, 10 Jun 2015 17:06:12 +0200 Subject: Docs: Slider Change-Id: I9499ab27a74996f43db70ec3ddc49e04b39d2da6 Reviewed-by: J-P Nurmi --- .../images/qtquickcontrols2-slider-background.png | Bin 0 -> 1172 bytes .../images/qtquickcontrols2-slider-disabled.png | Bin 0 -> 1088 bytes .../doc/images/qtquickcontrols2-slider-focused.png | Bin 0 -> 1282 bytes .../doc/images/qtquickcontrols2-slider-handle.png | Bin 0 -> 1076 bytes .../doc/images/qtquickcontrols2-slider-normal.png | Bin 0 -> 1126 bytes .../doc/images/qtquickcontrols2-slider-track.png | Bin 0 -> 1006 bytes .../doc/src/qtquickcontrols2-customize.qdoc | 24 ++++++ src/controls/qquickslider.cpp | 88 ++++++++++++++++++--- src/imports/controls/Slider.qml | 4 + 9 files changed, 104 insertions(+), 12 deletions(-) create mode 100644 src/controls/doc/images/qtquickcontrols2-slider-background.png create mode 100644 src/controls/doc/images/qtquickcontrols2-slider-disabled.png create mode 100644 src/controls/doc/images/qtquickcontrols2-slider-focused.png create mode 100644 src/controls/doc/images/qtquickcontrols2-slider-handle.png create mode 100644 src/controls/doc/images/qtquickcontrols2-slider-normal.png create mode 100644 src/controls/doc/images/qtquickcontrols2-slider-track.png diff --git a/src/controls/doc/images/qtquickcontrols2-slider-background.png b/src/controls/doc/images/qtquickcontrols2-slider-background.png new file mode 100644 index 00000000..35fb12ca Binary files /dev/null and b/src/controls/doc/images/qtquickcontrols2-slider-background.png differ diff --git a/src/controls/doc/images/qtquickcontrols2-slider-disabled.png b/src/controls/doc/images/qtquickcontrols2-slider-disabled.png new file mode 100644 index 00000000..7d4584f8 Binary files /dev/null and b/src/controls/doc/images/qtquickcontrols2-slider-disabled.png differ diff --git a/src/controls/doc/images/qtquickcontrols2-slider-focused.png b/src/controls/doc/images/qtquickcontrols2-slider-focused.png new file mode 100644 index 00000000..7f9ad18b Binary files /dev/null and b/src/controls/doc/images/qtquickcontrols2-slider-focused.png differ diff --git a/src/controls/doc/images/qtquickcontrols2-slider-handle.png b/src/controls/doc/images/qtquickcontrols2-slider-handle.png new file mode 100644 index 00000000..7878e0f8 Binary files /dev/null and b/src/controls/doc/images/qtquickcontrols2-slider-handle.png differ diff --git a/src/controls/doc/images/qtquickcontrols2-slider-normal.png b/src/controls/doc/images/qtquickcontrols2-slider-normal.png new file mode 100644 index 00000000..dac102de Binary files /dev/null and b/src/controls/doc/images/qtquickcontrols2-slider-normal.png differ diff --git a/src/controls/doc/images/qtquickcontrols2-slider-track.png b/src/controls/doc/images/qtquickcontrols2-slider-track.png new file mode 100644 index 00000000..868fa420 Binary files /dev/null and b/src/controls/doc/images/qtquickcontrols2-slider-track.png differ diff --git a/src/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/controls/doc/src/qtquickcontrols2-customize.qdoc index 3843531c..7bbd0d71 100644 --- a/src/controls/doc/src/qtquickcontrols2-customize.qdoc +++ b/src/controls/doc/src/qtquickcontrols2-customize.qdoc @@ -102,6 +102,30 @@ \snippet RadioButton.qml indicator + \section1 Customizing Slider + + Slider consists of three parts: \l {Control::background}{background}, + \l {Slider::track}{track} and \l {Slider::handle}{handle}. Their + implicit sizes are used to calculate the implicit size of the control. + + \section3 Background + + \image qtquickcontrols2-slider-background.png + + Slider has no background item by default. + + \section3 Track + + \image qtquickcontrols2-slider-track.png + + \snippet Slider.qml track + + \section3 Handle + + \image qtquickcontrols2-slider-handle.png + + \snippet Slider.qml handle + \section1 Customizing Switch Switch consists of three parts: \l {Control::background}{background}, diff --git a/src/controls/qquickslider.cpp b/src/controls/qquickslider.cpp index 3f60fc95..5ce3cb92 100644 --- a/src/controls/qquickslider.cpp +++ b/src/controls/qquickslider.cpp @@ -49,7 +49,24 @@ QT_BEGIN_NAMESPACE \ingroup sliders \brief A slider control. - TODO + Slider is used to select a value by sliding a handle along a track. + + \table + \row \li \image qtquickcontrols2-slider-normal.png + \li A slider in its normal state. + \row \li \image qtquickcontrols2-slider-focused.png + \li A slider that has active focus. + \row \li \image qtquickcontrols2-slider-disabled.png + \li A slider that is disabled. + \endtable + + \code + Slider { + value: 0.5 + } + \endcode + + \sa {Customizing Slider} */ class QQuickSliderPrivate : public QQuickControlPrivate @@ -115,7 +132,14 @@ QQuickSlider::QQuickSlider(QQuickItem *parent) : /*! \qmlproperty real QtQuickControls2::Slider::value - TODO + This property holds the value in the range \c 0.0 - \c 1.0. The default value is \c 0.0. + + The value is defined as a percentage of the control's size, scaled + to \c 0.0 - \c 1.0. Unlike the \l position property, the \c value is + not updated while the handle is dragged. The value is updated after + the value has been chosen and the slider has been released. + + \sa position */ qreal QQuickSlider::value() const { @@ -137,7 +161,14 @@ void QQuickSlider::setValue(qreal value) /*! \qmlproperty real QtQuickControls2::Slider::position - TODO + This property holds the logical position of the handle. + + The position is defined as a percentage of the control's size, scaled + to \c 0.0 - \c 1.0. Unlike the \l value property, the \c position is + continuously updated while the handle is dragged. For visualizing a + slider, the right-to-left aware \l visualPosition should be used instead. + + \sa value, visualPosition */ qreal QQuickSlider::position() const { @@ -147,8 +178,16 @@ qreal QQuickSlider::position() const /*! \qmlproperty real QtQuickControls2::Slider::visualPosition + \readonly + + This property holds the visual position of the handle. + + The position is defined as a percentage of the control's size, scaled to + \c 0.0 - \c 1.0. When the control is \l mirrored, the value is equal to + \c {1.0 - position}. This makes the value suitable for visualizing the + slider, taking right-to-left support into account. - TODO + \sa position */ qreal QQuickSlider::visualPosition() const { @@ -172,7 +211,9 @@ void QQuickSlider::setPosition(qreal position) /*! \qmlproperty real QtQuickControls2::Slider::stepSize - TODO + This property holds the step size. The default value is \c 0.0. + + \sa snapMode, increase(), decrease() */ qreal QQuickSlider::stepSize() const { @@ -192,7 +233,16 @@ void QQuickSlider::setStepSize(qreal step) /*! \qmlproperty enumeration QtQuickControls2::Slider::snapMode - TODO + This property holds the snap mode. + + Possible values: + \list + \li \c Slider.NoSnap (default) - The slider does not snap. + \li \c Slider.SnapAlways - The slider snaps while the handle is dragged. + \li \c Slider.SnapOnRelease - The slider does not snap while being dragged, but only after the handle is released. + \endlist + + \sa stepSize */ QQuickSlider::SnapMode QQuickSlider::snapMode() const { @@ -212,7 +262,7 @@ void QQuickSlider::setSnapMode(SnapMode mode) /*! \qmlproperty bool QtQuickControls2::Slider::pressed - TODO + This property holds whether the slider is pressed. */ bool QQuickSlider::isPressed() const { @@ -232,7 +282,13 @@ void QQuickSlider::setPressed(bool pressed) /*! \qmlproperty enumeration QtQuickControls2::Slider::orientation - TODO + This property holds the orientation. + + Possible values: + \list + \li \c Qt.Horizontal (default) + \li \c Qt.Vertical + \endlist */ Qt::Orientation QQuickSlider::orientation() const { @@ -252,7 +308,9 @@ void QQuickSlider::setOrientation(Qt::Orientation orientation) /*! \qmlproperty Item QtQuickControls2::Slider::handle - TODO + This property holds the handle item. + + \sa {Customizing Slider} */ QQuickItem *QQuickSlider::handle() const { @@ -275,7 +333,9 @@ void QQuickSlider::setHandle(QQuickItem *handle) /*! \qmlproperty Item QtQuickControls2::Slider::track - TODO + This property holds the track item. + + \sa {Customizing Slider} */ QQuickItem *QQuickSlider::track() const { @@ -298,7 +358,9 @@ void QQuickSlider::setTrack(QQuickItem *track) /*! \qmlmethod void QtQuickControls2::Slider::increase() - TODO + Increases the value by \l stepSize or \c 0.1 if stepSize is not defined. + + \sa stepSize */ void QQuickSlider::increase() { @@ -310,7 +372,9 @@ void QQuickSlider::increase() /*! \qmlmethod void QtQuickControls2::Slider::decrease() - TODO + Decreases the value by \l stepSize or \c 0.1 if stepSize is not defined. + + \sa stepSize */ void QQuickSlider::decrease() { diff --git a/src/imports/controls/Slider.qml b/src/imports/controls/Slider.qml index cf9cecd3..79792709 100644 --- a/src/imports/controls/Slider.qml +++ b/src/imports/controls/Slider.qml @@ -52,6 +52,7 @@ AbstractSlider { padding: Theme.padding + //! [handle] handle: Rectangle { implicitWidth: 20 implicitHeight: 20 @@ -76,7 +77,9 @@ AbstractSlider { control.pressed ? control.Theme.pressColor : "transparent") } } + //! [handle] + //! [track] track: Rectangle { readonly property bool horizontal: control.orientation === Qt.Horizontal implicitWidth: horizontal ? 120 : 6 @@ -101,4 +104,5 @@ AbstractSlider { radius: control.Theme.roundness } } + //! [track] } -- cgit v1.2.3