diff options
author | Jerome Pasion <jerome.pasion@nokia.com> | 2012-02-09 17:31:02 +0100 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2012-02-14 12:53:21 +0100 |
commit | 2d4e6ff9dd1e0e3410c4dc002c25d80fecfeafd2 (patch) | |
tree | b12aec803acf837024b4426526f1ce69cb3080ae /doc/src/examples/tutorial.qdoc | |
parent | d95178153a0f15991b2e6e91216dbcf5c0be2af3 (diff) |
Doc: Overhaul of doc/src/declarative and QtQuick2 docs.
-Consolidated model/view documentation into one.
-Added a new navigation for all overviews (grouped the pages)
-New front page that shows the grouping
-Separated the Qt C++ from the main QML overviews
-Consolidated Qt C++ into the "declarative runtime" section
-New articles about JavaScript, the engine, and plugins
-Fixed the older examples. New snippet comments
-Renamed some of the articles
-kept the qtquick2 qmlmodule
-"Qt Quick Elements"
Moved contents of doc/src/declarative into respective
module dirs.
-Qt Quick 2, LocalStorage, Particles, and QML are now
separate.
-Removed unused or duplicate documentation.
-edited C++ examples
-removed navigation and "\inqmlmodule QtQuick 2" for
those pages that are not in Qt Quick 2
-fixed doc/src/ licenses to header.FDL from qtbase
Change-Id: Ib36f9c07565d91160fa8d04f9670c438f684b82a
Reviewed-by: Sergio Ahumada <sergio.ahumada@nokia.com>
Diffstat (limited to 'doc/src/examples/tutorial.qdoc')
-rw-r--r-- | doc/src/examples/tutorial.qdoc | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/doc/src/examples/tutorial.qdoc b/doc/src/examples/tutorial.qdoc new file mode 100644 index 0000000000..9042b5e3d8 --- /dev/null +++ b/doc/src/examples/tutorial.qdoc @@ -0,0 +1,232 @@ +/**************************************************************************** +** +** 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 qml-tutorial.html +\inqmlmodule QtQuick 2 +\title QML Tutorial +\brief An introduction to the basic concepts and features of QML. +\previouspage Introduction to the QML Language +\nextpage QML Tutorial 1 - Basic Types + +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 is located in the $QTDIR/examples/declarative/tutorials/helloworld directory. + +Tutorial chapters: + +\list 1 +\o \l {QML Tutorial 1 - Basic Types}{Basic Types} +\o \l {QML Tutorial 2 - QML Components}{QML Components} +\o \l {QML Tutorial 3 - States and Transitions}{States and Transitions} +\endlist + +*/ + +/*! +\page qml-tutorial1.html +\inqmlmodule QtQuick 2 +\title QML Tutorial 1 - Basic Types +\contentspage QML Tutorial +\previouspage QML Tutorial +\nextpage QML Tutorial 2 - QML Component + +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. + +\image declarative-tutorial1.png + +Here is the QML code for the application: + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 0 + +\section1 Walkthrough + +\section2 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 \l{Rectangle}, \l{Image}, ...) that come with Qt, using: + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 3 + +\section2 Rectangle element + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 1 + +We declare a root element of type \l{Rectangle}. It is one of the basic building blocks you can use to create an application in QML. +We give it an \c{id} to be able to refer to it later. In this case, we call it "page". +We also set the \c width, \c height and \c color properties. +The \l{Rectangle} element contains many other properties (such as \c x and \c y), but these are left at their default values. + +\section2 Text element + +\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 2 + +We add a \l Text element as a child of the root Rectangle element that displays the text 'Hello world!'. + +The \c y property is used to position the text vertically at 30 pixels from the top of its parent. + +The \c 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 \i page element (see \l{anchor-layout}{Anchor-Based Layout}). + +The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}. + + +\section2 Viewing the example + +To view what you have created, run the \l{QML Viewer} tool (located in the \c bin directory) with your filename as the first argument. +For example, to run the provided completed Tutorial 1 example from the install location, you would type: + +\code +bin/qmlviewer $QTDIR/examples/declarative/tutorials/helloworld/tutorial1.qml +\endcode +*/ + +/*! +\page qml-tutorial2.html +\inqmlmodule QtQuick 2 +\title QML Tutorial 2 - QML Components +\contentspage QML Tutorial +\previouspage QML Tutorial 1 - Basic Types +\nextpage QML Tutorial 3 - States and Transitions + +This chapter adds a color picker to change the color of the text. + +\image declarative-tutorial2.png + +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 \c 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. (For more details, see \l {Defining New Components}). +The component's filename must always start with a capital letter. + +Here is the QML code for \c Cell.qml: + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 0 + +\section1 Walkthrough + +\section2 The Cell Component + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 1 + +The root element of our component is an \l Item with the \c id \i container. +An \l Item is the most basic visual element in QML and is often used as a container for other elements. + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 4 + +We declare a \c cellColor property. This property is accessible from \i 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 +(see \l{Property Binding in QML}). + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 5 + +We want our component to also have a signal that we call \i clicked with a \i cellColor parameter of type \i color. +We will use this signal to change the color of the text in the main QML file later. + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 2 + +Our cell component is basically a colored rectangle with the \c id \i rectangle. + +The \c 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 (see \l{anchor-layout}{Anchor-Based Layout}). + +\snippet examples/declarative/tutorials/helloworld/Cell.qml 3 + +In order to change the color of the text when clicking on a cell, we create a \l MouseArea element with +the same size as its parent. + +A \l MouseArea defines a signal called \i clicked. +When this signal is triggered we want to emit our own \i clicked signal with the color as parameter. + +\section2 The main QML file + +In our main QML file, we use our \c Cell component to create the color picker: + +\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 0 + +We create the color picker by putting 6 cells with different colors in a grid. + +\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 1 + +When the \i clicked signal of our cell is triggered, we want to set the color of the text to the \i cellColor passed as a parameter. +We can react to any signal of our component through a property of the name \i 'onSignalName' (see \l{Signal Handlers}). +*/ + +/*! +\page qml-tutorial3.html +\inqmlmodule QtQuick 2 +\title QML Tutorial 3 - States and Transitions +\contentspage QML Tutorial +\previouspage QML Tutorial 2 - QML Component + +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. + +\image declarative-tutorial3_animation.gif + +Here is the QML code: + +\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 0 + +\section1 Walkthrough + +\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 2 + +First, we create a new \i down state for our text element. +This state will be activated when the \l MouseArea is pressed, and deactivated when it is released. + +The \i down state includes a set of property changes from our implicit \i {default state} +(the items as they were initially defined in the QML). +Specifically, we set the \c y property of the text to \c 160, the rotation to \c 180 and the \c color to red. + +\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 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. + +\c from and \c to define the states between which the transition will run. +In this case, we want a transition from the default state to our \i down state. + +Because we want the same transition to be run in reverse when changing back from the \i down state to the default state, +we set \c reversible to \c true. +This is equivalent to writing the two transitions separately. + +The \l 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 \l SequentialAnimation instead. + +For more details on states and transitions, see \l {QML States} and the \l{declarative/animation/states}{states and transitions example}. +*/ |