diff options
| author | Alan Alpert <alan.alpert@nokia.com> | 2012-07-19 11:05:05 +1000 |
|---|---|---|
| committer | Qt by Nokia <qt-info@nokia.com> | 2012-08-08 10:50:52 +0200 |
| commit | 3704f1f0b25aee9e7c903368202ccf7dc16d9107 (patch) | |
| tree | c44762ec24a0a351f401bdf1f4e43c7dde18c396 | |
| parent | 6ebf215fdaf2d757ab90ae4d46c4b938e978e2dc (diff) | |
Provide features/use-case docs in QML AppDevGuide
The most common use-cases should have easily-accessible solutions
available from the front-page of the QML application developer guide.
This commit adds that documentation.
Task-number: QTBUG-26428
Change-Id: Id15e76db15fbe3599e9ac5dd98e74ad4e034ece4
Reviewed-by: Alan Alpert <alan.alpert@nokia.com>
37 files changed, 1638 insertions, 125 deletions
diff --git a/src/quick/doc/images/qml-uses-animation.png b/src/quick/doc/images/qml-uses-animation.png Binary files differnew file mode 100644 index 0000000000..b54361260c --- /dev/null +++ b/src/quick/doc/images/qml-uses-animation.png diff --git a/src/quick/doc/images/qml-uses-integratingjs.png b/src/quick/doc/images/qml-uses-integratingjs.png Binary files differnew file mode 100644 index 0000000000..3bb0d8aadf --- /dev/null +++ b/src/quick/doc/images/qml-uses-integratingjs.png diff --git a/src/quick/doc/images/qml-uses-layouts.png b/src/quick/doc/images/qml-uses-layouts.png Binary files differnew file mode 100644 index 0000000000..3e1162977e --- /dev/null +++ b/src/quick/doc/images/qml-uses-layouts.png diff --git a/src/quick/doc/images/qml-uses-styling-text.png b/src/quick/doc/images/qml-uses-styling-text.png Binary files differnew file mode 100644 index 0000000000..af2518a9e8 --- /dev/null +++ b/src/quick/doc/images/qml-uses-styling-text.png diff --git a/src/quick/doc/images/qml-uses-styling.png b/src/quick/doc/images/qml-uses-styling.png Binary files differnew file mode 100644 index 0000000000..a6bf68e783 --- /dev/null +++ b/src/quick/doc/images/qml-uses-styling.png diff --git a/src/quick/doc/images/qml-uses-text.png b/src/quick/doc/images/qml-uses-text.png Binary files differnew file mode 100644 index 0000000000..6b3d88cb3f --- /dev/null +++ b/src/quick/doc/images/qml-uses-text.png diff --git a/src/quick/doc/images/qml-uses-userinput.png b/src/quick/doc/images/qml-uses-userinput.png Binary files differnew file mode 100644 index 0000000000..2793e8d1d7 --- /dev/null +++ b/src/quick/doc/images/qml-uses-userinput.png diff --git a/src/quick/doc/images/qml-uses-visual-opacity.png b/src/quick/doc/images/qml-uses-visual-opacity.png Binary files differnew file mode 100644 index 0000000000..ab238deb54 --- /dev/null +++ b/src/quick/doc/images/qml-uses-visual-opacity.png diff --git a/src/quick/doc/images/qml-uses-visual-rectangles.png b/src/quick/doc/images/qml-uses-visual-rectangles.png Binary files differnew file mode 100644 index 0000000000..acf7cb160a --- /dev/null +++ b/src/quick/doc/images/qml-uses-visual-rectangles.png diff --git a/src/quick/doc/images/qml-uses-visual-transforms.png b/src/quick/doc/images/qml-uses-visual-transforms.png Binary files differnew file mode 100644 index 0000000000..d89fc75256 --- /dev/null +++ b/src/quick/doc/images/qml-uses-visual-transforms.png diff --git a/src/quick/doc/snippets/qml/usecases/Button.qml b/src/quick/doc/snippets/qml/usecases/Button.qml new file mode 100644 index 0000000000..a6934cfa0a --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/Button.qml @@ -0,0 +1,86 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Rectangle { + id: container + // The caption property is an alias to the text of the Text element, so Button users can set the text + property alias caption: txt.text + // The clicked signal is emitted whenever the button is clicked, so Button users can respond + signal clicked + + // The button is set to have rounded corners and a thin black border + radius: 4 + border.width: 1 + // This button has a fixed size, but it could resize based on the text + width: 160 + height: 40 + + // A SystemPalette is used to get colors from the system settings for the background + SystemPalette { id: sysPalette } + + gradient: Gradient { + + // The top gradient is darker when 'pressed', all colors come from the system palette + GradientStop { position: 0.0; color: ma.pressed ? sysPalette.dark : sysPalette.light } + + GradientStop { position: 1.0; color: sysPalette.button } + } + + Text { + id: txt + // This is the default value of the text, but most Button users will set their own with the caption property + text: "Button" + font.bold: true + font.pixelSize: 16 + anchors.centerIn: parent + } + + MouseArea { + id: ma + anchors.fill: parent + // This re-emits the clicked signal on the root item, so that Button users can respond to it + onClicked: container.clicked() + } +} + +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/MyText.qml b/src/quick/doc/snippets/qml/usecases/MyText.qml new file mode 100644 index 0000000000..5d9310dda5 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/MyText.qml @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Text { + color: "lightsteelblue" + font { family: 'Courier'; pixelSize: 20; bold: true; capitalization: Font.SmallCaps } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/animations.qml b/src/quick/doc/snippets/qml/usecases/animations.qml new file mode 100644 index 0000000000..486cf57b1e --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/animations.qml @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + Column { + //![states] + + Item { + id: container + width: 320 + height: 120 + + Rectangle { + id: rect + color: "red" + width: 120 + height: 120 + + MouseArea { + anchors.fill: parent + onClicked: container.state == 'other' ? container.state = '' : container.state = 'other' + } + } + states: [ + // This adds a second state to the container where the rectangle is farther to the right + + State { name: "other" + + PropertyChanges { + target: rect + x: 200 + } + } + ] + transitions: [ + // This adds a transition that defaults to applying to all state changes + + Transition { + + // This applies a default NumberAnimation to any changes a state change makes to x or y properties + NumberAnimation { properties: "x,y" } + } + ] + } + //![states] + //![behave] + Item { + width: 320 + height: 120 + + Rectangle { + color: "green" + width: 120 + height: 120 + + // This is the behavior, and it applies a NumberAnimation to any attempt to set the x property + Behavior on x { + + NumberAnimation { + //This specifies how long the animation takes + duration: 600 + //This selects an easing curve to interpolate with, the default is Easing.Linear + easing.type: Easing.OutBounce + } + } + + MouseArea { + anchors.fill: parent + onClicked: parent.x == 0 ? parent.x = 200 : parent.x = 0 + } + } + } + //![behave] + //![constant] + Item { + width: 320 + height: 120 + + Rectangle { + color: "blue" + width: 120 + height: 120 + + // By setting this SequentialAnimation on x, it and animations within it will automatically animate + // the x property of this element + SequentialAnimation on x { + id: xAnim + // Animations on properties start running by default + running: false + loops: Animation.Infinite // The animation is set to loop indefinitely + NumberAnimation { from: 0; to: 200; duration: 500; easing.type: Easing.InOutQuad } + NumberAnimation { from: 200; to: 0; duration: 500; easing.type: Easing.InOutQuad } + PauseAnimation { duration: 250 } // This puts a bit of time between the loop + } + + MouseArea { + anchors.fill: parent + // The animation starts running when you click within the rectangle + onClicked: xAnim.running = true + } + } + } + //![constant] + + //![scripted] + Item { + width: 320 + height: 120 + + Rectangle { + id: rectangle + color: "yellow" + width: 120 + height: 120 + + MouseArea { + anchors.fill: parent + // The animation starts running when you click within the rectange + onClicked: anim.running = true; + } + } + + // This animation specifically targets the Rectangle's properties to animate + SequentialAnimation { + id: anim + // Animations on their own are not running by default + // The default number of loops is one, restart the animation to see it again + + NumberAnimation { target: rectangle; property: "x"; from: 0; to: 200; duration: 500 } + + NumberAnimation { target: rectangle; property: "x"; from: 200; to: 0; duration: 500 } + } + } + //![scripted] + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/integratingjs-inline.qml b/src/quick/doc/snippets/qml/usecases/integratingjs-inline.qml new file mode 100644 index 0000000000..f9a7294109 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/integratingjs-inline.qml @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + id: container + width: 320 + height: 480 + + function randomNumber() { + return Math.random() * 360; + } + + function getNumber() { + return container.randomNumber(); + } + + MouseArea { + anchors.fill: parent + // This line uses the JS function from the item + onClicked: rectangle.rotation = container.getNumber(); + } + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + Rectangle { + id: rectangle + anchors.centerIn: parent + width: 160 + height: 160 + color: "green" + Behavior on rotation { RotationAnimation { direction: RotationAnimation.Clockwise } } + } + +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/integratingjs.qml b/src/quick/doc/snippets/qml/usecases/integratingjs.qml new file mode 100644 index 0000000000..cf1a319b66 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/integratingjs.qml @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 +import "myscript.js" as Logic + +Item { + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + MouseArea { + anchors.fill: parent + // This line uses the JS function from the separate JS file + onClicked: rectangle.rotation = Logic.getRandom(rectangle.rotation); + } + + Rectangle { + id: rectangle + anchors.centerIn: parent + width: 160 + height: 160 + color: "green" + Behavior on rotation { RotationAnimation { direction: RotationAnimation.Clockwise } } + } + +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/layouts.qml b/src/quick/doc/snippets/qml/usecases/layouts.qml new file mode 100644 index 0000000000..0099cdf319 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/layouts.qml @@ -0,0 +1,122 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + Rectangle { + // Manually positioned at 20,20 + x: 20 + y: 20 + width: 80 + height: 80 + color: "red" + } + Rectangle { + // Anchored to 20px off the top right corner of the parent + anchors.right: parent.right + anchors.top: parent.top + anchors.margins: 20 // Sets all margins at once + width: 80 + height: 80 + color: "blue" + } + Rectangle { + // Anchored to 20px off the top center corner of the parent + // Note the different group property syntax to the previous Rectangle. Both are valid. + anchors { horizontalCenter: parent.horizontalCenter; top: parent.top; topMargin: 20 } + width: 80 + height: 80 + color: "green" + } + + Row { // Lays the Rectangles out in a line + x: 20 + y: 120 + spacing: 20 // Places 20px of space between items + Rectangle { width: 80; height: 80; color: "red" } + Rectangle { width: 80; height: 80; color: "green" } + Rectangle { width: 80; height: 80; color: "blue" } + } + + Rectangle { + id: middleRect + //This Rectangle has its y animated, for the others to follow + x: 120 + y: 220 + SequentialAnimation on y { + loops: -1 + NumberAnimation { from: 220; to: 380; easing.type: Easing.InOutQuad; duration: 1200 } + NumberAnimation { from: 380; to: 220; easing.type: Easing.InOutQuad; duration: 1200 } + } + width: 80 + height: 80 + color: "green" + } + Rectangle { + // x,y bound to the position of middleRect + x: middleRect.x - 100 + y: middleRect.y + width: 80 + height: 80 + color: "red" + } + + Rectangle { + // Anchored to the position of middleRect + anchors.left: middleRect.right + anchors.leftMargin: 20 + anchors.verticalCenter: middleRect.verticalCenter + width: 80 + height: 80 + color: "blue" + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/myscript.js b/src/quick/doc/snippets/qml/usecases/myscript.js new file mode 100644 index 0000000000..037cd94c5a --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/myscript.js @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +// myscript.js +function getRandom(previousValue) { + return Math.floor(previousValue + Math.random() * 90) % 360; +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/styling-text.qml b/src/quick/doc/snippets/qml/usecases/styling-text.qml new file mode 100644 index 0000000000..719bfda3e0 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/styling-text.qml @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + id: root + width: 480 + height: 320 + + Rectangle { + color: "#272822" + width: 480 + height: 320 + } + +//![texts] + Column { + spacing: 20 + + MyText { text: 'I am the very model of a modern major general!' } + + MyText { text: 'I\'ve information vegetable, animal and mineral.' } + + MyText { + width: root.width + wrapMode: Text.WordWrap + text: 'I know the kings of England and I quote the fights historical:' + } + + MyText { text: 'From Marathon to Waterloo in order categorical.' } + } +//![texts] +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/styling.qml b/src/quick/doc/snippets/qml/usecases/styling.qml new file mode 100644 index 0000000000..99212b5bd7 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/styling.qml @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + Column { + width: childrenRect.width + anchors.centerIn: parent + spacing: 8 + // Each of these is a Button as styled in Button.qml + Button { caption: "Eeny"; onClicked: console.log("Eeny");} + Button { caption: "Meeny"; onClicked: console.log("Meeny");} + Button { caption: "Miny"; onClicked: console.log("Miny");} + Button { caption: "Mo"; onClicked: console.log("Mo");} + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/text.qml b/src/quick/doc/snippets/qml/usecases/text.qml new file mode 100644 index 0000000000..545be70e51 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/text.qml @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + id: root + width: 480 + height: 320 + + Rectangle { + color: "#272822" + width: 480 + height: 320 + } + + Column { + spacing: 20 + + Text { + text: 'I am the very model of a modern major general!' + + // color can be set on the entire element with this property + color: "yellow" + + } + + Text { + // For text to wrap, a width has to be explicitly provided + width: root.width + + // This setting makes the text wrap at word boundaries when it goes past the width of the Text object + wrapMode: Text.WordWrap + + // You can use \ to escape quotation marks, or to add new lines (\n). Use \\ to get a \ in the string + text: 'I am the very model of a modern major general. I\'ve information vegetable, animal and mineral. I know the kings of england and I quote the fights historical; from Marathon to Waterloo in order categorical.' + + // color can be set on the entire element with this property + color: "white" + + } + + Text { + text: 'I am the very model of a modern major general!' + + // color can be set on the entire element with this property + color: "yellow" + + // font properties can be set effciently on the whole string at once + font { family: 'Courier'; pixelSize: 20; italic: true; capitalization: Font.SmallCaps } + + } + + Text { + // HTML like markup can also be used + text: '<font color="white">I am the <b>very</b> model of a modern <i>major general</i>!</font>' + + // This could also be written font { pointSize: 14 }. Both syntaxes are valid. + font.pointSize: 14 + + // StyledText format supports fewer tags, but is more efficient than RichText + textFormat: Text.StyledText + + } + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/userinput-keys.qml b/src/quick/doc/snippets/qml/usecases/userinput-keys.qml new file mode 100644 index 0000000000..77e7524e4a --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/userinput-keys.qml @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + id: root + + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + Rectangle { + id: rectangle + x: 40 + y: 20 + width: 120 + height: 120 + color: "red" + + focus: true + Keys.onUpPressed: rectangle.y -= 10 + Keys.onDownPressed: rectangle.y += 10 + Keys.onLeftPressed: rectangle.x += 10 + Keys.onRightPressed: rectangle.x -= 10 + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/userinput.qml b/src/quick/doc/snippets/qml/usecases/userinput.qml new file mode 100644 index 0000000000..887cc9ee78 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/userinput.qml @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + id: root + + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + Rectangle { + id: rectangle + x: 40 + y: 20 + width: 120 + height: 120 + color: "red" + + MouseArea { + anchors.fill: parent + onClicked: rectangle.width += 10 + } + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/visual-opacity.qml b/src/quick/doc/snippets/qml/usecases/visual-opacity.qml new file mode 100644 index 0000000000..b28dbd5b2a --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/visual-opacity.qml @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + Item { + x: 20 + y: 270 + width: 200 + height: 200 + MouseArea { + anchors.fill: parent + onClicked: topRect.visible = !topRect.visible + } + Rectangle { + x: 20 + y: 20 + width: 100 + height: 100 + color: "red" + } + Rectangle { + id: topRect + opacity: 0.5 + + x: 100 + y: 100 + width: 100 + height: 100 + color: "blue" + } + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/visual-rects.qml b/src/quick/doc/snippets/qml/usecases/visual-rects.qml new file mode 100644 index 0000000000..f04ba13e95 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/visual-rects.qml @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + // This element displays a rectangle with a gradient and a border + Rectangle { + x: 160 + y: 20 + width: 100 + height: 100 + radius: 8 // This gives rounded corners to the Rectangle + gradient: Gradient { // This sets a vertical gradient fill + GradientStop { position: 0.0; color: "aqua" } + GradientStop { position: 1.0; color: "teal" } + } + border { width: 3; color: "white" } // This sets a 3px wide black border to be drawn + } + + // This rectangle is a plain color with no border + Rectangle { + x: 40 + y: 20 + width: 100 + height: 100 + color: "red" + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/visual-transforms.qml b/src/quick/doc/snippets/qml/usecases/visual-transforms.qml new file mode 100644 index 0000000000..dd22bb9500 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/visual-transforms.qml @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + Rectangle { + rotation: 45 // This rotates the Rectangle by 45 degrees + x: 20 + y: 160 + width: 100 + height: 100 + color: "blue" + } + Rectangle { + scale: 0.8 // This scales the Rectangle down to 80% size + x: 160 + y: 160 + width: 100 + height: 100 + color: "green" + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/usecases/visual.qml b/src/quick/doc/snippets/qml/usecases/visual.qml new file mode 100644 index 0000000000..81f3edcab3 --- /dev/null +++ b/src/quick/doc/snippets/qml/usecases/visual.qml @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation 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 Nokia Corporation and its Subsidiary(-ies) 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$ +** +****************************************************************************/ + +//![0] +import QtQuick 2.0 + +Item { + + width: 320 + height: 480 + + Rectangle { + color: "#272822" + width: 320 + height: 480 + } + + //![image] + // This element displays an image. Because the source is online, it may take some time to fetch + Image { + x: 40 + y: 20 + width: 61 + height: 73 + source: "http://codereview.qt-project.org/static/logo_qt.png" + } + //![image] +} +//![0] diff --git a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc index f72f129894..e67df07475 100644 --- a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc +++ b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc @@ -28,34 +28,6 @@ /* XXX -The "Features and Use-Case Solutions" section has been temporarily removed -from the "QML Application Developer Resources" page as we do not have any -content for them yet. - -Once we have written content for these sections, they can be re-integrated. - -See QTBUG-26428 - -\section1 Features and Use-Case Solutions - -\list -\li \l{qtquick-usecase-visual.html}{Placing Visual Content and Images in the Window} -\li \l{qtquick-usecase-userinput.html}{Responding to User Input} -\li \l{qtquick-usecase-animations.html}{Animating UI Elements} -\li \l{qtquick-usecase-text.html}{Formatting and Displaying Text} -\li \l{qtquick-usecase-layouts.html}{Complex Layouts} -\li \l{qtquick-usecase-styling.html}{Style and Theme: Look and Feel} -\li \l{qtquick-usecase-integratingjs.html}{Integrating with JavaScript} -\li \l{qtquick-usecase-integratingcpp.html}{Integrating with C++} -\li \l{qtquick-usecase-modules.html}{Creating Modules for QML} -\li \l{qtquick-usecase-multimedia.html}{Playing Sounds and Video in QML} -\endlist - -*/ - -/* -XXX - The "QML Intro" section has been temporarily removed, as it includes mostly outdated information. However, it has some pertinent information, so we should review it and extract the useful documentation at some point, for @@ -82,6 +54,22 @@ interfaces to any back-end C++ libraries. This page links to all the information you need to start developing applications with QML and QtQuick. +\section2 Other QML modules + +Qt Quick only provides basic visual types, much of Qt's functionality is exposed to QML +through other modules. If you require the functionality of those modules, you should browse +their QML documentation. Qt Essentials modules exposing QML types include: + +\list +\li \c Qt3D for 3D graphics rendering. +\li \c QtSensors for using device sensors such as accelerometers. +\li \c QtMultimedia for playing and managing multimedia content and cameras. +\li \c QtLocation for using GPS and mapping data. +\li \c QtSystems for reading system info and interacting with services. +\li \c QtWebkit for rendering web content. +\li \c QtPim for interacting with contact and calendar information. +\endlist + \section1 Quick Start \list @@ -99,6 +87,19 @@ applications with QML and QtQuick. \endlist \endlist +\section1 Features And Use-Case Solutions + +\list +\li \l{qtquick-usecase-visual.html}{Visual Elements in QML} +\li \l{qtquick-usecase-userinput.html}{Responding to User Input in QML} +\li \l{qtquick-usecase-animations.html}{Animations in QML} +\li \l{qtquick-usecase-text.html}{Displaying Text in QML} +\li \l{qtquick-usecase-layouts.html}{Layouts in QML} +\li \l{qtquick-usecase-styling.html}{Style and Theme Support} +\li \l{qtquick-usecase-integratingjs.html}{Integrating JavaScript in QML} +\endlist + + \section1 In-Depth Documentation \section2 What is QML? diff --git a/src/quick/doc/src/appdevguide/usecases/animations.qdoc b/src/quick/doc/src/appdevguide/usecases/animations.qdoc index 1ae5ac7816..905ed26a49 100644 --- a/src/quick/doc/src/appdevguide/usecases/animations.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/animations.qdoc @@ -28,4 +28,47 @@ \page qtquick-usecase-animations.html \title Usecase - Animations In QML \brief Example of how to include animations in QML applications + +QtQuick provides the ability to animate properties. Animating properties allows property values to move through +intermediate values instead of immediately changing to the target value. To animate the position of an item, you can +animate the properties that controle the item's position, x and y for example, so that the item's position +changes each frame on the way to the target position. + +\section1 Fluid UIs + +QML was designed to facilitate the creation of fluid UIs. These are user interfaces where the UI elements animate when +they move instead of elements appearing, disappearing, or jumping. Qt Quick provides two simple ways to have UI +elements move with animation instead of instantly appearing at their new location. + +\section2 States and Transitions + +QtQuick allows you to declare various UI states in \l State objects. These states are comprised of property changes from a +base state, and can be a useful way of organizing your UI logic. Transitions are objects you can associate with an item +to define how its properties will animate when they change due to a state change. + +States and transitions for an item can be declared with the \l Item::states and \l Item::transitions properties. +States are declared inside the states list property of an item, usually the root item of the component. Transitions +defined on the same item are used to animate the changes in the state. Here is an example. + +\snippet qml/usecases/animations.qml states + +\section2 Animating Property Changes. + +Behaviors can be used to specify an animation for a property to use when it changes. This is then applied to all +changes, regardless of their source. The following example animates a button moving around the +screen using behaviors. + +\snippet qml/usecases/animations.qml behave + +\section1 Other Animations + +Not all animations have to be tied to a specific property or state. You can also create animations more generally, and +specify target items and properties inside the animation. Here are some examples of different ways to do this: + +\snippet qml/usecases/animations.qml constant +\snippet qml/usecases/animations.qml scripted +\image qml-uses-animation.png + +More information about animations can be found on the \l{Important Concepts in Qt Quick - States, Transitions and +Animations} page. */ diff --git a/src/quick/doc/src/appdevguide/usecases/integratingcpp.qdoc b/src/quick/doc/src/appdevguide/usecases/integratingcpp.qdoc deleted file mode 100644 index 27bb40c131..0000000000 --- a/src/quick/doc/src/appdevguide/usecases/integratingcpp.qdoc +++ /dev/null @@ -1,31 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qtquick-usecase-integratingcpp.html -\title Use Case - Integrating C++ In QML Applications -\brief Example of how to integrate C++ within a QML application -*/ diff --git a/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc b/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc index 3a261a16d5..d4aef9b0cb 100644 --- a/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc @@ -26,6 +26,45 @@ ****************************************************************************/ /*! \page qtquick-usecase-integratingjs.html -\title Use Case - Integrating JavaScript In QML +\title Use Case - Integrating JavaScript in QML \brief Example of how to integrate JavaScript code in QML applications + +JavaScript code can be easily integrated into QML to provide UI logic, imperative control, or other benefits. + +\section1 Using JavaScript Expressions for Property Values + +JavaScript expressions can be used in QML as bindings. For example +\code +Item { + width: Math.random() + height: width < 100 ? 100 : (width + 50) / 2 +} +\endcode + +Note that function calls, like Math.random(), will not be revaluated unless their arguments +change. So binding to Math.random() will be one random number and not revaluated, but if the width is changed in some +other manner, the height binding will be reevaluated to take that into account. + +\section1 Adding JavaScript Functions in QML + +JavaScript functions can be declared on QML items, like in the below example. This allows you to call the method +using the item id. + +\snippet qml/usecases/integratingjs-inline.qml 0 + +\section1 Using JavaScript files + +JavaScript files can be used for abstracting out logic from QML files. To do this, first place your functions inside a +.js file like in the example shown. + +\snippet qml/usecases/myscript.js 0 + +Then import the file into any .qml file that needs to use the functions, like the example QML file below. + +\snippet qml/usecases/integratingjs.qml 0 + +\image qml-uses-integratingjs.png + +For further details on the JavaScript engine used by QML, as well as the difference from browser JS, see the full +documentation on \c {Using JavaScript Expressions with QML}. */ diff --git a/src/quick/doc/src/appdevguide/usecases/layouts.qdoc b/src/quick/doc/src/appdevguide/usecases/layouts.qdoc index a32b8b527f..cf059e9186 100644 --- a/src/quick/doc/src/appdevguide/usecases/layouts.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/layouts.qdoc @@ -28,4 +28,40 @@ \page qtquick-usecase-layouts.html \title Use Case - Layouts In QML \brief Example of how to create layouts for visual elements in a QML application + +There are several ways to position items in QML, including simple property bindings. + +\section1 Manual Positioning + +Items can be placed at specific x,y coordinates on the screen by setting their x,y properties. This will setup their +position relative to the top left corner of their parent, for more detail see \c {Visual Canvas}. + +Combined with using bindings instead of constant valudes for these properties, relative positioning is also easily +accomplished by setting the x and y coordinates to the appropriate bindings. + +\snippet qml/usecases/layouts.qml direct + +\section1 Anchors + +The \c Item type provides the abilitiy to anchor to other Item types. There are six anchor lines for each item: left, +right, vertical center, top, bottom and horizontal center. The three vertical anchor lines can be anchored to any of +the three vertical anchor lines of another item, and the three horizontal anchor lines can be anchored to the +horizontal anchor lines of another item. + +For full details, see the documentation of the \l{Item::anchors}{anchors property}. + +\snippet qml/usecases/layouts.qml anchors + +\section1 Positioners + +For the common case of wanting to position a set of elements in a regular pattern, QtQuick provides some Positioner +types. Items placed in a positioner are automatically positioned in some way, for example a Row positions items to be +horizontally adjacent (forming a row). + +For full details see the documentation for \l{qtquick-qmltypereference.html#positioning}{the positioner types}. + +\snippet qml/usecases/layouts.qml positioners + +\image qml-uses-layouts.png + */ diff --git a/src/quick/doc/src/appdevguide/usecases/modules.qdoc b/src/quick/doc/src/appdevguide/usecases/modules.qdoc deleted file mode 100644 index f453de1924..0000000000 --- a/src/quick/doc/src/appdevguide/usecases/modules.qdoc +++ /dev/null @@ -1,31 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qtquick-usecase-modules.html -\title Use Case - Extending QML With Modules -\brief Example of how to create a loadable QML extension module -*/ diff --git a/src/quick/doc/src/appdevguide/usecases/multimedia.qdoc b/src/quick/doc/src/appdevguide/usecases/multimedia.qdoc deleted file mode 100644 index 8af6987f4c..0000000000 --- a/src/quick/doc/src/appdevguide/usecases/multimedia.qdoc +++ /dev/null @@ -1,31 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qtquick-usecase-multimedia.html -\title Use Case - Playing Sound And Video In QML -\brief Example of how to play multimedia in a QML application -*/ diff --git a/src/quick/doc/src/appdevguide/usecases/styling.qdoc b/src/quick/doc/src/appdevguide/usecases/styling.qdoc index 4564e1cffd..9995249bcb 100644 --- a/src/quick/doc/src/appdevguide/usecases/styling.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/styling.qdoc @@ -27,5 +27,37 @@ /*! \page qtquick-usecase-styling.html \title Use Case - Style And Theme Support -\brief Example of how to style user-interface elements in QML +\brief Example of how to style user interface elements in QML + +The types provided in the QtQuick module are not complete user interface elements on their own. A common use case is to +develop a set of custom styled user interface elements out of the types in the QtQuick module. This is easily +accomplished by creating your own reusable components. + +With the reusable components approach, you define your own type with the appearance you want to have in your +application and style that type directly. You then use that type in your application instead of the unstyled type. For +example, you could create a MyText.qml which is a Text element with certain properties set by default, and use MyText +instead of Text elsewhere in your application. + +\section1 Example Themed Text +\section2 Button Definition +\snippet qml/usecases/MyText.qml 0 +\section2 Using the Text +\snippet qml/usecases/styling-text.qml texts +\image qml-uses-styling-text.png + +Because the root item in MyText.qml is a Text item it will behave as a +Text item, and the properties can be overriden in specific uses. However, the properties will be set to the values +specified in MyText when the item is first generated, thus applying your style by default. + +For pre-styled user interface elements, see the \c{Qt Components} add-on which provides a set of components. +For accessing the system theme, see the \l{SystemPalette} element documentation. + +\section1 Example Themed Button +\section2 Button Definition +\snippet qml/usecases/Button.qml 0 +\section2 Using the Button +\snippet qml/usecases/styling.qml 0 +\image qml-uses-styling.png + +For more examples of creating custom UI components in QML, see the tutorials. */ diff --git a/src/quick/doc/src/appdevguide/usecases/text.qdoc b/src/quick/doc/src/appdevguide/usecases/text.qdoc index 40b32d577d..2507df7c35 100644 --- a/src/quick/doc/src/appdevguide/usecases/text.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/text.qdoc @@ -28,4 +28,31 @@ \page qtquick-usecase-text.html \title Use Case - Displaying Text In QML \brief Example of how to display text in QML +To display text the Text type is provided by the QtQuick module. For related uses, the \l{TextInput} and +\l{TextEdit} types provide editable text controls. For full HTML markup, see the \c{QtWebkit} module. + +\section1 Displaying and Formatting Text + +To display text in QML, create a Text item and set the text property to the text you wish to display. The Text item +will now display that text. + +Several properties can be set on the Text item to style the entire block of text. These include color, font family, +font size, bold and italic. For a full list of properties, consult the \l{Text} type documentation. + +Rich text like markup can be used to selectively style specific sections of text with a Text item. Set \l +Text::textFormat to Text.StyledText to use this functionality. More details are available in the documentation of the +\l{Text} type. + +\section1 Laying out Text + +By default, Text will display the text as a single line unless it contains embedded newlines. To wrap the line, set the +wrapMode property and give the text an explicit width for it to wrap to. If the width or height is not explicitly set, +reading these properties will return the parameters of the bounding rect of the text (if you have explicitly set width +or height, you can still use paintedWidth and paintedHeight). With these parameters in mind, the Text can be positioned +like any other Item. + +\section1 Example Code +\snippet qml/usecases/text.qml 0 +\image qml-uses-text.png + */ diff --git a/src/quick/doc/src/appdevguide/usecases/userinput.qdoc b/src/quick/doc/src/appdevguide/usecases/userinput.qdoc index 212eff257d..c04b5f732b 100644 --- a/src/quick/doc/src/appdevguide/usecases/userinput.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/userinput.qdoc @@ -26,6 +26,58 @@ ****************************************************************************/ /*! \page qtquick-usecase-userinput.html -\title Use Case - Responding To User-Input In QML -\brief Example of how to accept user-input and respond to it in a QML application +\title Use Case - Responding To User Input in QML +\brief Example of how to accept user input and respond to it in a QML application + +\section1 Supported Types of User Input + +The \l QtQuick module provides support for the most common types of user input, +including mouse and touch events, text input and key-press events. Other +modules provide support for other types of user input (for example, the +\l QtSensors module provides support for shake-gestures in QML applications). + +This article covers how to handle basic user input; for further information +about motion-gesture support, please see the \l QtSensors documentation. For +information about audio-visual input, please see the \l QtMultimedia documentation. + +\section2 Mouse and Touch Events + +The \l MouseArea type allows mouse and touch events to be handled in a QML +application. A \l MouseArea can be combined with either an \l Image or a +\l Rectangle and \l Text object to implement a simple button. + +\snippet qml/usecases/userinput.qml 0 + +For more advanced use cases requiring multiple touch points, please read the +documentation for the \l MultiPointTouchArea element and the \l PinchArea element. + +Note that some elements have their own built in input handling. For example, +\l Flickable responds to mouse dragging, mouse wheel scrolling, touch dragging, +and touch flicking by default. + +\section2 Keyboard and Button Events + +Button and key presses, from buttons on a device, a keypad, or a keyboard, +can all be handled using the \l Keys attached property. This attached property +is available on all \l Item derived elements, and works with the \l Item::focus property +to determine which element receives the key event. For simple key handling, you can set the focus +to true on a single \l Item and do all your key handling there. + +\snippet qml/usecases/userinput-keys.qml 0 + +For text input the \l QtQuick module provides several built-in types. +In particular, the \l TextInput and \l TextEdit types allow for single-line +entry and multi-line editing respectively. + +Here is all you need to get a working TextInput: + +\code +import QtQuick 2.0 + +TextInput { + focus: true + text: "Initial Text" +} +\endcode + */ diff --git a/src/quick/doc/src/appdevguide/usecases/visual.qdoc b/src/quick/doc/src/appdevguide/usecases/visual.qdoc index 66244381e6..d63f944b50 100644 --- a/src/quick/doc/src/appdevguide/usecases/visual.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/visual.qdoc @@ -28,4 +28,58 @@ \page qtquick-usecase-visual.html \title Use Case - Visual Elements In QML \brief Example of how to display visual item types in a QML application + +\section1 The Rectangle Type + +For the most basic of visuals, QtQuick provides a \l Rectangle type to draw rectangles. These rectangles can be colored with a +color or a vertical gradient. The \l Rectangle type can also draw borders on the rectangle. + +For drawing custom shapes beyond rectangles, see the \l Canvas type or display +a pre-rendered image using the \l Image type. + +\snippet qml/usecases/visual-rects.qml 0 +\image qml-uses-visual-rectangles.png + +\section1 The Image Type + +QtQuick provides an \l Image type which may be used to display images. The +\l Image type has a \l source property whose value can be a remote or local +URL, or the URL of an image file embedded in a compiled resource file. + +\snippet qml/usecases/visual.qml image + +For more complex images there are other types similar to \l Image. +\l BorderImage draws an image with grid scaling, suitable for images used as +borders. \l AnimatedImage plays animated .gif and .mng images. \l AnimatedSprite +and \l SpriteSequence play animations comprised of multiple frames stored adjacently +in a non animated image format. + +For displaying video files and camera data, see the \l QtMultimedia module. + +\section1 Shared Visual Properties + +All visual items provided by the QtQuick are based on the Item type, which provides a common set of attributes for +visual items, including opacity and transform attributes. + +\section2 Opacity and Visibility + +The QML object types provided by Qt Quick have built-in support for \l{Item::opacity}{opacity}. +Opacity can be animated to allow smooth transitions to or from a transparent +state. Visibility can also be managed with the \l{Item::visible}{visible} property more efficiently, +but at the cost of not being able to animate it. + +\snippet qml/usecases/visual-opacity.qml 0 +\image qml-uses-visual-opacity.png + +\section2 Transforms + +Qt Quick types have built-in support for transformations. If you wish to have your +visual content rotated or scaled, you can set the \l Item::rotation or \l Item::scale +property. These can also be animated. + +\snippet qml/usecases/visual-transforms.qml 0 +\image qml-uses-visual-transforms.png + +For more complex transformations, see the \l Item::transform property. + */ |
