diff options
Diffstat (limited to 'doc/tutorials/qmltutorial')
-rw-r--r-- | doc/tutorials/qmltutorial/declarative-tutorial1.png | bin | 0 -> 3577 bytes | |||
-rw-r--r-- | doc/tutorials/qmltutorial/declarative-tutorial2.png | bin | 0 -> 3913 bytes | |||
-rw-r--r-- | doc/tutorials/qmltutorial/declarative-tutorial3_animation.gif | bin | 0 -> 301974 bytes | |||
-rw-r--r-- | doc/tutorials/qmltutorial/helloworld.tar.bz2 | bin | 0 -> 2401 bytes | |||
-rw-r--r-- | doc/tutorials/qmltutorial/helloworld/Cell.qml | 72 | ||||
-rw-r--r-- | doc/tutorials/qmltutorial/helloworld/tutorial1.qml | 63 | ||||
-rw-r--r-- | doc/tutorials/qmltutorial/helloworld/tutorial2.qml | 72 | ||||
-rw-r--r-- | doc/tutorials/qmltutorial/helloworld/tutorial3.qml | 91 | ||||
-rw-r--r-- | doc/tutorials/qmltutorial/index.rst | 25 | ||||
-rw-r--r-- | doc/tutorials/qmltutorial/step1.rst | 66 | ||||
-rw-r--r-- | doc/tutorials/qmltutorial/step2.rst | 81 | ||||
-rw-r--r-- | doc/tutorials/qmltutorial/step3.rst | 47 |
12 files changed, 517 insertions, 0 deletions
diff --git a/doc/tutorials/qmltutorial/declarative-tutorial1.png b/doc/tutorials/qmltutorial/declarative-tutorial1.png Binary files differnew file mode 100644 index 000000000..c9d3844cb --- /dev/null +++ b/doc/tutorials/qmltutorial/declarative-tutorial1.png diff --git a/doc/tutorials/qmltutorial/declarative-tutorial2.png b/doc/tutorials/qmltutorial/declarative-tutorial2.png Binary files differnew file mode 100644 index 000000000..835484aa4 --- /dev/null +++ b/doc/tutorials/qmltutorial/declarative-tutorial2.png diff --git a/doc/tutorials/qmltutorial/declarative-tutorial3_animation.gif b/doc/tutorials/qmltutorial/declarative-tutorial3_animation.gif Binary files differnew file mode 100644 index 000000000..80b78dea9 --- /dev/null +++ b/doc/tutorials/qmltutorial/declarative-tutorial3_animation.gif diff --git a/doc/tutorials/qmltutorial/helloworld.tar.bz2 b/doc/tutorials/qmltutorial/helloworld.tar.bz2 Binary files differnew file mode 100644 index 000000000..001a5258d --- /dev/null +++ b/doc/tutorials/qmltutorial/helloworld.tar.bz2 diff --git a/doc/tutorials/qmltutorial/helloworld/Cell.qml b/doc/tutorials/qmltutorial/helloworld/Cell.qml new file mode 100644 index 000000000..76055abf3 --- /dev/null +++ b/doc/tutorials/qmltutorial/helloworld/Cell.qml @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples 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 1.0 + +//![1] +Item { + id: container +//![4] + property alias cellColor: rectangle.color +//![4] +//![5] + signal clicked(color cellColor) +//![5] + + width: 40; height: 25 +//![1] + +//![2] + Rectangle { + id: rectangle + border.color: "white" + anchors.fill: parent + } +//![2] + +//![3] + MouseArea { + anchors.fill: parent + onClicked: container.clicked(container.cellColor) + } +//![3] +} +//![0] diff --git a/doc/tutorials/qmltutorial/helloworld/tutorial1.qml b/doc/tutorials/qmltutorial/helloworld/tutorial1.qml new file mode 100644 index 000000000..83b57b8f6 --- /dev/null +++ b/doc/tutorials/qmltutorial/helloworld/tutorial1.qml @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples 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] +//![3] +import QtQuick 1.0 +//![3] + +//![1] +Rectangle { + id: page + width: 500; height: 200 + color: "lightgray" +//![1] + +//![2] + Text { + id: helloText + text: "Hello world!" + y: 30 + anchors.horizontalCenter: page.horizontalCenter + font.pointSize: 24; font.bold: true + } +//![2] +} +//![0] diff --git a/doc/tutorials/qmltutorial/helloworld/tutorial2.qml b/doc/tutorials/qmltutorial/helloworld/tutorial2.qml new file mode 100644 index 000000000..1bfab92fe --- /dev/null +++ b/doc/tutorials/qmltutorial/helloworld/tutorial2.qml @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples 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 1.0 + +Rectangle { + id: page + width: 500; height: 200 + color: "lightgray" + + Text { + id: helloText + text: "Hello world!" + y: 30 + anchors.horizontalCenter: page.horizontalCenter + font.pointSize: 24; font.bold: true + } + + Grid { + id: colorPicker + x: 4; anchors.bottom: page.bottom; anchors.bottomMargin: 4 + rows: 2; columns: 3; spacing: 3 + +//![1] + Cell { cellColor: "red"; onClicked: helloText.color = cellColor } +//![1] + Cell { cellColor: "green"; onClicked: helloText.color = cellColor } + Cell { cellColor: "blue"; onClicked: helloText.color = cellColor } + Cell { cellColor: "yellow"; onClicked: helloText.color = cellColor } + Cell { cellColor: "steelblue"; onClicked: helloText.color = cellColor } + Cell { cellColor: "black"; onClicked: helloText.color = cellColor } + } +} +//![0] diff --git a/doc/tutorials/qmltutorial/helloworld/tutorial3.qml b/doc/tutorials/qmltutorial/helloworld/tutorial3.qml new file mode 100644 index 000000000..cc0686555 --- /dev/null +++ b/doc/tutorials/qmltutorial/helloworld/tutorial3.qml @@ -0,0 +1,91 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples 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 1.0 + +Rectangle { + id: page + width: 500; height: 200 + color: "lightgray" + + Text { + id: helloText + text: "Hello world!" + y: 30 + anchors.horizontalCenter: page.horizontalCenter + font.pointSize: 24; font.bold: true + +//![1] + MouseArea { id: mouseArea; anchors.fill: parent } +//![1] + +//![2] + states: State { + name: "down"; when: mouseArea.pressed == true + PropertyChanges { target: helloText; y: 160; rotation: 180; color: "red" } + } +//![2] + +//![3] + transitions: Transition { + from: ""; to: "down"; reversible: true + ParallelAnimation { + NumberAnimation { properties: "y,rotation"; duration: 500; easing.type: Easing.InOutQuad } + ColorAnimation { duration: 500 } + } + } +//![3] + } + + Grid { + id: colorPicker + x: 4; anchors.bottom: page.bottom; anchors.bottomMargin: 4 + rows: 2; columns: 3; spacing: 3 + + Cell { cellColor: "red"; onClicked: helloText.color = cellColor } + Cell { cellColor: "green"; onClicked: helloText.color = cellColor } + Cell { cellColor: "blue"; onClicked: helloText.color = cellColor } + Cell { cellColor: "yellow"; onClicked: helloText.color = cellColor } + Cell { cellColor: "steelblue"; onClicked: helloText.color = cellColor } + Cell { cellColor: "black"; onClicked: helloText.color = cellColor } + } +} +//![0] diff --git a/doc/tutorials/qmltutorial/index.rst b/doc/tutorials/qmltutorial/index.rst new file mode 100644 index 000000000..35cda3170 --- /dev/null +++ b/doc/tutorials/qmltutorial/index.rst @@ -0,0 +1,25 @@ + +.. _qmltutorial: + +QML Tutorial +************ + +This tutorial gives an introduction to QML, the mark up language for Qt Quick. It doesn't cover everything; +the emphasis is on teaching the key principles, and features are introduced as needed. + +Through the different steps of this tutorial we will learn about QML basic types, we will create our own QML component +with properties and signals, and we will create a simple animation with the help of states and transitions. + +Chapter one starts with a minimal "Hello world" program and the following chapters introduce new concepts. + +The tutorial's source code can be downloaded :download:`here<helloworld.tar.bz2>`. + +Tutorial chapters: + +.. toctree:: + :maxdepth: 1 + + step1.rst + step2.rst + step3.rst + diff --git a/doc/tutorials/qmltutorial/step1.rst b/doc/tutorials/qmltutorial/step1.rst new file mode 100644 index 000000000..02a1095bc --- /dev/null +++ b/doc/tutorials/qmltutorial/step1.rst @@ -0,0 +1,66 @@ +.. _qmlbasictypes: + +QML Tutorial 1 - Basic Types +**************************** + +This first program is a very simple "Hello world" example that introduces some basic QML concepts. +The picture below is a screenshot of this program. + +.. figure:: declarative-tutorial1.png + :align: center + +Here is the QML code for the application: + +.. pysideinclude:: helloworld/tutorial1.qml + :snippet: 0 + +Walkthrough +=========== + +Import +------ + +First, we need to import the types that we need for this example. Most QML files will import the built-in QML +types (like Rectangle, Image, ...) that come with Qt, using: + +.. pysideinclude:: helloworld/tutorial1.qml + :snippet: 3 + +Rectangle element +----------------- + +.. pysideinclude:: helloworld/tutorial1.qml + :snippet: 1 + +We declare a root element of type Rectangle. It is one of the basic building blocks you can use to create an application in QML. +We give it an ``id`` to be able to refer to it later. In this case, we call it "page". +We also set the ``width``, ``height`` and ``color`` properties. +The Rectangle element contains many other properties (such as ``x`` and ``y``), but these are left at their default values. + +Text element +------------ + +.. pysideinclude code/tutorial1.qml + :snippet: 2 + +We add a Text element as a child of the root Rectangle element that displays the text 'Hello world!'. + +The ``y`` property is used to position the text vertically at 30 pixels from the top of its parent. + +The ``anchors.horizontalCenter`` property refers to the horizontal center of an element. +In this case, we specify that our text element should be horizontally centered in the *page* element. + +The ``font.pointSize`` and ``font.bold properties`` are related to fonts and use the dot notation. + + +Viewing the example +------------------- + +To view what you have created, run the QML Viewer tool (located in the ``bin directory`` of your Qt installation) with your filename as the first argument. +For example, to run the provided completed Tutorial 1 example from the install location, you would type: + +:: + + bin/qmlviewer tutorial1.qml + +[Previous :ref:`qmltutorial`][Next :ref:`qmlcomponents`] diff --git a/doc/tutorials/qmltutorial/step2.rst b/doc/tutorials/qmltutorial/step2.rst new file mode 100644 index 000000000..4dacd00a9 --- /dev/null +++ b/doc/tutorials/qmltutorial/step2.rst @@ -0,0 +1,81 @@ +.. _qmlcomponents: + +QML Tutorial 2 - QML Components +******************************* + +This chapter adds a color picker to change the color of the text. + +.. figure:: declarative-tutorial2.png + :align: center + +Our color picker is made of six cells with different colors. +To avoid writing the same code multiple times for each cell, we create a new ``Cell`` component. +A component provides a way of defining a new type that we can re-use in other QML files. +A QML component is like a black-box and interacts with the outside world through properties, signals and functions and is generally +defined in its own QML file. +The component's filename must always start with a capital letter. + +Here is the QML code for ``Cell.qml``: + +.. pysideinclude:: helloworld/Cell.qml + :snippet: 0 + +Walkthrough +=========== + +The Cell Component +------------------ + +.. pysideinclude:: helloworld/Cell.qml + :snippet: 1 + +The root element of our component is an Item with the ``id`` *container*. +An Item is the most basic visual element in QML and is often used as a container for other elements. + +.. pysideinclude:: helloworld/Cell.qml + :snippet: 4 + +We declare a ``cellColor`` property. This property is accessible from *outside* our component, this allows us +to instantiate the cells with different colors. +This property is just an alias to an existing property - the color of the rectangle that compose the cell. + +.. pysideinclude:: helloworld/Cell.qml + :snippet: 5 + +We want our component to also have a signal that we call *clicked* with a *cellColor* parameter of type *color*. +We will use this signal to change the color of the text in the main QML file later. + +.. pysideinclude:: helloworld/Cell.qml + :snippet: 2 + +Our cell component is basically a colored rectangle with the ``id`` *rectangle*. + +The ``anchors.fill`` property is a convenient way to set the size of an element. +In this case the rectangle will have the same size as its parent. + +.. pysideinclude:: helloworld/Cell.qml + :snippet: 3 + +In order to change the color of the text when clicking on a cell, we create a MouseArea element with +the same size as its parent. + +A MouseArea defines a signal called *clicked*. +When this signal is triggered we want to emit our own *clicked* signal with the color as parameter. + +The main QML file +----------------- + +In our main QML file, we use our ``Cell`` component to create the color picker: + +.. pysideinclude:: helloworld/tutorial2.qml + :snippet: 0 + +We create the color picker by putting 6 cells with different colors in a grid. + +.. pysideinclude:: helloworld/tutorial2.qml + :snippet: 1 + +When the *clicked* signal of our cell is triggered, we want to set the color of the text to the *cellColor* passed as a parameter. +We can react to any signal of our component through a property of the name *'onSignalName'*. + +[Previous :ref:`qmlbasictypes`][Next :ref:`qmlstatesandtransitions`] diff --git a/doc/tutorials/qmltutorial/step3.rst b/doc/tutorials/qmltutorial/step3.rst new file mode 100644 index 000000000..a72d1eac0 --- /dev/null +++ b/doc/tutorials/qmltutorial/step3.rst @@ -0,0 +1,47 @@ +.. _qmlstatesandtransitions: + +QML Tutorial 3 - States and Transitions +*************************************** + +In this chapter, we make this example a little bit more dynamic by introducing states and transitions. + +We want our text to move to the bottom of the screen, rotate and become red when clicked. + +.. figure:: declarative-tutorial3_animation.gif + :align: center + +Here is the QML code: + +.. pysideinclude:: helloworld/tutorial3.qml + :snippet: 0 + +Walkthrough +=========== + +.. pysideinclude:: helloworld/tutorial3.qml + :snippet: 2 + +First, we create a new *down* state for our text element. +This state will be activated when the MouseArea is pressed, and deactivated when it is released. + +The *down* state includes a set of property changes from our implicit *default state* +(the items as they were initially defined in the QML). +Specifically, we set the ``y`` property of the text to ``160``, the rotation to ``180`` and the ``color`` to red. + +.. pysideinclude:: helloworld/tutorial3.qml + :snippet: 3 + +Because we don't want the text to appear at the bottom instantly but rather move smoothly, +we add a transition between our two states. + +``from`` and ``to`` define the states between which the transition will run. +In this case, we want a transition from the default state to our *down* state. + +Because we want the same transition to be run in reverse when changing back from the *down* state to the default state, +we set ``reversible`` to ``true``. +This is equivalent to writing the two transitions separately. + +The ParallelAnimation element makes sure that the two types of animations (number and color) start at the same time. +We could also run them one after the other by using SequentialAnimation instead. + +[Previous :ref:`qmlcomponents`] |