diff options
author | Mitch Curtis <mitch.curtis@qt.io> | 2016-10-13 13:14:21 +0200 |
---|---|---|
committer | Mitch Curtis <mitch.curtis@qt.io> | 2016-11-03 13:37:01 +0000 |
commit | d5d413a64a818a42f1199ef76605c16b82c0774b (patch) | |
tree | c064f34596a18226fc4311b4f4281ac2ced1478f /src | |
parent | 6f95a086b4d396ff62bc2817bcb1545f60973f38 (diff) |
ScrollBar: Fix documentation review findings
Change-Id: I83703bf0188aa52b873f717b3470ceba4a4d670e
Task-number: QTBUG-55904
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>
Diffstat (limited to 'src')
-rw-r--r-- | src/imports/controls/doc/images/qtquickcontrols2-scrollbar-non-attached.png | bin | 0 -> 5459 bytes | |||
-rw-r--r-- | src/imports/controls/doc/snippets/qtquickcontrols2-scrollbar-non-attached.qml | 93 | ||||
-rw-r--r-- | src/quicktemplates2/qquickscrollbar.cpp | 51 |
3 files changed, 142 insertions, 2 deletions
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-non-attached.png b/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-non-attached.png Binary files differnew file mode 100644 index 00000000..8817ad5c --- /dev/null +++ b/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-non-attached.png diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-scrollbar-non-attached.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-scrollbar-non-attached.qml new file mode 100644 index 00000000..f80ebfe2 --- /dev/null +++ b/src/imports/controls/doc/snippets/qtquickcontrols2-scrollbar-non-attached.qml @@ -0,0 +1,93 @@ +/**************************************************************************** +** +** Copyright (C) 2016 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the test suite of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQuick 2.7 +import QtQuick.Controls 2.0 + +Item { + width: 200 + height: 200 + +//! [1] +Rectangle { + id: frame + clip: true + width: 160 + height: 160 + border.color: "black" + anchors.centerIn: parent + + Text { + id: content + text: "ABC" + font.pixelSize: 160 + x: -hbar.position * width + y: -vbar.position * height + } + + ScrollBar { + id: vbar + hoverEnabled: true + active: hovered || pressed + orientation: Qt.Vertical + size: frame.height / content.height + anchors.top: parent.top + anchors.right: parent.right + anchors.bottom: parent.bottom + } + + ScrollBar { + id: hbar + hoverEnabled: true + active: hovered || pressed + orientation: Qt.Horizontal + size: frame.width / content.width + anchors.left: parent.left + anchors.right: parent.right + anchors.bottom: parent.bottom + } +} +//! [1] + +Component.onCompleted: { + hbar.active = true + vbar.active = true +} +} diff --git a/src/quicktemplates2/qquickscrollbar.cpp b/src/quicktemplates2/qquickscrollbar.cpp index 5d921fe3..7ac1df34 100644 --- a/src/quicktemplates2/qquickscrollbar.cpp +++ b/src/quicktemplates2/qquickscrollbar.cpp @@ -65,9 +65,12 @@ QT_BEGIN_NAMESPACE } \endcode + \section1 Attaching ScrollBar to a Flickable + When ScrollBar is attached \l {ScrollBar::vertical}{vertically} or - \l {ScrollBar::horizontal}{horizontally} to a Flickable, the following - properties are automatically set and updated as appropriate: + \l {ScrollBar::horizontal}{horizontally} to a Flickable, its geometry and + the following properties are automatically set and updated as appropriate: + \list \li \l orientation \li \l position @@ -113,6 +116,8 @@ QT_BEGIN_NAMESPACE } \endcode + \section1 Binding the Active State of Horizontal and Vertical Scroll Bars + Horizontal and vertical scroll bars do not share the \l active state with each other by default. In order to keep both bars visible whilst scrolling to either direction, establish a two-way binding between the active states @@ -120,6 +125,29 @@ QT_BEGIN_NAMESPACE \snippet qtquickcontrols2-scrollbar-active.qml 1 + \section1 Non-attached Scroll Bars + + It is possible to create an instance of ScrollBar without using the + attached property API. This is useful when the behavior of the attached + scoll bar is not sufficient or a \l Flickable is not in use. In the + following example, horizontal and vertical scroll bars are used to + scroll over the text without using \l Flickable: + + \snippet qtquickcontrols2-scrollbar-non-attached.qml 1 + + \image qtquickcontrols2-scrollbar-non-attached.png + + When using a non-attached ScrollBar, the following must be done manually: + + \list + \li Layout the scroll bar (with the \l {Item::}{x} and \l {Item::}{y} or + \l {Item::anchors}{anchor} properties, for example). + \li Set the \l size and \l position properties to determine the size and position + of the scroll bar in relation to the scrolled item. + \li Set the \l active property to determine when the scroll bar will be + visible. + \endlist + \sa ScrollIndicator, {Customizing ScrollBar}, {Indicator Controls} */ @@ -199,6 +227,9 @@ QQuickScrollBarAttached *QQuickScrollBar::qmlAttachedProperties(QObject *object) This property holds the size of the scroll bar, scaled to \c {0.0 - 1.0}. \sa {Flickable::visibleArea.heightRatio}{Flickable::visibleArea} + + This property is automatically set when the scroll bar is + \l {Attaching ScrollBar to a Flickable}{attached to a flickable}. */ qreal QQuickScrollBar::size() const { @@ -225,6 +256,9 @@ void QQuickScrollBar::setSize(qreal size) This property holds the position of the scroll bar, scaled to \c {0.0 - 1.0}. \sa {Flickable::visibleArea.yPosition}{Flickable::visibleArea} + + This property is automatically set when the scroll bar is + \l {Attaching ScrollBar to a Flickable}{attached to a flickable}. */ qreal QQuickScrollBar::position() const { @@ -273,6 +307,12 @@ void QQuickScrollBar::setStepSize(qreal step) This property holds whether the scroll bar is active, i.e. when it's \l pressed or the attached Flickable is \l {Flickable::moving}{moving}. + + It is possible to keep \l {Binding the Active State of Horizontal and Vertical Scroll Bars} + {both horizontal and vertical bars visible} while scrolling in either direction. + + This property is automatically set when the scroll bar is + \l {Attaching ScrollBar to a Flickable}{attached to a flickable}. */ bool QQuickScrollBar::isActive() const { @@ -321,6 +361,9 @@ void QQuickScrollBar::setPressed(bool pressed) Possible values: \value Qt.Horizontal Horizontal \value Qt.Vertical Vertical (default) + + This property is automatically set when the scroll bar is + \l {Attaching ScrollBar to a Flickable}{attached to a flickable}. */ Qt::Orientation QQuickScrollBar::orientation() const { @@ -560,6 +603,8 @@ QQuickScrollBarAttached::~QQuickScrollBarAttached() ScrollBar.horizontal: ScrollBar { } } \endcode + + \sa {Attaching ScrollBar to a Flickable} */ QQuickScrollBar *QQuickScrollBarAttached::horizontal() const { @@ -618,6 +663,8 @@ void QQuickScrollBarAttached::setHorizontal(QQuickScrollBar *horizontal) ScrollBar.vertical: ScrollBar { } } \endcode + + \sa {Attaching ScrollBar to a Flickable} */ QQuickScrollBar *QQuickScrollBarAttached::vertical() const { |