diff options
author | Mitch Curtis <mitch.curtis@qt.io> | 2016-10-14 12:35:32 +0200 |
---|---|---|
committer | Mitch Curtis <mitch.curtis@qt.io> | 2016-10-17 14:02:48 +0000 |
commit | 2a7c3cb7043ef422d8c2a51b34bacc553ee4eddd (patch) | |
tree | 36cc146093c829d68335a9811a1476aad7cfacaa | |
parent | c95350a57c5246e869ec7cc3392dec7f3619f9bd (diff) |
Improve StackView's documentation
Add more GIFs and restructure the text so that it's easier to follow.
Change-Id: Ieb3136c306240dae44859a59e4451fce23275d47
Task-number: QTBUG-55904
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>
-rw-r--r-- | src/imports/controls/doc/images/qtquickcontrols2-stackview-pop.gif | bin | 0 -> 23801 bytes | |||
-rw-r--r-- | src/imports/controls/doc/images/qtquickcontrols2-stackview-push.gif | bin | 0 -> 42790 bytes | |||
-rw-r--r-- | src/imports/controls/doc/images/qtquickcontrols2-stackview-replace.gif | bin | 0 -> 28882 bytes | |||
-rw-r--r-- | src/imports/controls/doc/images/qtquickcontrols2-stackview-unwind.gif | bin | 0 -> 23744 bytes | |||
-rw-r--r-- | src/quicktemplates2/qquickstackview.cpp | 59 | ||||
-rw-r--r-- | tests/manual/gifs/data/qtquickcontrols2-stackview-pop.qml | 102 | ||||
-rw-r--r-- | tests/manual/gifs/data/qtquickcontrols2-stackview-push.qml | 97 | ||||
-rw-r--r-- | tests/manual/gifs/data/qtquickcontrols2-stackview-replace.qml | 102 | ||||
-rw-r--r-- | tests/manual/gifs/data/qtquickcontrols2-stackview-unwind.qml | 102 | ||||
-rw-r--r-- | tests/manual/gifs/tst_gifs.cpp | 29 |
10 files changed, 474 insertions, 17 deletions
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-stackview-pop.gif b/src/imports/controls/doc/images/qtquickcontrols2-stackview-pop.gif Binary files differnew file mode 100644 index 00000000..1971c2e0 --- /dev/null +++ b/src/imports/controls/doc/images/qtquickcontrols2-stackview-pop.gif diff --git a/src/imports/controls/doc/images/qtquickcontrols2-stackview-push.gif b/src/imports/controls/doc/images/qtquickcontrols2-stackview-push.gif Binary files differnew file mode 100644 index 00000000..0218cc0f --- /dev/null +++ b/src/imports/controls/doc/images/qtquickcontrols2-stackview-push.gif diff --git a/src/imports/controls/doc/images/qtquickcontrols2-stackview-replace.gif b/src/imports/controls/doc/images/qtquickcontrols2-stackview-replace.gif Binary files differnew file mode 100644 index 00000000..63a6b2b4 --- /dev/null +++ b/src/imports/controls/doc/images/qtquickcontrols2-stackview-replace.gif diff --git a/src/imports/controls/doc/images/qtquickcontrols2-stackview-unwind.gif b/src/imports/controls/doc/images/qtquickcontrols2-stackview-unwind.gif Binary files differnew file mode 100644 index 00000000..28c051d8 --- /dev/null +++ b/src/imports/controls/doc/images/qtquickcontrols2-stackview-unwind.gif diff --git a/src/quicktemplates2/qquickstackview.cpp b/src/quicktemplates2/qquickstackview.cpp index 8cb06d06..a29062dd 100644 --- a/src/quicktemplates2/qquickstackview.cpp +++ b/src/quicktemplates2/qquickstackview.cpp @@ -126,6 +126,33 @@ QT_BEGIN_NAMESPACE application UI, "pop" navigates backward, and "replace" replaces the \l currentItem. + \section2 Pushing Items + + In the following animation, three \l Label controls are pushed onto a + stack view with the \l push() function: + + \image qtquickcontrols2-stackview-push.gif + + The stack now contains the following items: \c [A, B, C]. + + \note When the stack is empty, a push() operation will not have a + transition animation because there is nothing to transition from (typically + on application start-up). + + \section2 Popping Items + + Continuing on from the example above, the topmost item on the stack is + removed with a call to \l pop(): + + \image qtquickcontrols2-stackview-pop.gif + + The stack now contains the following items: \c [A, B]. + + \note A pop() operation on a stack with depth 1 or 0 does nothing. In such + cases, the stack can be emptied using the \l clear() method. + + \section3 Unwinding Items via Pop + Sometimes, it is necessary to go back more than a single step in the stack. For example, to return to a "main" item or some kind of section item in the application. In such cases, it is possible to specify an item as a @@ -135,22 +162,20 @@ QT_BEGIN_NAMESPACE explicitly unwind to the bottom of the stack, it is recommended to use \l{pop()}{pop(null)}, although any non-existent item will do. - Given the stack [A, B, C]: + In the following animation, we unwind the stack to the first item by + calling \c pop(null): - \list - \li \l{push()}{push(D)} => [A, B, C, D] - "push" transition animation - between C and D - \li pop() => [A, B] - "pop" transition animation between C and B - \li \l{replace()}{replace(D)} => [A, B, D] - "replace" transition between - C and D - \li \l{pop()}{pop(A)} => [A] - "pop" transition between C and A - \endlist + \image qtquickcontrols2-stackview-unwind.gif - \note When the stack is empty, a push() operation will not have a - transition animation because there is nothing to transition from (typically - on application start-up). A pop() operation on a stack with depth 1 or - 0 does nothing. In such cases, the stack can be emptied using the clear() - method. + The stack now contains a single item: \c [A]. + + \section2 Replacing Items + + In the following animation, we \l replace the topmost item with \c D: + + \image qtquickcontrols2-stackview-replace.gif + + The stack now contains the following items: \c [A, B, D]. \section1 Deep Linking @@ -441,7 +466,7 @@ QQuickItem *QQuickStackView::find(const QJSValue &callback, LoadBehavior behavio \value StackView.Transition An operation with transitions. \value StackView.Immediate An immediate operation without transitions. - \sa initialItem + \sa initialItem, {Pushing Items} */ void QQuickStackView::push(QQmlV4Function *args) { @@ -510,7 +535,7 @@ void QQuickStackView::push(QQmlV4Function *args) stackView.pop(null) \endcode - \sa clear() + \sa clear(), {Popping Items}, {Unwinding Items via Pop} */ void QQuickStackView::pop(QQmlV4Function *args) { @@ -625,7 +650,7 @@ void QQuickStackView::pop(QQmlV4Function *args) \value StackView.Transition An operation with transitions. \value StackView.Immediate An immediate operation without transitions. - \sa push() + \sa push(), {Replacing Items} */ void QQuickStackView::replace(QQmlV4Function *args) { diff --git a/tests/manual/gifs/data/qtquickcontrols2-stackview-pop.qml b/tests/manual/gifs/data/qtquickcontrols2-stackview-pop.qml new file mode 100644 index 00000000..2b4d3ee3 --- /dev/null +++ b/tests/manual/gifs/data/qtquickcontrols2-stackview-pop.qml @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** 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.Window 2.0 +import QtQuick.Controls 2.0 + +ApplicationWindow { + width: 160 + height: 160 + visible: true + color: "#eeeeee" + + property int maxDepth: 3 + + function itemText(index) { + return String.fromCharCode(65 + index); + } + + Component { + id: labelComponent + + Label { + font.pixelSize: 60 + horizontalAlignment: Text.AlignHCenter + verticalAlignment: Text.AlignVCenter + } + } + + StackView { + id: stackView + anchors.fill: parent + + Component.onCompleted: { + for (var i = 0; i < maxDepth; ++i) { + stackView.push(labelComponent, { text: itemText(i) }, StackView.Immediate); + } + } + } + + Label { + id: operationLabel + text: "pop()" + font.pixelSize: 16 + anchors.bottom: parent.bottom + anchors.horizontalCenter: parent.horizontalCenter + anchors.margins: 10 + } + + Timer { + id: operationTimer + running: true + interval: 1500 + onTriggered: { + stackView.pop(); + hideOperationTimer.start(); + } + } + + Timer { + id: hideOperationTimer + interval: operationTimer.interval + onTriggered: operationLabel.visible = false + } +} diff --git a/tests/manual/gifs/data/qtquickcontrols2-stackview-push.qml b/tests/manual/gifs/data/qtquickcontrols2-stackview-push.qml new file mode 100644 index 00000000..dd318f1d --- /dev/null +++ b/tests/manual/gifs/data/qtquickcontrols2-stackview-push.qml @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** 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.Window 2.0 +import QtQuick.Controls 2.0 + +ApplicationWindow { + width: 160 + height: 160 + visible: true + color: "#eeeeee" + + property int itemIndex: 0 + property int maxDepth: 3 + + function itemText(index) { + return String.fromCharCode(65 + index); + } + + Component { + id: labelComponent + + Label { + font.pixelSize: 60 + horizontalAlignment: Text.AlignHCenter + verticalAlignment: Text.AlignVCenter + } + } + + StackView { + id: stackView + anchors.fill: parent + } + + Label { + id: operationLabel + text: "push(" + itemText(Math.max(0, Math.min(maxDepth - 1, itemIndex - 1))) + ")" + font.pixelSize: 16 + anchors.bottom: parent.bottom + anchors.horizontalCenter: parent.horizontalCenter + anchors.margins: 10 + } + + Timer { + id: operationTimer + running: true + interval: 1500 + repeat: stackView.depth < maxDepth - 1 + onRepeatChanged: if (!repeat) hideOperationTimer.start() + + onTriggered: stackView.push(labelComponent, { text: itemText(itemIndex++) }) + } + + Timer { + id: hideOperationTimer + interval: operationTimer.interval * 2 + onTriggered: operationLabel.visible = false + } +} diff --git a/tests/manual/gifs/data/qtquickcontrols2-stackview-replace.qml b/tests/manual/gifs/data/qtquickcontrols2-stackview-replace.qml new file mode 100644 index 00000000..2586a81b --- /dev/null +++ b/tests/manual/gifs/data/qtquickcontrols2-stackview-replace.qml @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** 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.Window 2.0 +import QtQuick.Controls 2.0 + +ApplicationWindow { + width: 160 + height: 160 + visible: true + color: "#eeeeee" + + property int maxDepth: 3 + + function itemText(index) { + return String.fromCharCode(65 + index); + } + + Component { + id: labelComponent + + Label { + font.pixelSize: 60 + horizontalAlignment: Text.AlignHCenter + verticalAlignment: Text.AlignVCenter + } + } + + StackView { + id: stackView + anchors.fill: parent + + Component.onCompleted: { + for (var i = 0; i < maxDepth; ++i) { + stackView.push(labelComponent, { text: itemText(i) }, StackView.Immediate); + } + } + } + + Label { + id: operationLabel + text: "replace(D)" + font.pixelSize: 16 + anchors.bottom: parent.bottom + anchors.horizontalCenter: parent.horizontalCenter + anchors.margins: 10 + } + + Timer { + id: operationTimer + running: true + interval: 1500 + onTriggered: { + stackView.replace(labelComponent, { text: "D" }); + hideOperationTimer.start(); + } + } + + Timer { + id: hideOperationTimer + interval: operationTimer.interval + onTriggered: operationLabel.visible = false + } +} diff --git a/tests/manual/gifs/data/qtquickcontrols2-stackview-unwind.qml b/tests/manual/gifs/data/qtquickcontrols2-stackview-unwind.qml new file mode 100644 index 00000000..6fb6b2a8 --- /dev/null +++ b/tests/manual/gifs/data/qtquickcontrols2-stackview-unwind.qml @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** 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.Window 2.0 +import QtQuick.Controls 2.0 + +ApplicationWindow { + width: 160 + height: 160 + visible: true + color: "#eeeeee" + + property int maxDepth: 3 + + function itemText(index) { + return String.fromCharCode(65 + index); + } + + Component { + id: labelComponent + + Label { + font.pixelSize: 60 + horizontalAlignment: Text.AlignHCenter + verticalAlignment: Text.AlignVCenter + } + } + + StackView { + id: stackView + anchors.fill: parent + + Component.onCompleted: { + for (var i = 0; i < maxDepth; ++i) { + stackView.push(labelComponent, { text: itemText(i) }, StackView.Immediate); + } + } + } + + Label { + id: operationLabel + text: "pop(null)" + font.pixelSize: 16 + anchors.bottom: parent.bottom + anchors.horizontalCenter: parent.horizontalCenter + anchors.margins: 10 + } + + Timer { + id: operationTimer + running: true + interval: 1500 + onTriggered: { + stackView.pop(null); + hideOperationTimer.start(); + } + } + + Timer { + id: hideOperationTimer + interval: operationTimer.interval + onTriggered: operationLabel.visible = false + } +} diff --git a/tests/manual/gifs/tst_gifs.cpp b/tests/manual/gifs/tst_gifs.cpp index a147a45d..be436b52 100644 --- a/tests/manual/gifs/tst_gifs.cpp +++ b/tests/manual/gifs/tst_gifs.cpp @@ -76,6 +76,8 @@ private slots: void checkables_data(); void checkables(); void comboBox(); + void stackView_data(); + void stackView(); private: void moveSmoothly(QQuickWindow *window, const QPoint &from, const QPoint &to, int movements, @@ -882,6 +884,33 @@ void tst_Gifs::progressBar() gifRecorder.waitForFinish(); } +void tst_Gifs::stackView_data() +{ + QTest::addColumn<QString>("name"); + QTest::addColumn<int>("duration"); + + QTest::newRow("push") << "push" << 8; + QTest::newRow("pop") << "pop" << 6; + QTest::newRow("unwind") << "unwind" << 6; + QTest::newRow("replace") << "replace" << 6; +} + +void tst_Gifs::stackView() +{ + QFETCH(QString, name); + QFETCH(int, duration); + + GifRecorder gifRecorder; + gifRecorder.setDataDirPath(dataDirPath); + gifRecorder.setOutputDir(outputDir); + gifRecorder.setRecordingDuration(duration); + gifRecorder.setHighQuality(true); + gifRecorder.setQmlFileName(QString::fromLatin1("qtquickcontrols2-stackview-%1.qml").arg(name)); + + gifRecorder.start(); + gifRecorder.waitForFinish(); +} + QTEST_MAIN(tst_Gifs) #include "tst_gifs.moc" |