From: Chris Adams Date: Tue, 10 Jul 2012 04:32:17 +0000 (+1000) Subject: Add quick-start documentation to QML/QtQuick AppDevGuide X-Git-Tag: upstream/5.2.1~1430 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=9bc216f6fa34484bf582cbc3ccd2bb7b45826bc7;p=platform%2Fupstream%2Fqtdeclarative.git Add quick-start documentation to QML/QtQuick AppDevGuide This commit adds basic introductory information about QML to the application developer guide. Task-number: QTBUG-26427 Change-Id: I2fb313b8dec180988ef81c71579348b60e1d6962 Reviewed-by: Michael Brasser --- diff --git a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc index 041dda8..0253c00 100644 --- a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc +++ b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc @@ -28,31 +28,13 @@ /* XXX -These sections have been temporarily removed from the -"QML Application Developer Resources" page as we do not have any content -for them yet. +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-26427 and QTBUG-26428 - - -\section1 Quick Start - -\list -\li \l{qtquick-quickstart-basics.html}{QML Basics} - \list - \li \l{qtquick-quickstart-basics.html#creating-a-qml-document}{Creating A QML Document} - \li \l{qtquick-quickstart-basics.html#importing-and-using-the-qtquick-module}{Importing And Using The QtQuick Module} - \li \l{qtquick-quickstart-basics.html#loading-and-displaying-the-qml-document}{Loading And Displaying The QML Document} - \endlist -\li \l{qtquick-quickstart-essentials.html}{QML Essentials} - \list - \li \l{qtquick-quickstart-essentials.html#bindings-and-signals}{Bindings And Signals} - \li \l{qtquick-quickstart-essentials.html#handling-user-input}{Handling User Input} - \li \l{qtquick-quickstart-essentials.html#defining-custom-qml-types-for-re-use}{Defining Custom QML Types For Re-use} - \endlist -\endlist +See QTBUG-26428 \section1 Features And Use-Case Solutions @@ -103,6 +85,22 @@ documentation for the \l{qtquick-main.html}{Qt Quick Module Documentation} for i information about the various QML types and other functionality provided by Qt Quick.} +\section1 Quick Start + +\list +\li \l{qtquick-quickstart-basics.html}{QML Basics} + \list + \li \l{qtquick-quickstart-basics.html#creating-a-qml-document}{Creating A QML Document} + \li \l{qtquick-quickstart-basics.html#loading-and-displaying-the-qml-document}{Loading And Displaying The QML Document} + \endlist +\li \l{qtquick-quickstart-essentials.html}{QML Essentials} + \list + \li \l{qtquick-quickstart-essentials.html#handling-user-input}{Handling User Input} + \li \l{qtquick-quickstart-essentials.html#property-bindings-and-animations}{Property Bindings And Animations} + \li \l{qtquick-quickstart-essentials.html#defining-custom-qml-types-for-re-use}{Defining Custom QML Types For Re-use} + \endlist +\endlist + \section1 Important Application Development Topics \list diff --git a/src/quick/doc/src/appdevguide/quickstart/basics.qdoc b/src/quick/doc/src/appdevguide/quickstart/basics.qdoc index 48942a5..7f63d53 100644 --- a/src/quick/doc/src/appdevguide/quickstart/basics.qdoc +++ b/src/quick/doc/src/appdevguide/quickstart/basics.qdoc @@ -31,8 +31,89 @@ \section1 Creating A QML Document -\section1 Importing And Using The QtQuick Module +A QML document defines a hierarchy of objects with a highly-readable, +structured layout. Every QML document consists of two parts: an imports +section and an object declaration section. The types and functionality most +common to user interfaces are provided in the \l{Qt Quick Module}{QtQuick} +import. + +\section2 Importing And Using The QtQuick Module + +To use the \l{Qt Quick Module}{QtQuick} module, a QML document needs to +import it. The import syntax looks like this: + +\qml +import QtQuick 2.0 +\endqml + +The types and functionality that \l{Qt Quick Module}{QtQuick} provides can now +be used in the QML document! + +\section2 Defining An Object Hierarchy + +The object declaration in a QML document defines what will be displayed in the +visual scene. \l{Qt Quick Module}{QtQuick} provides the basic building blocks +for all user interfaces, including objects to display images and text, and to +handle user input. + +A simple object declaration might be a colored rectangle with some text centered +in it: + +\qml +Rectangle { + width: 200 + height: 100 + color: "red" + + Text { + anchors.centerIn: parent + text: "Hello, World!" + } +} +\endqml + +This defines an object hierarchy with a root \l Rectangle object +which has a child \l Text object. The \c parent of the \l Text object is +automatically set to the \l Rectangle, and similarly, the \l Text object is +added to the \c children property of the \l Rectangle object, by QML. + +\section2 Putting It Together + +The \l Rectangle and \l Text types used in the above example are both provided +by the \l{Qt Quick Module}{QtQuick} import. To use them, we need to import +\l{Qt Quick Module}{QtQuick}. Putting the import and object declaration +together, we get a complete QML document: + +\qml +import QtQuick 2.0 + +Rectangle { + width: 200 + height: 100 + color: "red" + + Text { + anchors.centerIn: parent + text: "Hello, World!" + } +} +\endqml + +If we save that document as "HelloWorld.qml" we can load and display it. \section1 Loading And Displaying The QML Document +To display the graphical scene defined by the QML document, it may be loaded +with the \l{Protoyping with qmlscene}{qmlscene} tool. The +\l{Protoyping with qmlscene}{qmlscene} tool should be installed into the +Qt installation directory. Assuming that the Qt binaries are installed into +or are available in the system executable path, you can display the QML +document with the following command: + +\code +qmlscene HelloWorld.qml +\endcode + +You should see the text "Hello, World!" in the center of a red rectangle. + */ diff --git a/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc b/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc index 3ab0d0c..8219bd4 100644 --- a/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc +++ b/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc @@ -29,13 +29,162 @@ \title Quick Start Guide - QML Essentials \brief Essential QML application development examples -\section1 Bindings And Signals - \section1 Handling User Input +One of the great advantages of using QML to define a user interface is that it +allows the user interface designer to define how the application should react +to events with simple JavaScript expressions. In QML, we refer to those events +as \l{Signal and Handler Event System}{signals} and such signals can be handled +with \l{qml-signals-and-handlers}{signal handlers}. + +For example, consider the following example: +\qml +import QtQuick 2.0 + +Rectangle { + width: 200 + height: 100 + color: "red" + + Text { + anchors.centerIn: parent + text: "Hello, World!" + } + + MouseArea { + anchors.fill: parent + onClicked: parent.color = "blue" + } +} +\endqml + +This example can be saved as "ClickableHelloWorld.qml" and run with qmlscene. +Whenever the user clicks anywhere in the window, the rectangle will change +from red to blue. Note that the \l MouseArea type also emits the clicked +signal for touch events, so this code will also work on a mobile device. + +Keyboard user input can be similarly handled with a simple expression: + +\qml +import QtQuick 2.0 + +Rectangle { + width: 200 + height: 100 + color: "red" + + Text { + anchors.centerIn: parent + text: "Hello, World!" + } + + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_Return) { + color = "blue"; + event.accepted = true; + } + } +} +\endqml + +By accepting focus, the color can be changed to blue whenever the return key +is pressed. + +\section1 Property Bindings + +Objects and their properties form the basis of a graphical interface defined +in a QML document. The QML language allows properties to be bound to each +other in various ways, enabling highly dynamic user interfaces. + +In the following example, the geometry of each child \l Rectangle is bound to +that of the parent \l Rectangle. If the geometry of the parent \l Rectangle +were to change, the geometry of each child \l Rectangle would automatically +update due to the property bindings. + +\qml +import QtQuick 2.0 + +Rectangle { + width: 400 + height: 200 + + Rectangle { + width: parent.width / 2 + height: parent.height + } + + Rectangle { + width: parent.width / 2 + height: parent.height + x: parent.width / 2 + } +} +\endqml + +\section1 Animations + +Properties can also be dynamically updated via animations. The \c QtQuick +import provides various animation types which can be used to animate changes +to a property's value. In the following example, a property is animated which +then gets displayed in a \l Text area: + +\qml +import QtQuick 2.0 + +Rectangle { + color: "lightgray" + width: 200 + height: 200 + + property int animatedValue: 0 + SequentialAnimation on animatedValue { + loops: Animation.Infinite + PropertyAnimation { to: 150; duration: 1000 } + PropertyAnimation { to: 0; duration: 1000 } + } + + Text { + anchors.centerIn: parent + text: animatedValue + } +} +\endqml + +The value being displayed will vary from 0 to 150 periodically. + \section1 Defining Custom QML Types For Re-use +One of the most important concepts in QML is that of type re-use. An +application will probably have multiple visual elements which are all similar +(for example, multiple push buttons), and QML allows these sort of things to +be defined as re-usable, custom types, to minimize code duplication and +maximize readability. + +For example, imagine that the developer defines a new \c Button type in the +\c Button.qml file: + +\snippet qml/qml-extending-types/components/Button.qml 0 + +That type may now be re-used multiple times in the application, as follows: + +\table +\row +\li \snippet qml/qml-extending-types/components/application.qml 0 +\li \image qml-extending-types.png +\endtable + + +In this way, modular user interface elements can be built up and re-used within +an application. + +The Qt Quick Desktop Components project provides the most commonly used +user interface elements (such as buttons, lists, scrollers, tabbed screens, and +so forth) for both commercial and open-source use. Please see the +Qt Quick Desktop Components home page on the Qt Project website for more +information on how to use these components in applications. + See \l{qtquick-appdevguide-components.html}{Defining Resuable Components} -for more details. +for more details on how to develop your own reusable components. */