diff options
Diffstat (limited to 'src/quick/doc/src/appdevguide')
22 files changed, 3856 insertions, 0 deletions
diff --git a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc new file mode 100644 index 0000000000..2b172ef2d6 --- /dev/null +++ b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc @@ -0,0 +1,110 @@ +/**************************************************************************** +** +** 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-applicationdevelopers.html +\title QML Application Developer Resources +\brief Essential documentation for QML application developers + +\section1 Overview Of QML and Qt Quick + +\section2 What Is QML? + +QML is a user-interface specification and programming language. +It allows highly performant, fluidly animated, visually appealing applications +to be rapidly developed by either developers or designers. QML offers a +highly-readable, declarative, JSON-like syntax with support for imperative +JavaScript expressions combined with dynamic property bindings. + +\section2 What Is Qt Quick? + +Qt Quick is the standard library of types and functionality for QML. It +includes visual elements, interactive elements, animations, models and views, +particle effects and shader effects. A QML application developer can get +access to all of that functionality with a single import statement. + +\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 + +\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 + +\section1 Important Application Development Topics + +\list +\li \l{qml-intro.html}{Introduction To QML Application Development} +\li \l{qtquick-performance.html}{Performance Considerations And Suggestions} +\li \l{qtquick-internationalization.html}{Internationalization And Localization} +\li \l{qtquick-glossary.html}{Glossary Of Terms} +\endlist + + +\section1 Testing and Debugging +\list +\li \l{qtquick-qmlscene.html}{Prototyping with qmlscene} +\li \l{qtquick-debugging.html}{Debugging QML Applications} +\li \l{qtquick-qtquicktest.html}{QtQuickTest: QML Unit Testing Framework} +\endlist + +\section1 Further Information About The QML Language + +Please see the documentation for the \l{qtqml-main.html}{Qt QML Module} for +in-depth information about QML documents and the QML language. + +\section1 Further Information About Qt Quick + +Please see the documentation for the \l{qtquick-main.html}{Qt Quick Module} +for in-depth information about the various QML types and other functionality +provided by Qt Quick. + +*/ + diff --git a/src/quick/doc/src/appdevguide/codingconventions.qdoc b/src/quick/doc/src/appdevguide/codingconventions.qdoc new file mode 100644 index 0000000000..89a1bd8cb3 --- /dev/null +++ b/src/quick/doc/src/appdevguide/codingconventions.qdoc @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** 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-coding-conventions.html +\title QML Coding Conventions +\brief code style convention + +This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow. + +\section1 QML Objects + +Through our documentation and examples, QML objects are always structured in the following order: + +\list +\li id +\li property declarations +\li signal declarations +\li JavaScript functions +\li object properties +\li child objects +\li states +\li transitions +\endlist + +For better readability, we separate these different parts with an empty line. + + +For example, a hypothetical \e photo QML object would look like this: + +\snippet qml/codingconventions/photo.qml 0 + + +\section1 Grouped Properties + +If using multiple properties from a group of properties, +we use the \e {group notation} rather than the \e {dot notation} to improve readability. + +For example, this: + +\snippet qml/codingconventions/dotproperties.qml 0 + +can be written like this: + +\snippet qml/codingconventions/dotproperties.qml 1 + + +\section1 Private Properties + +QML and JavaScript do not enforce private properties like C++. There is a need +to hide these private properties, for example, when the properties are part of +the implementation. As a convention, private properties begin with two +\e underscore characters. For example, \c __area, is a property that is +accessible but is not meant for public use. Note that QML and JavaScript will +grant the user access to these properties. + +\snippet qml/codingconventions/private.qml 0 + + +\section1 Lists + +If a list contains only one element, we generally omit the square brackets. + +For example, it is very common for a component to only have one state. + +In this case, instead of: + +\snippet qml/codingconventions/lists.qml 0 + +we will write this: + +\snippet qml/codingconventions/lists.qml 1 + + +\section1 JavaScript Code + +If the script is a single expression, we recommend writing it inline: + +\snippet qml/codingconventions/javascript.qml 0 + +If the script is only a couple of lines long, we generally use a block: + +\snippet qml/codingconventions/javascript.qml 1 + +If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this: + +\snippet qml/codingconventions/javascript.qml 2 + +For long scripts, we will put the functions in their own JavaScript file and import it like this: + +\snippet qml/codingconventions/javascript-imports.qml 0 + +*/ + + + + + + + + + diff --git a/src/quick/doc/src/appdevguide/debugging.qdoc b/src/quick/doc/src/appdevguide/debugging.qdoc new file mode 100644 index 0000000000..d0b239427b --- /dev/null +++ b/src/quick/doc/src/appdevguide/debugging.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** 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-debugging.html +\ingroup qtquick-tools +\title Debugging QML Applications +\brief debugging tools in QML + +\section1 Console API + +\section2 Log + +\c console.log, console.debug, console.info, console.warn and console.error can be used to print +debugging information to the console. For example: + +\code +function f(a, b) { + console.log("a is ", a, "b is ", b); +} +\endcode + +The output is generated using the qDebug, qWarning, qCritical methods in C++ +(see also http://doc.qt.nokia.com/latest/debug.html#warning-and-debugging-messages). + +Setting the environment variable QML_CONSOLE_EXTENDED also prints the source +code location of the call. + +\section2 Assert + +\c console.assert tests that an expression is true. If not, it will write an optional message +to the console and print the stack trace. + +\code +function f() { + var x = 12 + console.assert(x == 12, "This will pass"); + console.assert(x > 12, "This will fail"); +} +\endcode + +\section2 Timer + +\c console.time and console.timeEnd log the time (in milliseconds) that was spent between +the calls. Both take a string argument that identifies the measurement. For example: + +\code +function f() { + console.time("wholeFunction"); + console.time("firstPart"); + // first part + console.timeEnd("firstPart"); + // second part + console.timeEnd("wholeFunction"); +} +\endcode + +\section2 Trace + +\c console.trace prints the stack trace of JavaScript execution at the point where +it was called. The stack trace info contains function name, file name, line number +and column number. The stack trace is limited to last 10 stack frames. + +\section2 Count + +\c console.count prints the current number of times a particular piece of code has been executed, +along with a message. That is, + +\code +function f() { + console.count("f called"); +} +\endcode + +will print \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is executed. + +\section2 Profile + +\c console.profile turns on the QML and JavaScript profilers. Nested calls are not +supported and a warning will be printed to the console. + +\c console.profileEnd turns off the QML and JavaScript profilers. Calling this function +without a previous call to console.profile will print a warning to the console. A +profiling client should have been attached before this call to receive and store the +profiling data. For example: + +\code +function f() { + console.profile(); + //Call some function that needs to be profiled. + //Ensure that a client is attached before ending + //the profiling session. + console.profileEnd(); +} +\endcode + +\section2 Exception + +\c console.exception prints an error message together with the stack trace of JavaScript +execution at the point where it is called. + +\section1 Debugging Transitions + +When a transition doesn't look quite right, it can be helpful to view it in slow +motion to see what is happening more clearly. This functionality is supported +in the \l{qtquick-qmlscene.html}{QML Scene} tool: to enable this, +click on the "Debugging" menu, then "Slow Down Animations". + + +\section1 Debugging module imports + +The \c QML_IMPORT_TRACE environment variable can be set to enable debug output +from QML's import loading mechanisms. + +For example, for a simple QML file like this: + +\qml +import QtQuick 2.0 + +Rectangle { width: 100; height: 100 } +\endqml + +If you set \c {QML_IMPORT_TRACE=1} before running the \l{qtquick-qmlscene.html} +{QML Scene} (or your QML C++ application), you will see output similar to this: + +\code +QQmlImportDatabase::addImportPath "/qt-sdk/imports" +QQmlImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS" +QQmlImportDatabase::addToImport 0x106237370 "." -1.-1 File as "" +QQmlImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as "" +QQmlImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle" +\endcode + + +\section1 Debugging with Qt Creator + +\l{http://qt.nokia.com/products/developer-tools}{Qt Creator} provides built-in +support for QML debugging. QML projects and standalone C++ applications that +utilize QML can be debugged on desktops as well as on remote devices. +For more information, see the Qt Creator Manual. + +*/ diff --git a/src/quick/doc/src/appdevguide/deployment.qdoc b/src/quick/doc/src/appdevguide/deployment.qdoc new file mode 100644 index 0000000000..2104bb6552 --- /dev/null +++ b/src/quick/doc/src/appdevguide/deployment.qdoc @@ -0,0 +1,207 @@ +/**************************************************************************** +** +** 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-deployment.html +\title Deploying QML Applications +\brief process of deploying QML applications + + + +QML documents are loaded and executed by the QML runtime. This includes the +Declarative UI engine along with the built-in QML elements and plugin modules, +and it also provides access to third-party QML elements and modules. + +Applications that use QML need to invoke the QML runtime in order to +execute QML documents. This can be done by creating a QQuickView +or a QQmlEngine, as described below. In addition, the Declarative UI +package includes the qmlscene tool, which loads \c .qml files. This tool is +useful for developing and testing QML code without the need to write +a C++ application to load the QML runtime. + + + +\section1 Deploying QML-based applications + +To deploy an application that uses QML, the QML runtime must be invoked by +the application. This is done by writing a Qt C++ application that loads the +QQmlEngine by either: + +\list +\li Loading the QML file through a QQuickView instance, or +\li Creating a QQmlEngine instance and loading QML files with QQmlComponent +\endlist + + +\section2 Deploying with QQuickView + +QQuickView is a QWidget-based class that is able to load QML files. +For example, if there is a QML file, \c application.qml, like this: + +\qml + import QtQuick 2.0 + + Rectangle { width: 100; height: 100; color: "red" } +\endqml + +It can be loaded in a Qt application's \c main.cpp file like this: + +\code + #include <QApplication> + #include <QQuickView> + + int main(int argc, char *argv[]) + { + QApplication app(argc, argv); + + QQuickView view; + view.setSource(QUrl::fromLocalFile("application.qml")); + view.show(); + + return app.exec(); + } +\endcode + +This creates a QWidget-based view that displays the contents of +\c application.qml. + +The application's \c .pro \l{qmake Project Files}{project file} must specify +the \c declarative module for the \c QT variable. For example: + +\code + TEMPLATE += app + QT += gui declarative + SOURCES += main.cpp +\endcode + + +\section2 Creating a QQmlEngine directly + +If \c application.qml does not have any graphical components, or if it is +preferred to avoid QQuickView for other reasons, the QQmlEngine +can be constructed directly instead. In this case, \c application.qml is +loaded as a QQmlComponent instance rather than placed into a view: + +\code + #include <QApplication> + #include <QQmlEngine> + #include <QQmlContext> + #include <QQmlComponent> + + int main(int argc, char *argv[]) + { + QApplication app(argc, argv); + + QQmlEngine engine; + QQmlContext *objectContext = new QQmlContext(engine.rootContext()); + + QQmlComponent component(&engine, "application.qml"); + QObject *object = component.create(objectContext); + + // ... delete object and objectContext when necessary + + return app.exec(); + } +\endcode + +See \l{qtqml-cppintegration-data.html}{Exposing C++ Data to QML} for more information about using +QQmlEngine, QQmlContext and QQmlComponent, as well +as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}. + + + +\section1 Developing and Prototyping with QML Scene + +The Declarative UI package includes a QML runtime tool, +\l{qtquick-qmlscene.html}{qmlscene}, which loads and displays QML documents. +This is useful during the application development phase for prototyping +QML-based applications without writing your own C++ applications to invoke +the QML runtime. + + + +\section1 Managing resource files with the Qt resource system + +The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as +binary files in an application executable. This can be useful when building a mixed +QML/C++ application as it enables QML files (as well as other resources such as images +and sound files) to be referred to through the resource system URI scheme rather than +relative or absolute paths to filesystem resources. Note, however, that if you use the resource +system, the application executable must be re-compiled whenever a QML source file is changed +in order to update the resources in the package. + +To use the resource system in a mixed QML/C++ application: + +\list +\li Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource + files in XML format +\li From C++, load the main QML file as a resource using the \c :/ prefix or as a URL with the + \c qrc scheme +\endlist + +Once this is done, all files specified by relative paths in QML will be loaded from +the resource system instead. Use of the resource system is completely transparent to +the QML layer; this means all QML code should refer to resource files using relative +paths and should \e not use the \c qrc scheme. This scheme should only be used from +C++ code for referring to resource files. + +Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}. +The directory structure looks like this: + +\code +project + |- example.qrc + |- main.qml + |- images + |- background.png + |- main.cpp + |- project.pro +\endcode + +The \c main.qml and \c background.png files will be packaged as resource files. This is +done in the \c example.qrc resource collection file: + +\quotefile qml/qtbinding/resources/example.qrc + +Since \c background.png is a resource file, \c main.qml can refer to it using the relative +path specified in \c example.qrc: + +\snippet qml/qtbinding/resources/main.qml 0 + +To allow QML to locate resource files correctly, the \c main.cpp loads the main QML +file, \c main.qml, as a resource file using the \c qrc scheme: + +\snippet qml/qtbinding/resources/main.cpp 0 + +Finally \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should +be used to build the application resources: + +\quotefile qml/qtbinding/resources/resources.pro + +See \l {The Qt Resource System} for more information. + + diff --git a/src/quick/doc/src/appdevguide/glossary.qdoc b/src/quick/doc/src/appdevguide/glossary.qdoc new file mode 100644 index 0000000000..6e20d2fed9 --- /dev/null +++ b/src/quick/doc/src/appdevguide/glossary.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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-glossary.html +\title Glossary Of Terms +\brief Glossary of terms used in the documentation for QML and QtQuick + +\section1 Common Terms + +\table + \header + \li Term + \li Definition + + \row + \li QML + \li The language provided by the Qt QML module in which QML + applications are written + + \row + \li Qt Quick + \li The standard-library of types and functionality for the + QML language, which is provided by the Qt Quick module, + and may be accessed with "import QtQuick 2.0" + + \row + \li Type + \li A type is either a property type, or a QML object type. + All QML object types may also be a property type (for + example, you can have a property of type Button) but not + all property types are also QML object types (for example, + an integer is not an object). Types are either built-in + to the QML language (\l{qtqml-basictypes.html}{basic types}), + or they are provided by the QtQuick import + (\l{qtquick-qmltypereference.html}{Qt Quick types}), or they + are provided in extensions to QML (\l{qtqml-modules-topic.html} + {Modules}) or by the application developer as QML documents. + + \row + \li Component + \li A Component is a special type which may be used to instantiate + other QML object types. + + \row + \li Object + \li An object is an instance of a type. + + \row + \li Property + \li An object can have one or more properties. Some properties + are associated with the canvas (e.g., x, y, width, height, + and opacity) while others may be data specific to that type + (e.g., the "text" property of the Text type). + + \row + \li Binding + \li A binding is a JavaScript expression which is "bound" to a + property. The value of the property at any point in time + will be the value returned by evaluating that expression. + + \row + \li Signal + \li A signal is a notification of a condition occurring, and may be + either "emitted" or "handled". Most properties of QML objects + have a change signal, and also an associated change signal handler + which may be defined by clients to implement functionality. For + example, the "onClicked()" handler of an instance of the MouseArea + type might be defined in an application to cause a sound to be + played. + + \row + \li Signal Handler + \li A signal handler is the expression (or function) which is triggered + by a signal. It is also known as a "slot" in C++. + + \row + \li Lazy Instantiation + \li Object instances can be instantiated "lazily" at run-time, + to avoid performing unnecessary work until needed. Qt Quick + provides the Loader element to make lazy instantiation more + convenient. +\endtable + +\section1 Indexed Alphabetically + +*/ diff --git a/src/quick/doc/src/appdevguide/internationalization.qdoc b/src/quick/doc/src/appdevguide/internationalization.qdoc new file mode 100644 index 0000000000..ee2ac5df20 --- /dev/null +++ b/src/quick/doc/src/appdevguide/internationalization.qdoc @@ -0,0 +1,96 @@ +/**************************************************************************** +** +** 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-internationalization.html +\ingroup qml-features +\title Localization And Internationalization Support In Qt Quick +\brief Description of how a QML developer can internationalize their application + +\section1 Translation + +Strings in QML can be marked for translation using the qsTr(), qsTranslate(), qsTrId(), +QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions. + +For example: +\qml +Text { text: qsTr("Pictures") } +\endqml + +These functions are standard QtScript functions; for more details see +QScriptEngine::installTranslatorFunctions(). + +QML relies on the core internationalization capabilities provided by Qt. These +capabilities are described more fully in: +\list +\li \l {Internationalization with Qt} +\li \l {Qt Linguist Manual} +\endlist + +You can test a translation with the \l{qtquick-qmlscene.html}{QML Scene} using the -translation option. + +\section2 Example + +First we create a simple QML file with text to be translated. The string +that needs to be translated is enclosed in a call to \c qsTr(). + +hello.qml: +\qml +import QtQuick 2.0 + +Rectangle { + width: 200; height: 200 + Text { text: qsTr("Hello"); anchors.centerIn: parent } +} +\endqml + +Next we create a translation source file using lupdate: +\code +lupdate hello.qml -ts hello.ts +\endcode + +Then we open \c hello.ts in \l{Qt Linguist Manual} {Linguist}, provide +a translation and create the release file \c hello.qm. + +Finally, we can test the translation: +\code +qmlviewer -translation hello.qm hello.qml +\endcode + +You can see a complete example and source code in the \l{declarative/i18n}{QML Internationalization example}. + +\section1 Localization + +Localization is the process of adapting to local conventions, +for example presenting dates and times using the locally preferred formats. + +Qt Quick supports localization via the \l {QtQuick2::Locale}{Locale} object and extensions to the +\l{ECMA-262}{ECMAScript} \l {QtQuick2::Date}{Date} and \l {QtQuick2::Number}{Number} types. + + +*/ + diff --git a/src/quick/doc/src/appdevguide/performance.qdoc b/src/quick/doc/src/appdevguide/performance.qdoc new file mode 100644 index 0000000000..f2918139dc --- /dev/null +++ b/src/quick/doc/src/appdevguide/performance.qdoc @@ -0,0 +1,1120 @@ +/**************************************************************************** +** +** 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-performance.html +\title Performance Considerations And Suggestions +\brief Discussion of performance-related tradeoffs and best-practices + +\section1 Timing Considerations + +As an application developer, you must strive to allow the rendering engine +to achieve a consistent 60 frames-per-second refresh rate. 60 FPS means +that there is approximately 16 milliseconds between each frame in which +processing can be done, which includes the processing required to upload +the draw primitives to the graphics hardware. + +In practice, this means that the application developer should use asynchronous, +event driven programming wherever possible, should use worker threads to do +significant processing, should never manually spin the event loop, and should +never spend more than a couple of milliseconds per frame within blocking functions. +Failure to do so will result in skipped frames, which has a drastic effect on the +user experience. + +\note A pattern which is tempting, but should \e never be used, is creating your +own QEventLoop or calling QCoreApplication::processEvents() in order to avoid +blocking within a C++ code block invoked from QML. This is dangerous because +when an event loop is entered in a signal handler or binding, the QML engine +continues to run other bindings, animations, transitions, etc. Those bindings +can then cause side effects which, for example, destroy the hierarchy containing +your event loop. + +\section1 Profiling + +The most important tip is: use the QML profiler included with Qt Creator. Knowing +where time is spent in an application will allow you to focus on problem areas which +actually exist, rather than problem areas which potentially exist. See the Qt Creator +manual for more information on how to use the QML profiling tool. + +Determining which bindings are being run the most often, or which functions your +application is spending the most time in, will allow you to decide whether you need +to optimize the problem areas, or redesign some implementation details of your +application so that the performance is improved. Attempting to optimize code without +profiling is likely to result in very minor rather than significant performance +improvements. + +\section1 JavaScript + +Most QML applications will have a large amount of JavaScript code in them, in the +form of dynamic functions, signal handlers, and property binding expressions. +This is not generally a problem (in fact, due to some optimizations in the QML engine +(bindings compiler, etc) it can for some use-cases be faster than calling a C++ function) +however care must be taken to ensure that unnecessary processing isn't triggered +accidentally. + +\section2 Bindings + +There are two types of bindings in QML: optimized and non-optimized bindings. +It is a good idea to keep binding expressions as simple as possible, since the +QML engine makes use of an optimized binding expression evaluator which can +evaluate simple binding expressions without needing to switch into a full +JavaScript execution environment. These optimized bindings are evaluated far +more efficiently than more complex (non-optimized) bindings. + +Things to avoid in binding expressions to maximize optimizability: +\list + \li declaring intermediate JavaScript variables + \li calling JavaScript functions + \li constructing closures or defining functions within the binding expression + \li accessing properties outside of the immediate context (generally, this means outside the component) + \li writing to other properties as side effects +\endlist + +The QML_COMPILER_STATS environment variable may be set when running a QML application +to print statistics about how many bindings were able to be optimized. + +Bindings are quickest when they know the type of objects and properties they are working +with. This means that non-final property lookup in a binding expression can be slower +in some cases, where it is possible that the type of the property being looked up has +been changed (for example, by a derived type). + +Note that if a binding cannot be optimized by the QML engine's optimized binding +expression evaluator, and thus must be evaluated by the full JavaScript environment, +some of the tips listed above will no longer apply. For example, it can sometimes be +beneficial to cache the result of property resolution in an intermediate JavaScript +variable, in a very complex binding. Upcoming sections have more information on these +sorts of optimizations. + +\section2 Type-Conversion + +One major cost of using JavaScript is that in most cases when a property from a QML +element is accessed, a JavaScript object with an external resource containing the +underlying C++ data (or a reference to it) is created. In most cases, this is fairly +inexpensive, but in others it can be quite expensive. One example of where it is +expensive is assigning a C++ QVariantMap Q_PROPERTY to a QML "variant" property. +Lists can also be expensive, although sequences of specific types (QList of int, +qreal, bool, QString, and QUrl) should be inexpensive; other list types involve an +expensive conversion cost (creating a new JavaScript Array, and adding new elements +one by one, with per-element conversion from C++ type instance to JavaScript value). + +Converting between some basic property types (such as "string" and "url" properties) +can also be expensive. Using the closest matching property type will avoid unnecessary +conversion. + +If you must expose a QVariantMap to QML, use a "var" property rather than a "variant" +property. In general, "property var" should be considered to be superior to +"property variant" for every use-case in QtQuick 2.0 (note that "property variant" +is marked as obsolete in the QtQuick 2.0 documentation), as it allows a true JavaScript +reference to be stored (which can reduce the number of conversions required in certain +expressions). + +\section2 Resolving Properties + +Property resolution takes time. While in some cases the result of a lookup can be +cached and reused, it is always best to avoid doing unnecessary work altogether, if +possible. + +In the following example, we have a block of code which is run often (in this case, it +is the contents of an explicit loop; but it could be a commonly-evaluated binding expression, +for example) and in it, we resolve the element with the "rect" id and its "color" property +multiple times: + +\qml +// bad.qml +import QtQuick 2.0 + +Item { + width: 400 + height: 200 + Rectangle { + id: rect + anchors.fill: parent + color: "blue" + } + + function printValue(which, value) { + console.log(which + " = " + value); + } + + Component.onCompleted: { + var t0 = new Date(); + for (var i = 0; i < 1000; ++i) { + printValue("red", rect.color.r); + printValue("green", rect.color.g); + printValue("blue", rect.color.b); + printValue("alpha", rect.color.a); + } + var t1 = new Date(); + console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); + } +} +\endqml + +We could instead resolve the common base just once in the block: + +\qml +// good.qml +import QtQuick 2.0 + +Item { + width: 400 + height: 200 + Rectangle { + id: rect + anchors.fill: parent + color: "blue" + } + + function printValue(which, value) { + console.log(which + " = " + value); + } + + Component.onCompleted: { + var t0 = new Date(); + for (var i = 0; i < 1000; ++i) { + var rectColor = rect.color; // resolve the common base. + printValue("red", rectColor.r); + printValue("green", rectColor.g); + printValue("blue", rectColor.b); + printValue("alpha", rectColor.a); + } + var t1 = new Date(); + console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); + } +} +\endqml + +Just this simple change results in a significant performance improvement. +Note that the code above can be improved even further (since the property +being looked up never changes during the loop processing), by hoisting the +property resolution out of the loop, as follows: + +\qml +// better.qml +import QtQuick 2.0 + +Item { + width: 400 + height: 200 + Rectangle { + id: rect + anchors.fill: parent + color: "blue" + } + + function printValue(which, value) { + console.log(which + " = " + value); + } + + Component.onCompleted: { + var t0 = new Date(); + var rectColor = rect.color; // resolve the common base outside the tight loop. + for (var i = 0; i < 1000; ++i) { + printValue("red", rectColor.r); + printValue("green", rectColor.g); + printValue("blue", rectColor.b); + printValue("alpha", rectColor.a); + } + var t1 = new Date(); + console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); + } +} +\endqml + +\section2 Property Bindings + +A property binding expression will be re-evaluated if any of the properties +it references are changed. As such, binding expressions should be kept as +simple as possible. + +If you have a loop where you do some processing, but only the final result +of the processing is important, it is often better to update a temporary +accumulator which you afterwards assign to the property you need to update, +rather than incrementally updating the property itself, in order to avoid +triggering re-evaluation of binding expressions during the intermediate +stages of accumulation. + +The following contrived example illustrates this point: + +\qml +// bad.qml +import QtQuick 2.0 + +Item { + id: root + width: 200 + height: 200 + property int accumulatedValue: 0 + + Text { + anchors.fill: parent + text: root.accumulatedValue.toString() + onTextChanged: console.log("text binding re-evaluated") + } + + Component.onCompleted: { + var someData = [ 1, 2, 3, 4, 5, 20 ]; + for (var i = 0; i < someData.length; ++i) { + accumulatedValue = accumulatedValue + someData[i]; + } + } +} +\endqml + +The loop in the onCompleted handler causes the "text" property binding to +be re-evaluated six times (which then results in any other property bindings +which rely on the text value, as well as the onTextChanged signal handler, +to be re-evaluated each time, and lays out the text for display each time). +This is clearly unnecessary in this case, since we really only care about +the final value of the accumulation. + +It could be rewritten as follows: + +\qml +// good.qml +import QtQuick 2.0 + +Item { + id: root + width: 200 + height: 200 + property int accumulatedValue: 0 + + Text { + anchors.fill: parent + text: root.accumulatedValue.toString() + onTextChanged: console.log("text binding re-evaluated") + } + + Component.onCompleted: { + var someData = [ 1, 2, 3, 4, 5, 20 ]; + var temp = accumulatedValue; + for (var i = 0; i < someData.length; ++i) { + temp = temp + someData[i]; + } + accumulatedValue = temp; + } +} +\endqml + +\section2 Sequence tips + +As mentioned earlier, some sequence types are fast (eg, QList<int>, QList<qreal>, +QList<bool>, QList<QString>, QStringList and QList<QUrl>) while others will be +much slower. Aside from using these types wherever possible instead of slower types, +there are some other performance-related semantics you need to be aware of to achieve +the best performance. + +Firstly, there are two different implementations for sequence types: one for where +the sequence is a Q_PROPERTY of a QObject (we'll call this a reference sequence), +and another for where the sequence is returned from a Q_INVOKABLE function of a +QObject (we'll call this a copy sequence). + +A reference sequence is read and written via QMetaObject::property() and thus is read +and written as a QVariant. This means that changing the value of any element in the +sequence from JavaScript will result in three steps occurring: the complete sequence +will be read from the QObject (as a QVariant, but then cast to a sequence of the correct +type); the element at the specified index will be changed in that sequence; and the +complete sequence will be written back to the QObject (as a QVariant). + +A copy sequence is far simpler as the actual sequence is stored in the JavaScript +object's resource data, so no read/modify/write cycle occurs (instead, the resource +data is modified directly). + +Therefore, writes to elements of a reference sequence will be much slower than writes +to elements of a copy sequence. In fact, writing to a single element of an N-element +reference sequence is equivalent in cost to assigning a N-element copy sequence to that +reference sequence, so you're usually better off modifying a temporary copy sequence +and then assigning the result to a reference sequence, during computation. + +Assume the existence (and prior registration into the "Qt.example 1.0" namespace) of the +following C++ type: + +\code +class SequenceTypeExample : public QQuickItem +{ + Q_OBJECT + Q_PROPERTY (QList<qreal> qrealListProperty READ qrealListProperty WRITE setQrealListProperty NOTIFY qrealListPropertyChanged) + +public: + SequenceTypeExample() : QQuickItem() { m_list << 1.1 << 2.2 << 3.3; } + ~SequenceTypeExample() {} + + QList<qreal> qrealListProperty() const { return m_list; } + void setQrealListProperty(const QList<qreal> &list) { m_list = list; emit qrealListPropertyChanged(); } + +signals: + void qrealListPropertyChanged(); + +private: + QList<qreal> m_list; +}; +\endcode + +The following example writes to elements of a reference sequence in a +tight loop, resulting in bad performance: + +\qml +// bad.qml +import QtQuick 2.0 +import Qt.example 1.0 + +SequenceTypeExample { + id: root + width: 200 + height: 200 + + Component.onCompleted: { + var t0 = new Date(); + qrealListProperty.length = 100; + for (var i = 0; i < 500; ++i) { + for (var j = 0; j < 100; ++j) { + qrealListProperty[j] = j; + } + } + var t1 = new Date(); + console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); + } +} +\endqml + +The QObject property read and write in the inner loop caused by the +\c{"qrealListProperty[j] = j"} expression makes this code very suboptimal. Instead, +something functionally equivalent but much faster would be: + +\qml +// good.qml +import QtQuick 2.0 +import Qt.example 1.0 + +SequenceTypeExample { + id: root + width: 200 + height: 200 + + Component.onCompleted: { + var t0 = new Date(); + var someData = [1.1, 2.2, 3.3] + someData.length = 100; + for (var i = 0; i < 500; ++i) { + for (var j = 0; j < 100; ++j) { + someData[j] = j; + } + qrealListProperty = someData; + } + var t1 = new Date(); + console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); + } +} +\endqml + +Secondly, a change signal for the property is emitted if any element in it changes. +If you have many bindings to a particular element in a sequence property, it is better +to create a dynamic property which is bound to that element, and use that dynamic +property as the symbol in the binding expressions instead of the sequence element, +as it will only cause re-evaluation of bindings if its value changes. + +This is an unusual use-case which most clients should never hit, but is worth being +aware of, in case you find yourself doing something like this: + +\qml +// bad.qml +import QtQuick 2.0 +import Qt.example 1.0 + +SequenceTypeExample { + id: root + + property int firstBinding: qrealListProperty[1] + 10; + property int secondBinding: qrealListProperty[1] + 20; + property int thirdBinding: qrealListProperty[1] + 30; + + Component.onCompleted: { + var t0 = new Date(); + for (var i = 0; i < 1000; ++i) { + qrealListProperty[2] = i; + } + var t1 = new Date(); + console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); + } +} +\endqml + +Note that even though only the element at index 2 is modified in the loop, the three +bindings will all be re-evaluated since the granularity of the change signal is that +the entire property has changed. As such, adding an intermediate binding can +sometimes be beneficial: + +\qml +// good.qml +import QtQuick 2.0 +import Qt.example 1.0 + +SequenceTypeExample { + id: root + + property int intermediateBinding: qrealListProperty[1] + property int firstBinding: intermediateBinding + 10; + property int secondBinding: intermediateBinding + 20; + property int thirdBinding: intermediateBinding + 30; + + Component.onCompleted: { + var t0 = new Date(); + for (var i = 0; i < 1000; ++i) { + qrealListProperty[2] = i; + } + var t1 = new Date(); + console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); + } +} +\endqml + +In the above example, only the intermediate binding will be re-evaluated each time, +resulting in a significant performance increase. + +\section2 Value-Type tips + +Value-type properties (font, color, vector3d, etc) have similar QObject property +and change notification semantics to sequence type properties. As such, the tips +given above for sequences are also applicable for value-type properties. While +they are usually less of a problem with value-types (since the number of +sub-properties of a value-type is usually far less than the number of elements +in a sequence), any increase in the number of bindings being re-evaluated needlessly +will have a negative impact on performance. + +\section2 Other JavaScript Objects + +Different JavaScript engines provide different optimizations. The JavaScript engine +which QtQuick 2 uses is optimized for object instantiation and property lookup, but +the optimizations which it provides relies on certain criteria. If your application +does not meet the criteria, the JavaScript engine falls back to a "slow-path" mode +with much worse performance. As such, always try to ensure you meet the following +criteria: + +\list +\li Avoid using eval() if at all possible +\li Do not delete properties of objects +\endlist + +\section1 Common Interface Elements + +\section2 Text Elements + +Calculating text layouts can be a slow operation. Consider using the \c PlainText +format instead of \c StyledText wherever possible, as this reduces the amount of work +required of the layout engine. If you cannot use \c PlainText (as you need to embed +images, or use tags to specify ranges of characters to have certain formatting (bold, +italic, etc) as opposed to the entire text) then you should use \c StyledText. + +You should only use \c AutoText if the text might be (but probably isn't) +\c StyledText as this mode will incur a parsing cost. The \c RichText mode should +not be used, as \c StyledText provides almost all of its features at a fraction of +its cost. + +\section2 Images + +Images are a vital part of any user interface. Unfortunately, they are also a big +source of problems due to the time it takes to load them, the amount of memory they +consume, and the way in which they are used. + +\section3 Asynchronous Loading + +Images are often quite large, and so it is wise to ensure that loading an image doesn't +block the UI thread. Set the "asynchronous" property of the QML Image element to +\c true to enable asynchronous loading of images from the local file system (remote +images are always loaded asynchronously) where this would not result in a negative impact +upon the aesthetics of the user interface. + +Image elements with the "asynchronous" property set to \c true will load images in +a low-priority worker thread. + +\section3 Explicit Source Size + +If your application loads a large image but displays it in a small-sized element, set +the "sourceSize" property to the size of the element being rendered to ensure that the +smaller-scaled version of the image is kept in memory, rather than the large one. + +Beware that changing the sourceSize will cause the image to be reloaded. + +\section3 Avoid Run-time Composition + +Also remember that you can avoid doing composition work at run-time by providing the +pre-composed image resource with your application (e.g., providing elements with shadow +effects). + +\section2 Position Elements With Anchors + +It is more efficient to use anchors rather than bindings to position items +relative to each other. Consider this use of bindings to position rect2 +relative to rect1: + +\code +Rectangle { + id: rect1 + x: 20 + width: 200; height: 200 +} +Rectangle { + id: rect2 + x: rect1.x + y: rect1.y + rect1.height + width: rect1.width - 20 + height: 200 +} +\endcode + +This is achieved more efficiently using anchors: + +\code +Rectangle { + id: rect1 + x: 20 + width: 200; height: 200 +} +Rectangle { + id: rect2 + height: 200 + anchors.left: rect1.left + anchors.top: rect1.bottom + anchors.right: rect1.right + anchors.rightMargin: 20 +} +\endcode + +Note that this is still not as efficient as specifying a static size, so you should still specify static sizes via +the x, y, width and height properties. + +Item coordinates are always relative to their parent, so if you wanted to be a fixed offset from your parent's +0,0 coordinate you should not use anchors. For example the following items are in the same place, but the anchors +code is not as resource efficient as fixed positioning. + +\code +Rectangle { + width: 60 + height: 60 + Rectangle { + x: 20 + y: 20 + width: 20 + height: 20 + } + Rectangle { + anchors.fill: parent + anchors.margins: 20 + } +} +\endcode + +\section1 Models and Views + +Most applications will have at least one model feeding data to a view. There are +some semantics which application developers need to be aware of, in order to achieve +maximal performance. + +\section2 Custom C++ Models + +It is often desirable to write your own custom model in C++ for use with a view in +QML. While the optimal implementation of any such model will depend heavily on the +use-case it must fulfil, some general guidelines are as follows: + +\list +\li Be as asynchronous as possible +\li Do all processing in a (low priority) worker thread +\li Batch up backend operations so that (potentially slow) I/O and IPC is minimized +\li Use a sliding slice window to cache results, whose parameters are determined with the help of profiling +\endlist + +It is important to note that using a low-priority worker thread is recommended to +minimise the risk of starving the GUI thread (which could result in worse perceived +performance). Also, remember that synchronization and locking mechanisms can be a +significant cause of slow performance, and so care should be taken to avoid +unnecessary locking. + +\section2 ListModel + +QML provides a ListModel element which can be used to feed data to a ListView. +It should suffice for most use-cases and be relatively performant so long as +it is used correctly. + +\section3 Populate Within A Worker Thread + +ListModel elements can be populated in a (low priority) worker thread in JavaScript. The +developer must explicitly call "sync()" on the ListModel from within the WorkerScript to +have the changes synchronized to the main thread. See the WorkerScript documentation +for more information. + +Please note that using a WorkerScript element will result in a separate JavaScript engine +being created (as the JavaScript engine is per-thread). This will result in increased +memory usage. Multiple WorkerScript elements will all use the same worker thread, however, +so the memory impact of using a second or third WorkerScript element is negligible once +an application already uses one. + +\section3 Don't Use Dynamic Roles + +The ListModel element in QtQuick 2.0 is much more performant than in QtQuick 1.0. The +performance improvements mainly come from assumptions about the type of roles within each +element in a given model - if the type doesn't change, the caching performance improves +dramatically. If the type can change dynamically from element to element, this optimization +becomes impossible, and the performance of the model will be an order of magnitude worse. + +Therefore, dynamic typing is disabled by default; the developer must specifically set +the boolean "dynamicRoles" property of the model to enable dynamic typing (and suffer +the attendant performance degradation). We recommend that you do not use dynamic typing +if it is possible to redesign your application to avoid it. + +\section2 Views + +View delegates should be kept as simple as possible. Have just enough QML in the delegate +to display the necessary information. Any additional functionality which is not immediately +required (e.g., if it displays more information when clicked) should not be created until +needed (see the upcoming section on lazy initialization). + +The following list is a good summary of things to keep in mind when designing a delegate: +\list +\li The fewer elements that are in a delegate, the faster they can be created, and thus + the faster the view can be scrolled. +\li Keep the number of bindings in a delegate to a minimum; in particular, use anchors + rather than bindings for relative positioning within a delegate. +\li Avoid using ShaderEffect elements within delegates. +\li Never enable clipping on a delegate. +\endlist + +You may set the \c cacheBuffer property of a view to allow asynchronous creation and +buffering of delegates outside of the visible area. Utilizing a \c cacheBuffer is +recommended for view delegates that are non-trivial and unlikely to be created within a +single frame. + +Be mindful that a \c cacheBuffer keeps additional delegates in-memory and therefore the +value derived from utilizing the \c cacheBuffer must be balanced against additional memory +usage. Developers should use benchmarking to find the best value for their use-case, since +the increased memory pressure caused by utilizing a \c cacheBuffer can, in some rare cases, +cause reduced frame rate when scrolling. + +\section1 Visual Effects + +QtQuick 2 includes several features which allow developers and designers to create +exceptionally appealing user interfaces. Fluidity and dynamic transitions as well +as visual effects can be used to great effect in an application, but some care must +be taken when using some of the features in QML as they can have performance implications. + +\section2 Animations + +In general, animating a property will cause any bindings which reference that property +to be re-evaluated. Usually, this is what is desired but in other cases it may be better +to disable the binding prior to performing the animation, and then reassign the binding +once the animation has completed. + +Avoid running JavaScript during animation. For example, running a complex JavaScript +expression for each frame of an x property animation should be avoided. + +Developers should be especially careful using script animations, as these are run in the main +thread (and therefore can cause frames to be skipped if they take too long to complete). + +\section2 Particles + +The QtQuick 2.0 Particles module allows beautiful particle effects to be integrated +seamlessly into user interfaces. However every platform has different graphics hardware +capabilities, and the Particles module is unable to limit parameters to what your hardware +can gracefully support. The more particles you attempt to render (and the larger they are), +the faster your graphics hardware will need to be in order to render at 60 FPS. Affecting +more particles requires a faster CPU. It is therefore important to test all +particle effects on your target platform carefully, to calibrate the number and size of +particles you can render at 60 FPS. + +It should be noted that a particle system can be disabled when not in use +(e.g., on a non-visible element) to avoid doing unnecessary simulation. + +See the \l{Particle System Performance Guide} for more in-depth information. + +\section2 Shaders + +Shaders written in GLSL allow for complex transformations and visual effects to be written, +however they should be used with care. Using a ShaderEffectSource causes a scene to +prerendered into an FBO before it can be drawn. This extra overhead is quite expensive. + +A ShaderEffect element can imply a ShaderEffectSource (and the indirect rendering costs +associated with that) and also involves uploading a vertex and fragment shader program +(which is then compiled into a GLSL shader). Each fragment shader runs once for every +pixel of the scene, and so these should be kept as simple as possible. + +\section1 Controlling Element Lifetime + +By partitioning an application into simple, modular components, each contained in a single +QML file, you can achieve faster application startup time and better control over memory +usage, and reduce the number of active-but-invisible elements in your application. + +\section2 Lazy Initialization + +The QML engine does some tricky things to try to ensure that loading and initialization of +components doesn't cause frames to be skipped, however there is no better way to reduce +startup time than to avoid doing work you don't need to do, and delaying the work until +it is necessary. This may be achieved by using either \l Loader or creating components +\l {qtqml-javascript-dynamicobjects.html}{dynamically}. + +\section3 Using Loader + +The Loader is an element which allows dynamic loading and unloading of components. + +\list +\li Using the "active" property of a Loader, initialization can be delayed until required. +\li Using the overloaded version of the "setSource()" function, initial property values can + be supplied. +\li Setting the Loader \l {Loader::asynchronous}{asynchronous} property to true may also + improve fluidity while a component is instantiated. +\endlist + +\section3 Using Dynamic Creation + +Developers can use the Qt.createComponent() function to create a component dynamically at +runtime from within JavaScript, and then call createObject() to instantiate it. Depending +on the ownership semantics specified in the call, the developer may have to delete the +created object manually. See \l{qtqml-javascript-dynamicobjects.html} +{Dynamic Object Management in QML} for more information. + +\section2 Destroy Unused Elements + +Elements which are invisible because they are a child of a non-visible element (e.g., the +second tab in a tab-widget, while the first tab is shown) should be initialized lazily in +most cases, and deleted when no longer in use, to avoid the ongoing cost of leaving them +active (e.g., rendering, animations, property binding evaluation, etc). + +An item loaded with a Loader element may be released by resetting the "source" or +"sourceComponent" property of the Loader, while other items may be explicitly +released by calling destroy() on them. In some cases, it may be necessary to +leave the item active, in which case it should be made invisible at the very least. + +See the upcoming section on Rendering for more information on active but invisible elements. + +\section1 Rendering + +The scene graph used for rendering in QtQuick 2.0 allows highly dynamic, animated user +interfaces to be rendered fluidly at 60 FPS. There are some things which can +dramatically decrease rendering performance, however, and developers should be careful +to avoid these pitfalls wherever possible. + +\section2 Clipping + +Clipping is disabled by default, and should only be enabled when required. + +Clipping is a visual effect, NOT an optimization. It increases (rather than reduces) +complexity for the renderer. If clipping is enabled, an item will clip its own painting, +as well as the painting of its children, to its bounding rectangle. This stops the renderer +from being able to reorder the drawing order of elements freely, resulting in a sub-optimal +best-case scene graph traversal. + +Clipping inside a delegate is especially bad and should be avoided at all costs. + +\section2 Over-drawing and Invisible Elements + +If you have elements which are totally covered by other (opaque) elements, it is best to +set their "visible" property to \c false or they will be needlessly drawn. + +Similarly, elements which are invisible (e.g., the second tab in a tab widget, while the +first tab is shown) but need to be initialized at startup time (e.g., if the cost of +instantiating the second tab takes too long to be able to do it only when the tab is +activated), should have their "visible" property set to \c false, in order to avoid the +cost of drawing them (although as previously explained, they will still incur the cost of +any animations or bindings evaluation since they are still active). + +\section2 Manual Layouts + +The scene graph renderer is able to batch up certain operations to minimise the number of +OpenGL state changes required. However, this optimization is only possible for the +built-in layout elements provided by QtQuick 2.0, and cannot be applied to manual layouts. + +Therefore, application developers should use the Row, Column, Grid, GridView and ListView +elements instead of manual layouts wherever possible. + +\section1 Memory Allocation And Collection + +The amount of memory which will be allocated by an application and the way in which that +memory will be allocated are very important considerations. Aside from the obvious +concerns about out-of-memory conditions on memory-constrained devices, allocating memory +on the heap is a fairly computationally expensive operation, and certain allocation +strategies can result in increased fragmentation of data across pages. JavaScript uses +a managed memory heap which is automatically garbage collected, and this provides some +advantages but also has some important implications. + +An application written in QML uses memory from both the C++ heap and an automatically +managed JavaScript heap. The application developer needs to be aware of the subtleties +of each in order to maximise performance. + +\section2 Tips For QML Application Developers + +The tips and suggestions contained in this section are guidelines only, and may not be +applicable in all circumstances. Be sure to benchmark and analyse your application +carefully using empirical metrics, in order to make the best decisions possible. + +\section3 Instantiate and initialize components lazily + +If your application consists of multiple views (for example, multiple tabs) but only +one is required at any one time, you can use lazy instantiation to minimize the +amount of memory you need to have allocated at any given time. See the prior section +on \l{Lazy Initialization} for more information. + +\section3 Destroy unused objects + +If you lazily instantiate components, or dynamically create objects during a JavaScript +expression, it is often better to manually \c{destroy()} them rather than waiting for +automatic garbage collection to do so. See the prior section on +\l{Controlling Element Lifetime} for more information. + +\section3 Don't manually invoke the garbage collector + +In most cases, it is not wise to manually invoke the garbage collector, as it will block +the GUI thread for a substantial period of time. This can result in skipped frames and +jerky animations, which should be avoided at all costs. + +There are some cases where manually invoking the garbage collector is acceptable (and +this is explained in greater detail in an upcoming section), but in most cases, invoking +the garbage collector is unnecessary and counter-productive. + +\section3 Avoid complex bindings + +Aside from the reduced performance of complex bindings (for example, due to having to +enter the JavaScript execution context to perform evaluation), they also take up more +memory both on the C++ heap and the JavaScript heap than bindings which can be +evaluated by QML's optimized binding expression evaluator. + +\section3 Avoid defining multiple identical implicit types + +If a QML element has a custom property defined in QML, it becomes its own implicit type. +This is explained in greater detail in an upcoming section. If multiple identical +implicit types are defined inline in a component, some memory will be wasted. In that +situation it is usually better to explicitly define a new component which can then be +reused. + +Defining a custom property can often be a beneficial performance optimization (for +example, to reduce the number of bindings which are required or re-evaluated), or it +can improve the modularity and maintainability of a component. In those cases, using +custom properties is encouraged; however, the new type should, if it is used more than +once, be split into its own component (.qml file) in order to conserve memory. + +\section3 Re-use existing components + +If you are considering defining a new component, it's worth double checking that such a +component doesn't already exist in the component set for your platform. Otherwise, you +will be forcing the QML engine to generate and store type-data for a type which is +essentially a duplicate of another pre-existing and potentially already loaded component. + +\section3 Use module APIs instead of pragma library scripts + +If you are using a pragma library script to store application-wide instance data, +consider using a QObject module API instead. This should result in better performance, +and will result in less JavaScript heap memory being used. + +\section2 Memory Allocation in a QML Application + +The memory usage of a QML application may be split into two parts: its C++ heap usage, +and its JavaScript heap usage. Some of the memory allocated in each will be unavoidable, +as it is allocated by the QML engine or the JavaScript engine, while the rest is +dependent upon decisions made by the application developer. + +The C++ heap will contain: +\list + \li the fixed and unavoidable overhead of the QML engine (implementation data + structures, context information, and so on) + \li per-component compiled data and type information, including per-type property + metadata, which is generated by the QML engine depending on which modules are + imported by the application and which components the application loads + \li per-object C++ data (including property values) plus a per-element metaobject + hierarchy, depending on which components the application instantiates + \li any data which is allocated specifically by QML imports (libraries) +\endlist + +The JavaScript heap will contain: +\list + \li the fixed and unavoidable overhead of the JavaScript engine itself (including + built-in JavaScript types) + \li the fixed and unavoidable overhead of our JavaScript integration (constructor + functions for loaded types, function templates, and so on) + \li per-type layout information and other internal type-data generated by the JavaScript + engine at runtime, for each type (see note below, regarding types) + \li per-object JavaScript data ("var" properties, JavaScript functions and signal + handlers, and non-optimized binding expressions) + \li variables allocated during expression evaluation +\endlist + +Furthermore, there will be one JavaScript heap allocated for use in the main thread, and +optionally one other JavaScript heap allocated for use in the WorkerScript thread. If an +application does not use a WorkerScript element, that overhead will not be incurred. The +JavaScript heap can be several megabytes in size, and so applications written for +memory-constrained devices may be best served to avoid using the WorkerScript element +despite its usefulness in populating list models asynchronously. + +Note that both the QML engine and the JavaScript engine will automatically generate their +own caches of type-data about observed types. Every component loaded by an application +is a distinct (explicit) type, and every element (component instance) which defines its +own custom properties in QML is an implicit type. Any element (instance of a component) +which does not define any custom properties is considered by the JavaScript and QML engines +to be of the type explicitly defined by the component, rather than its own implicit type. + +Consider the following example: +\qml +import QtQuick 2.0 + +Item { + id: root + + Rectangle { + id: r0 + color: "red" + } + + Rectangle { + id: r1 + color: "blue" + width: 50 + } + + Rectangle { + id: r2 + property int customProperty: 5 + } + + Rectangle { + id: r3 + property string customProperty: "hello" + } + + Rectangle { + id: r4 + property string customProperty: "hello" + } +} +\endqml + +In the previous example, the rectangles \c r0 and \c r1 do not have any custom properties, +and thus the JavaScript and QML engines consider them both to be of the same type. That +is, \c r0 and \c r1 are both considered to be of the explicitly defined \c Rectangle type. +The rectangles \c r2, \c r3 and \c r4 each have custom properties and are each considered +to be different (implicit) types. Note that \c r3 and \c r4 are each considered to be of +different types, even though they have identical property information, simply because the +custom property was not declared in the component which they are instances of. + +If \c r3 and \c r4 were both instances of a \c RectangleWithString component, and that +component definition included the declaration of a string property named \c customProperty, +then \c r3 and \c r4 would be considered to be the same type (that is, they would be +instances of the \c RectangleWithString type, rather than defining their own implicit type). + +\section2 In-Depth Memory Allocation Considerations + +Whenever making decisions regarding memory allocation or performance trade-offs, it is +important to keep in mind the impact of CPU-cache performance, operating system paging, +and JavaScript engine garbage collection. Potential solutions should be benchmarked +carefully in order to ensure that the best one is selected. + +No set of general guidelines can replace a solid understanding of the underlying +principles of computer science combined with a practical knowledge of the implementation +details of the platform for which the application developer is developing. Furthermore, +no amount of theoretical calculation can replace a good set of benchmarks and analysis +tools when making trade-off decisions. + +\section3 Fragmentation + +Fragmentation is a C++ development issue. If the application developer is not defining +any C++ types or plugins, they may safely ignore this section. + +Over time, an application will allocate large portions of memory, write data to that +memory, and subsequently free some portions of that memory once it has finished using +some of the data. This can result in "free" memory being located in non-contiguous +chunks, which cannot be returned to the operating system for other applications to use. +It also has an impact on the caching and access characteristics of the application, as +the "living" data may be spread across many different pages of physical memory. This +in turn could force the operating system to swap which can cause filesystem I/O - which +is, comparatively speaking, an extremely slow operation. + +Fragmentation can be avoided by utilizing pool allocators (and other contiguous memory +allocators), by reducing the amount of memory which is allocated at any one time by +carefully managing object lifetimes, by periodically cleansing and rebuilding caches, +or by utilizing a memory-managed runtime with garbage collection (such as JavaScript). + +\section3 Garbage Collection + +JavaScript provides garbage collection. Memory which is allocated on the JavaScript +heap (as opposed to the C++ heap) is owned by the JavaScript engine. The engine will +periodically collect all unreferenced data on the JavaScript heap, and if fragmentation +becomes an issue, it will compact its heap by moving all "living" data into a contiguous +region of memory (allowing the freed memory to be returned to the operating system). + +\section4 Implications of Garbage Collection + +Garbage collection has advantages and disadvantages. It ensures that fragmentation is +less of an issue, and it means that manually managing object lifetime is less important. +However, it also means that a potentially long-lasting operation may be initiated by the +JavaScript engine at a time which is out of the application developer's control. Unless +JavaScript heap usage is considered carefully by the application developer, the frequency +and duration of garbage collection may have a negative impact upon the application +experience. + +\section4 Manually Invoking the Garbage Collector + +An application written in QML will (most likely) require garbage collection to be +performed at some stage. While garbage collection will be automatically triggered by +the JavaScript engine when the amount of available free memory is low, it is occasionally +better if the application developer makes decisions about when to invoke the garbage +collector manually (although usually this is not the case). + +The application developer is likely to have the best understanding of when an application +is going to be idle for substantial periods of time. If a QML application uses a lot +of JavaScript heap memory, causing regular and disruptive garbage collection cycles +during particularly performance-sensitive tasks (for example, list scrolling, animations, +and so forth), the application developer may be well served to manually invoke the +garbage collector during periods of zero activity. Idle periods are ideal for performing +garbage collection since the user will not notice any degradation of user experience +(skipped frames, jerky animations, and so on) which would result from invoking the garbage +collector while activity is occurring. + +The garbage collector may be invoked manually by calling \c{gc()} within JavaScript. +This will cause a comprehensive collection and compaction cycle to be performed, which +may take from between a few hundred to more than a thousand milliseconds to complete, and +so should be avoided if at all possible. + +\section3 Memory vs Performance Trade-offs + +In some situations, it is possible to trade-off increased memory usage for decreased +processing time. For example, caching the result of a symbol lookup used in a tight loop +to a temporary variable in a JavaScript expression will result in a significant performance +improvement when evaluating that expression, but it involves allocating a temporary variable. +In some cases, these trade-offs are sensible (such as the case above, which is almost always +sensible), but in other cases it may be better to allow processing to take slightly longer +in order to avoid increasing the memory pressure on the system. + +In some cases, the impact of increased memory pressure can be extreme. In some situations, +trading off memory usage for an assumed performance gain can result in increased page-thrash +or cache-thrash, causing a huge reduction in performance. It is always necessary to benchmark +the impact of trade-offs carefully in order to determine which solution is best in a given +situation. + +For in-depth information on cache performance and memory-time trade-offs, please see +Ulrich Drepper's excellent article "What Every Programmer Should Know About Memory" +(available at http://ftp.linux.org.ua/pub/docs/developer/general/cpumemory.pdf as at 18th +April 2012), and for information on C++-specific optimizations, please see Agner Fog's +excellent manuals on optimizing C++ applications (available at +http://www.agner.org/optimize/ as at 18th April 2012). + +*/ diff --git a/src/quick/doc/src/appdevguide/qml-intro.qdoc b/src/quick/doc/src/appdevguide/qml-intro.qdoc new file mode 100644 index 0000000000..e96fafb6cb --- /dev/null +++ b/src/quick/doc/src/appdevguide/qml-intro.qdoc @@ -0,0 +1,1291 @@ +/**************************************************************************** +** +** 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-intro.html tutorial +\title Introduction to QML Application Development +\brief Introduction to the concepts and features behind QML. + +QML is a declarative language designed to describe the user interface of a +program: both what it looks like, and how it behaves. In QML, a user +interface is specified as a tree of objects with properties. + +This introduction is meant for those with little or no programming +experience. JavaScript is used as a scripting language in QML, so you may want +to learn a bit more about it (see the \l{qtqml-javascript-topic.html} +{Javascript integration in QML} documentation) before diving deeper into QML. +It is also helpful to have a basic understanding of other Web technologies like +HTML and JSON, but it is not required. + +The examples shown in this guide are located in the +\c{examples/quick/tutorials/qmlintro} directory within the Qt source +package. You can run then with the \l{qtquick-qmlscene.html}{qmlscene} tool. They make +use of the Qt Quick module (which provides the standard library of +QML types and functionality for the QML language). + +\section1 \l{QML Concepts and Syntax} +\tableofcontents{1 QML Concepts and Syntax}{section4} + +\section1 \l{Composing User Interfaces with QML} +\tableofcontents{1 Composing User Interfaces with QML}{section4} + +\section1 \l{User Interaction with QML} +\tableofcontents{1 User Interaction with QML}{section4} + +\section1 \l{QML Application Development Tools} +\tableofcontents{1 QML Application Development Tools}{section4} +*/ + +/*! +\page qml-intro-basic-syntax.html +\brief The basic syntax and concepts of the QML language. +\contentspage Introduction to QML Application Development +\previouspage Introduction to QML Application Development +\nextpage Composing User Interfaces with QML +\title QML Concepts and Syntax + +\tableofcontents + +This chapter covers the basic syntax of the QML language through the +use of examples, introducing the concepts behind the language and +the terminology used in the reference documentation. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-basic-syntax.png +\enddiv +The following example shows the basic syntax of QML. When opened in +the \l{qtquick-qmlscene.html}{qmlscene} tool, the output displayed should match the +image shown on the right: a light blue rectangle. + +\snippet examples/quick/tutorials/qmlintro/basic-syntax.qml document + +In this example, we import the features defined by Qt Quick 1.0, and +we declare and create a single rectangle with width, height and color. +Let's take a look at the main points of the language introduced by +this simple example. + +\section1 Importing Modules + +The \c import statement imports the \l{qtquick-main.html}{QtQuick} +\l{qtqml-modules-topic.html}{module}, which contains all of the standard +QML types. Without this import statement, the \l Rectangle and +other visual object types would not be available. + +A specific version of a module is imported. This guarantees that the +QML types imported when the application is run by the user match those +used by the developer when the application was written, ensuring that +they have the expected behavior. + +\section1 Object Declarations + +The rectangle in the above example is specified by the \l Rectangle +object definition. When we declare objects like this, we write the object's type +followed by a pair of braces in between which additional data can be +defined for the object, such as its property values and any child objects. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-elements1.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/elements1.qml document + +Here, we create two visual items: a rectangle with an image inside it. We say that +the rectangle is the parent visual item and the image is its child. Since the +rectangle does not have a parent, it is a top level visual item. + +The position of each visual item in the user interface is defined relative +to the position of its parent, except for the top level visual item whose +position is always the top-left corner of the screen. + +QML files can contain multiple object declarations, but \e{only one} can be a top level +visual item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-elements2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/elements2.qml document + +In this example, we can define as many objects inside the rectangle +as we like, but we cannot define other top level visual items. All the +additional objects are defined inside the light blue rectangle. + +\list +\li When we talk about an \e{object definition}, we mean the syntactic structure, + including the name, the opening and closing braces, and its contents. +\li A \e{visual item} is a declaration of an object that has a visual appearance. All visual items are + objects that inherit \l Item either directly or indirectly. For example, + a \l Rectangle is a visual item, but a \l State is a (non-visual) object because it does + not have an intrinsic appearance. +\endlist + +Note that all object definitions in QML are QML object types. The QML type system +provides basic types and object types. A full list of object types provided by +Qt Quick is described on the \l{qtquick-qmltypereference.html}{Qt Quick QML Type Reference} page. + +\section1 Properties + +A QML object usually has various \e properties that help define the object. +For example, all items have the \l{Item::}{x} and \l{Item::}{y} properties +that define the position of the item relative to its parent item (or the +screen's origin) and \l{Item::}{width} and \l{Item::}{height} properties +that define its dimensions. All simple properties have names that begin +with a lower case letter. + +\section2 Setting Properties + +Properties are specified with a \c{property: value} syntax. In the above +example, we can see the \l Image object has a property named \c source, +which has been assigned the value \c{"pics/logo.png"}. The property and its +value are separated by a colon. + +Properties can be specified one-per-line: + +\qml +Rectangle { + width: 100 + height: 100 +} +\endqml + +or you can put multiple properties on a single line: + +\qml +Rectangle { width: 100; height: 100 } +\endqml + +When multiple property-value pairs are specified on a single line, they +must be separated by a semicolon. + +\section2 Basic Property Types + +QML supports properties of many types (see the documentation about the +\l{qtqml-typesystem-topic.html}{QML type system}). The basic types +include \c int, \c real, \c bool, \c string and \c color. + +\qml +Item { + x: 10.5 // a 'real' property + state: "details" // a 'string' property + focus: true // a 'bool' property + // ... +} +\endqml + +QML properties are what is known as \e type-safe. That is, they only allow you +to assign a value that matches the property type. For example, the \c x property +of item is a real, and if you try to assign a string to it you will get an error. + +\badcode +Item { + x: "hello" // illegal! +} +\endcode + +Property values are dynamic, responding to changes in the user interface. +See the \l{#Property Change Notifications}{Property Change Notifications} +section for information on the different ways to define properties, bind +them together and react to changes. + +\section2 Grouped Properties +\target dot properties + +Some objects contain a set of related properties that form a logical group; +these use a "dot" or grouped notation to show this. The \l Text item is one +such item that uses groups of properties to describe the font used to +display text. + +Grouped properties can be written like this: + +\snippet examples/quick/tutorials/qmlintro/grouped-properties1.qml text with grouped properties + +or like this: + +\snippet examples/quick/tutorials/qmlintro/grouped-properties2.qml text with grouped properties + +In the object documentation, grouped properties are shown using the "dot" notation. + +\section2 List Properties + +Some properties have a value which is a list of other objects, such as \l State, \l Item or +\l Transition. For example, the \l{Item::}{states} property is used like +this: + +\qml +Item { + states: [ + State { name: "stop" }, + State { name: "go" } + ] +} +\endqml + +The list is enclosed in square brackets, with a comma separating the list +objects. In cases where you are only assigning a single object to a list, +you can omit the square brackets: + +\qml +Item { + states: State { name: "stop" } +} +\endqml + +Objects in the list can be accessed by index. See the \l{list}{list type} +documentation for more details about list properties and their available +operations. + +\section1 Expressions + +JavaScript expressions can be used to assign property values. For example: + +\qml +Item { + width: 100 * 3 + height: 50 + 22 +} +\endqml + +These expressions can include references to other objects and properties, in +which case a \l{qtqml-syntax-propertybinding.html}{binding} is established: when the value of +the expression changes, the property to which the expression is assigned is +automatically updated to the new value. For example: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-property-binding1.png + +\inlineimage declarative-qmlintro-property-binding2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/property-binding.qml elements + +Here, the child \l Rectangle item's \c width property is set relative to +the width of its parent. Whenever the parent's width changes, the width of +the \l Rectangle is automatically updated. This uses the special \c parent +property to refer to a parent item, which we explore in the +\l{Object Identifiers}{next section}. + +This is useful for relating the size of one visual object to another, so that +changes to the sizes of a visual object in the design, or at run-time, will be +taken into account. + +Property binding works with all types of properties, not just those related +to the size of a visual object. + +\section1 Object Identifiers + +Each object can be given a special \e id value that allows the object to +be identified and referred to by other objects. An \c id must begin with +a lower-case letter or an underscore, and cannot contain characters other +than letters, numbers and underscores. + +For example, below we define a \l Text object and a \l Rectangle object +as children of a \l Column object. The \l Text object has an \c id value +of \c{textElement}. The Rectangle object defines its \c width property +to be the same as that of the Text object by referring to +\c{textElement.width}: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-object-identifiers.png +\enddiv + +\snippet examples/quick/tutorials/qmlintro/object-identifiers.qml document + +An object can be referred to by its \c id from anywhere within the +\l{qtqml-documents-topic.html}{component} in which it is declared. Therefore, an +\c id value must always be unique within a single component. +This means that a single QML document should only contain one place where +a particular \c id value is defined. + +The \c id value is a special value for a QML object and should not be +thought of as an ordinary object property; for example, it is not possible +to access \c{textElement.id} in the above example. Once an object is +created, its \c id cannot be changed. + +\note The \c parent value is a special identity that each object can use +to refer to its parent item. For most simple user interfaces containing +a few display items, the parent of an item will be the enclosing object +in the QML file that contains it. However, when we look at more complex +ways to arrange and display items, we will find that this is not always +the case. + +\section1 Comments + +Commenting in QML is similar to JavaScript. +\list +\li Single line comments start with // and finish at the end of the line. +\li Multi-line comments start with /* and finish with *\/ +\endlist + +Comments are ignored by the QML engine. They are useful for explaining what +you are doing; for referring back to at a later date, or for others reading +your QML files. + +\snippet examples/quick/tutorials/qmlintro/comments.qml commenting + +Comments can also be used to prevent the execution of code, which is +sometimes useful for tracking down problems. In the above example, the +\l Text object will have normal opacity, since the line containing the +opacity property has been turned into a comment. + +\section1 Responding to Changes + +User interfaces created using QML contain items such as \l Rectangle, +\l Image and \l Text to display content, but they can also contain items +that accept user input, such as \l TextInput and \l MouseArea. When the +user interacts with these items, they emit signals to inform other +components of any change. These signals can be received by the items +themselves; this is the main way to create items that respond to the user. + +\section2 Signal Handlers + +Signal handlers allow JavaScript code to be executed in response to a signal. +For example, the \l MouseArea object has an \l{MouseArea::}{onClicked} handler +that can be used to respond to a mouse click. Below, we use this handler to +print a message whenever the mouse is clicked: + +\snippet examples/quick/tutorials/qmlintro/signal-handlers.qml document + +All signal handlers begin with \e "on". + +Some signal handlers include an optional parameter. For example +the MouseArea \l{MouseArea::}{onPressed} signal handler has a \c mouse parameter +that contains information about the mouse press. This parameter can be +referred to in the JavaScript code, as below: + +\snippet examples/quick/tutorials/qmlintro/signal-handlers-parameters.qml mouse area + +\section2 Property Change Notifications + +When a property changes value, it can send a signal to notify others of this change. + +To receive these signals, simply create a \e{signal handler} named with an +\e on<Property>Changed syntax. For example, the \l TextInput type has a +\l{TextInput::}{text} property. When this property changes, the \c textChanged +signal is emitted. We can monitor this property for changes with the +\c onTextChanged handler. + +\table +\header \li Property \li Signal \li Signal Handler +\row \li \l{TextInput::}{text} \li \c textChanged \li \c onTextChanged +\endtable + +The following code shows this in practice: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-property-change1.png + +\inlineimage declarative-qmlintro-property-change2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/property-change.qml property change + +When the user modifies the text, the expression assigned to the \c textChanged +handler will be evaluated. In this example, the text changes color when this +happens. + +Similarly, the \l Rectangle type has \l{Item::}{width} and +\l{Rectangle::}{color} properties. Below, we have a \l Rectangle object +that has defined two signal handlers, \c onWidthChanged and \c onColorChanged, +which will automatically be called whenever these properties are modified: + +\qml +Rectangle { + width: 100; height: 100 + + onWidthChanged: console.log("Width has changed to:", width) + onColorChanged: console.log("Color has changed to:", color) +} +\endqml + +These cause the new values of these properties to be written to the console, +which can be useful for debugging purposes. + +\section2 Attached Properties +\target attached-properties + +Some objects attach properties to other objects. This is used in cases +where one object needs to access features of another, but does not +inherit properties to access those features. + +Attached Properties are of the form \e {<Type>.<property>} where \e <Type> +is the type of the object that attaches \e <property>. + +An example of attached properties in use involves the \l Keys type which +attaches properties for handling key presses to any item. For example: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-attached-properties.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/attached-properties.qml attached properties + +The \l Keys properties are not defined by the \l Item type. They are +defined separately and attached to the item. + +Attached properties are also used by delegates to reference information about +the view they are used in. For example, the \l ListView type attaches +the \e ListView.isCurrentItem property to each delegate it creates: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-attached-properties-view.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/attached-properties-view.qml delegate with attached property + +In effect, by attaching this property, \l ListView provides an interface +that lets the delegate access information about the current item in the +view it appears in. + +The use of attached properties will be covered in more depth later in this +guide. + +\omit +\section2 Default Properties + +Each object type can specify one of its list or object properties as its default property. +If a property has been declared as the default property, the property tag can be omitted. + +For example this code: +\qml +State { + changes: [ + PropertyChanges {}, + PropertyChanges {} + ] +} +\endqml + +can be simplified to: + +\qml +State { + PropertyChanges {} + PropertyChanges {} +} +\endqml + +because \c changes is the default property of the \c State type. +\endomit +*/ + +/*! +\page qml-intro-composing-uis.html +\contentspage Introduction to QML Application Development +\previouspage QML Concepts and Syntax +\nextpage User Interaction with QML +\title Composing User Interfaces with QML +\brief How to arrange items with anchors. + +\tableofcontents + +In the \l{Introduction to QML Application Development}{previous chapter}, we looked at +the syntax of QML and the basic building blocks that are used to create +user interfaces. For example, at a low level, we have seen that an item's +\c x and \c y properties are used to position it within its parent item. +However, when defining more complex user interfaces, especially those with +items that will move or change size, we need a way to arrange items in a +more systematic way. + +\section1 Anchors and Anchor Lines + +In the previous examples, all the items have been given either absolute +positions in the user interface or positions relative to their parents. +For more flexibility, both at design-time and in the case where the user +interface changes at run-time, we prefer to use anchors to arrange items. + +Anchors connect items together visually, creating relationships between +their geometries. As a result, mixing absolute positioning and anchors +is only recommended in cases where the constraints imposed by each +approach do not conflict. Anchors can only be used to relate items +with their parents, children or siblings. + +\section2 Anchoring within Items + +Anchors can be used to generally describe how items are positioned +within the space occupied by their parents. Two of the anchors are used +to place items in this way. + +The following example uses anchors to position a \l Text item in the +center of a \l Rectangle. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-centerin.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/anchors.qml centered text + +In this case, the center of the text item is anchored to the center of +its parent item by using the \c{anchors.centerIn} grouped property. +This defines a high level description of the relationship between the two +items. Similarly, the \c{anchors.fill} grouped property is used to describe +the case where an item needs to fill the space provided by its parent. + +\note When using \c{anchors.centerIn} and \c{anchors.fill}, the value of +the anchor property is an item. + +\section2 Anchor Lines + +At a lower level, anchors can be used to line up the edges of two items. +In the following example, the \l Text item is centered within its parent, +the \l Item that defines the user interface. The \l Rectangle uses anchors +to define its position relative to the text item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-edges.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/anchors2.qml anchored items + +By giving the text item the \c textItem identifier, we can refer to it when +defining the anchors for the rectangle. We line up the right edge of the +rectangle with the left edge of the text item, and line up their top edges. + +This example shows the use of anchor lines. Grouped properties are defined +for key parts of each item, including its top, left, right and bottom edges, +plus the lines running through the horizontal center and vertical center of +the item. A baseline anchor line is also used for items that display text. + +\note We connect anchor lines to other anchor lines, not to items. + +\section2 Anchors and Property Bindings + +Since the anchor definitions are property bindings, any changes to the +position of an anchor will cause any connected anchors to move as well. +This is illustrated by the following example, which places a red rectangle +beneath a \l TextInput item and uses anchors to ensure that it is always +the same width. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-expanding1.png + +\inlineimage declarative-qmlintro-anchors-expanding2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/anchors-expanding.qml anchored items + +The anchor lines on the left and right edges of the rectangle are connected +to those of the text input item. Since the text can be modified by the user, +the width of the item can change. The use of anchors causes the width of the +rectangle to change as well. + +The \l{qtquick-concepts-positioning-anchors.html}{Anchor-Based Layout in QML} +document covers the use of anchors in more detail. + +\section2 Margins + +Although anchors are useful for lining up items, it is often useful to leave +small gaps between the edges of adjacent items. The following example lines +up an \l Image item with a \l Text item, but uses a margin to leave a gap +between them. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-margins.png + +\inlineimage declarative-qmlintro-anchors-baseline-margins.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/anchors-margins.qml anchored items + +Note that the image also uses a margin to leave a gap between its left edge +and the left edge of the user interface. + +Adding \l Rectangle items to the scene description, we can see the effects of +the anchors and margins, with the image displaced from the left edge of its +parent item and the text label displaced from the right edge of the image. + +\section2 Limitations and Strategies + +Anchors allow the relationships between items to be described using simple +declarations, maintaining a user interface layout when items move or change +size. They are useful in most situations, but have limitations which need +to be considered, and therefore it is a good idea to adopt strategies for +using them. + +\section3 Limitations of Anchors + +Since anchors can only be used to relate an item with its parent, children or +siblings, care must be taken when referencing items in complex or deeply-nested +user interfaces. Where there are lots of items to be arranged, it can be more +productive to use \l{#Positioners}{positioners} and +\l{Generating Items with Repeaters}{repeaters}, or +\l{qtquick-concepts-data-modelview.html}{models and views}. + +Connections between anchors cannot be deleted and will override explicit +declarations of positions and sizes using the \l{Item::}{x}, \l{Item::}{y}, +\l{Item::}{width} and \l{Item::}{height} properties of items. + +Since anchors rely on property binding to ensure that items are dynamically +updated if one of them changes, each anchor definition creates a new dependency +on another item. Use of anchors therefore causes a dependency graph defining an +order in which items will be updated. Problems can occur if circular dependencies +are created between items. The following example shows this occurring with a +parent item and its child. + +\snippet examples/quick/tutorials/qmlintro/circular.qml circular + +\section3 Strategies for Use + +In order to reference an item with an anchor, it needs a way to be identified. +Children of the item can refer to it as \c parent, but otherwise it needs to +define an \l{QML Concepts and Syntax#Object Identifiers}{identifier}. +It is good practice to define identifiers for all the items that need to be +positioned or referenced in some way unless those items can be referenced +using the \c parent identifier. + +It is usually helpful to identify the fixed or dominant parts of the user +interface and give those items identifiers so that dependent items can refer +to them. This avoids potential issues with circular dependencies. +In the example shown, the \c launchBox and \c cancelBox items are anchored +within the top level item that contains the user interface. Each of these +items contain an image and a text item that are anchored to their parent. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-strategy-annotated.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/anchors-strategy.qml anchor strategy + +The above example shows how each item is anchored to its parent. This ensures +that the dependencies introduced by the anchors all consistently point to each +item's parent or a sibling. It is not always possible to ensure such simple +dependencies between items. As a result, it is often necessary to consider +other factors that determine how the use of anchors will affect the geometries +of items. + +When positioning items using the \c horizontalCenter anchor, do not use the +\c left or \c right anchors; define the width of the item instead, either as +a fixed value or as a proportion of the parent item. Similarly, avoid using +the \c top or \c bottom anchors with the \c verticalCenter anchor; set the +height of the item instead. + +Items that define their own width and height based on their contents, like +\l Image or \l TextInput, can be used with all kinds of anchors. Care must +be taken to avoid imposing conflicting constraints on their dimensions. +For example, using \c left and \c right anchors to position a text input +item may be problematic because the item determines its own width and it +may change. + +When defining an item that you want to stretch to fill the available space +between other items, make sure that you anchor the stretchable item to items +with well-defined or implicitly-defined sizes and not the other way round. +The following example shows this with a \l Text item with an implicit size +and a \l Rectangle that stretches to fill the remaining space in its parent +item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-anchors-stretch.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/anchors-stretch.qml items + +The rectangle uses anchors to define its top, left and right edges in terms +of its parent item, and the bottom edge is aligned with the top of the text +item. If, instead, the text item is anchored to the rectangle, which has no +implicit size, the layout of the user interface will be broken because the +rectangle will be assigned a zero height. + +\section1 Positioners + +Positioner items are container items that manage the positions and sizes of +items in a declarative user interface. Positioners behave in a similar way to +the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets, +except that they are also containers in their own right. + +Positioners make it easier to work with many items when they need to be +arranged in a regular layout. As we will see when we encounter +\l{Generating Items with Repeaters}{Repeaters}, it is easier to describe +how items should be arranged when there are many of them than it is to +try and individually position them. + +\section2 Standard Positioners + +A set of standard positioners are provided in the basic set of Qt Quick items. +Since these are all based on the \l Item type, they contain properties that +define their positions and sizes, but they do not have any visual appearance +of their own; they simply arrange their child items in the space allocated to +them. Any background color, if desired, must be added to a parent Rectangle. + +\list +\li \l{#Row}{Row} arranges its children in a row. +\li \l{#Column}{Column} arranges its children in a column. +\li \l{#Grid}{Grid} arranges its children in a grid. +\li \l{#Flow}{Flow} arranges its children like words on a page. +\endlist + +Each of these items provides many of the same properties as the others, +making it easy to exchange one with another at a later point in the design +of an application or component. The common properties are \c spacing, +\c add and \c move. As expected, the \l{Row::spacing}, \l{Column::spacing} +and \l{Grid::spacing} properties have slightly different meanings because +they describe how space is added to different kinds of layout. + +The \c add and \c move properties describe what should happen when items +are added to a positioner item or moved within it. These actions are +described with \l{qtquick-concepts-statesanimations-animations.html} +{transitions}, and will be covered later. + +\section3 Row + +\l Row items are used to horizontally arrange items. The following example +uses a Row item to arrange three rounded \l Rectangle items in an area defined +by an outer colored Rectangle. The \l{Row::spacing}{spacing} property is set to +include a small amount of space between the rectangles. + +\div {class="float-right"} +\inlineimage qml-row.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/row.qml document + +We ensure that the parent \l Rectangle is large enough so that there is some space +left around the edges of the horizontally centered Row item. The equally-sized +rectangles in this example automatically line up because they each have the +same height. Items with different heights will not be positioned vertically +by the \l Row; these need to be lined up using anchors. + +Since the \l Row item is responsible for positioning its child items +horizontally, those child items cannot use anchors to position themselves +within the row. However, they can use anchors to align themselves vertically +relative to one another or to the row itself. The following example uses +\c verticalCenter anchors to vertically align three rectangles with +different sizes. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-row-anchors.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/row-anchors.qml row + +Note that the \l Row item itself uses \c horizontalCenter and \c verticalCenter +anchors to place itself in the center of its parent. It is free to do this +because it is not being positioned by its parent, a \l Rectangle. However, +when we place positioners inside other positioner, such as a \l Row inside +a \l Column, we will need to be aware of what constraints are being imposed +by the positioner's parent item. This is +\l{#Nesting Positioner Items}{discussed later} in this chapter. + +The height of the row is dependent on the heights of the individual child +items and, unless specified using the \c height property or with anchors, +it will only be as high as the tallest child item. + +\section3 Column + +\l Column items are used to vertically arrange items. The following example +uses a Column item to arrange three \l Rectangle items in an area defined +by an outer \l Item. The \l{Column::spacing}{spacing} property is set to +include a small amount of space between the rectangles. + +\div {class="float-right"} +\inlineimage qml-column.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/column.qml document + +In the above example, each of the rounded rectangles are positioned by the +\l Column item. The column only changes the vertical positions of its +child items and does not restrict their horizontal positions. However, +the restrictions on the use of anchors do not apply to the children of +these child items, so each \l Text item uses its \c centerIn anchor to +horizontally and vertically align itself within its parent rectangle. + +The width of the column is dependent on the widths of the individual child +items and, unless specified using the \c width property or with anchors, +it will only be as wide as the widest child item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-column-anchors.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/column-anchors.qml document + +The example above stretches the column horizontally to fill the entire +user interface, and stretches each rectangle inside to fill the column. +The text items behave as they did in the previous example. + +\section3 Grid + +\l Grid items are used to place items in a grid or table arrangement. +The following example uses a Grid item to place four \l Rectangle items +in a 2-by-2 grid. As with the other positioners, the spacing between items +can be specified using the \l{Grid::spacing}{spacing} property. + +\div {class="float-right"} +\inlineimage qml-grid-spacing.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/grid-spacing.qml document + +There is no difference between horizontal and vertical spacing inserted +between items, so any additional space must be added within the items +themselves. Any empty cells in the grid must be created by defining +placeholder items at the appropriate places in the grid definition. + +As with the \l Row and \l Column items, \l Grid items restrict the anchors +used by their child items. Since they position items both horizontally +and vertically, it is not possible to use any of the anchors to align +items within the grid. However, we can use placeholder items as the grid's +child items and put visible items inside those, using anchors to align +them. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-grid-positioning.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/grid-positioning.qml document start +\snippet examples/quick/tutorials/qmlintro/grid-positioning.qml document end + +We only show the first item, but the principle is the same for the others. + +\section3 Flow + +\l Flow items are used to place items like words on a page, with rows or +columns of non-overlapping items. + +Flow items arrange items in a similar way to \l Grid items, with items +arranged in lines along one axis (the minor axis), and lines of items +placed next to each other along another axis (the major axis). The +direction of flow, as well as the spacing between items, are controlled +by the \l{Flow::}{flow} and \l{Flow::}{spacing} properties. + +The following example shows a Flow item containing a number of \l Text +child items. These are arranged in a similar way to those shown in the +screenshots. + +\div {class="float-right"} +\inlineimage qml-flow-text1.png + +\inlineimage qml-flow-text2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/flow.qml document + +The main differences between the \l Grid and \l Flow positioners are that +items inside a \l Flow will wrap when they run out of space on the minor +axis, and items on one line may not be aligned with items on another line +if the items do not have uniform sizes. As with grid items, there is no +independent control of spacing between items and between lines of items. + +\section2 Nesting Positioner Items + +Since each positioner is based on \l Item, we can nest them like other +items, placing one positioner inside another. The following example shows a +\l Column that contains two \l Row positioners. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-nested-positioners.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/nested-positioners.qml column + +The example works around the restrictions on the use of anchors mentioned +earlier by using appropriate anchors for each item. The innermost items, +\l Text and \l Rectangle, use anchors for vertical positioning within +\l Row items, which each perform horizontal positioning of their child +items. + +The rows use anchors to position themselves within the \l Column item, which +arranges them vertically. The column is centered horizontally and vertically +within its parent, a non-positioning item. + +\section2 Strategies for Use + +Positioners are intended to be used in situations where it would be +tedious to apply anchors to a number of items. For this reason, they are +also used to position dynamically created items, such as those generated +by \l Repeater items. + +The items used with positioners must have a well-defined size, otherwise +positioners will not be able to determine where they should be placed, +leaving their positions undefined. When using a \l Column, it is sufficient +to give each child item a fixed height; the width can be defined using +anchors. Similarly, with a \l Row, the width of each item should be +fixed, but the height can be defined using anchors. Items used with \l Grid +and \l Flow positioners should have fixed widths and heights. +*/ + +/*! +\page qml-intro-user-interaction.html +\contentspage Introduction to QML Application Development +\previouspage Composing User Interfaces with QML +\nextpage Generating Items with Repeaters +\title User Interaction with QML +\brief Making items respond to user input. + +\tableofcontents + +So far, we have shown how to declare items and arrange them to create a user +interface. If we play a QML file using \l{qtquick-qmlscene.html}{qmlscene}, we can resize the +display window and see the items adapt to the change, but the items +themselves do not respond to user input from the keyboard or mouse. + +Unlike standard Qt widgets, items do not include intrinsic support for user +interaction. The features required for interactivity are added or applied to +items. + +QML provides the \l MouseArea item to handle mouse input and \l Keys and +\l KeyNavigation attached properties to handle keyboard input. These are +used with other items to make them responsive to user input. + +\section1 Mouse Areas + +To make items responsive to mouse clicks, we add \l MouseArea items to the +user interface, typically as children of the items we want to make +interactive. Since \l MouseArea is based on \l Item, it has a geometry, but +no visual appearance. The following example defines a mouse area with an +explicit position and size; the image shown indicates where the mouse area +is in the user interface, but it will not be visible in the running example. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mousearea-annotated.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/mousearea.qml mouse area + +The \l{MouseArea::}{onPressed} and \l{MouseArea::}{onReleased} definitions +are \l{QML Concepts and Syntax#Signal Handlers}{signal handlers} that +contain JavaScript code that will be executed in response to a signal. In +this case, when the mouse button is pressed or released, the code will +change the color of the background. Other signal handlers can be defined +to handle other user input, such as \l{MouseArea::}{onClicked} and +\l{MouseArea::}{onDoubleClicked}. Some require additional configuration +of the item before they will work as expected, as we shall see later. + +\note It is more common to define mouse areas within items and position them +with anchors, as shown by the rest of the examples in this chapter. + +\section2 Handling Mouse Buttons + +The following example uses an anchor to fill a \l Text item with a mouse +area, and defines two signal handlers to response to mouse button input. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-pressed1.png + +\inlineimage declarative-qmlintro-mouse-pressed2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/mouse-pressed-signals.qml text item + +The \l{MouseArea::}{onPressed} and \l{MouseArea::}{onReleased} +signal handlers are defined for the mouse area. As a result, when the user +presses a mouse button when the cursor is over the text, the color changes +to green; when the button is released, the color changes to black. + +Note that the mouse area only responds to the left mouse button by default. +This is because the default value of the \l{MouseArea::}{acceptedButtons} +is \l{Qt::LeftButton}{Qt.LeftButton}. To test for other buttons, set this +property to be the combination of the buttons required (using the OR +operator), as in the following example. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-pressed-buttons.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/mouse-pressed-buttons.qml items + +The mouse area covers the entire area of the user interface and accepts +input from both left and right buttons. Each of the rectangles defines its +color as an expression that depends on the mouse area's +\l{MouseArea::}{pressedButtons} property, testing whether the relevant +button is found in the value of this property. When a button is released, +the value is \c{Qt.NoButton}. + +\note The \l{MouseArea::}{pressed} property provides information about +whether or not a button was pressed in the mouse area, but does not +provide any more than a boolean value. This can be sufficient in many +situations. + +\section2 Finding the Cursor Position + +The \l MouseArea item contains a number of properties and signal handlers +that provide information about the mouse cursor. For example, the +\l{MouseArea::}{mouseX} and \l{MouseArea::}{mouseY} properties contain the +position of the cursor, as shown in the following example. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-pressed-position.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/mouse-pressed-position.qml text item + +When the user presses the mouse button over the text item, the text changes +to show the coordinates within the mouse area where the press occurred. If +we need to find the mouse position outside the text item, we should make +the mouse area a child of the text item's parent and use anchors to fill +that item instead. + +\section2 Mouse Hover + +In the previous examples, the text item and rectangles were updated only +when the mouse button was pressed. Consider a situation where we would like +to continuously update the text item with the mouse's position. In such a +case, we could try the following: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-pressed-position2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/mouse-pressed-position2.qml text item + +When we run this example, the text item shows the initial, default value of +the mouse area's \c mouseX and \c mouseY properties. Moving the cursor over +the text has no effect. It is only when the text item is clicked that the +text is updated. + +The reason for this is that, by default, the mouse area only updates various +properties when a button is pressed. To receive continuous updates about the +mouse cursor, we need to enable \e{mouse hover} by setting its +\l{MouseArea::}{hoverEnabled} property, as shown in the following example: + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-hover-enabled.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/mouse-hover-enabled.qml text item + +With mouse hover enabled, other properties of the \l MouseArea can be +monitored. For example, the \l{MouseArea::}{containsMouse} property can be +used to determine whether the mouse cursor is over the mouse area. +Previously, we only knew when this was the case because the user had to +press a mouse button over the area. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-hover-containsmouse1.png + +\inlineimage declarative-qmlintro-mouse-hover-containsmouse2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/mouse-hover-containsmouse.qml items + +The above example uses \l{QML Concepts and Syntax#Expressions}{an expression} +to show the coordinates of the mouse cursor when it is in the mouse area, +\c area. When \c{area.containsMouse} evaluates to \c false, the \c{-} +character is shown instead. + +Certain signal handlers only become useful when mouse hover is enabled. +For example, the \l{MouseArea::}{onEntered}, \l{MouseArea::}{onExited} +and \l{MouseArea::}{onPositionChanged} signal handlers will be called +when the cursor enters, exits or changes position in the area. + +\section2 Dragging Items + +As well as handling the low level interaction details, the \l MouseArea item +also handles drag operations if the relevant properties are set. The +following example shows how dragging is enabled for an item. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-mouse-drag.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/mouse-drag.qml draggable item + +The item to be dragged is the \l Rectangle containing a \l MouseArea and +\l Text items. All that is required is to set the value of the +\l{MouseArea::}{drag.target} grouped property to the item we wish to enable +dragging for; in this case, the \c parent of the mouse area. When run, the +rectangle containing the text can be dragged around its parent's area. + +The other \c drag grouped properties allow the dragging behavior of the +item to be restricted and fine-tuned. \l{MouseArea::}{drag.axis} can be +set to only allow dragging to occur along the x or y axes, and the range +of positions to which the target item can be dragged can be limited to +a range specified by the \l{MouseArea::}{drag.minimumX}, +\l{MouseArea::}{drag.minimumY}, \l{MouseArea::}{drag.maximumX} and +\l{MouseArea::}{drag.maximumY} properties. + +\section2 Strategies for Use + +Mouse areas are applied to a user interface by using anchors to fill the +items that need to respond to user input. This makes them responsive to +button presses by default, and to mouse movement when the +\l{MouseArea::}{hoverEnabled} property is set to \c true. When a mouse +area is not needed to provide input, its \l{MouseArea::}{enabled} +property can be set to \c false, so that it ignores user input. + +When mouse buttons are pressed and released, the +\l{MouseArea::}{pressedButtons} property is updated as expected. However, +when multiple buttons are used, as in the +\l{#Handling Mouse Buttons}{example above}, the most up-to-date values +reported by this property are not necessarily propagated to the items +that use it. For this reason, it can be better to consider using signal +handlers to respond to mouse button presses and releases. + + +\section1 Key Handling + +Another important method of user input is via the keyboard. In addition to +the \l TextInput and \l TextEdit items, which accept keyboard input for +display purposes, QML provides facilities to allow items to capture key +presses, as well as higher level features for navigation using keys. + +Unlike mouse input, which uses the \l MouseArea item, key input uses two +attached properties to handle keyboard input: \l Keys and \l KeyNavigation. +These look like ordinary object properties, but can be applied to any item in order +to enable keyboard input support. + +\section2 Key Navigation + +In desktop user interfaces, it is usually helpful to provide a way for the +user to navigate between input fields or other interactive items by pressing +navigation keys, typically the cursor keys or the \key Tab key. The +\l KeyNavigation attached property is used to define the relationships +between items to allow this kind of navigation. + +The following example shows two \l Rectangle items placed in a \l Row +positioner. These are defined with identifiers, \c{leftRect} and +\c{rightRect}. + +\div {class="float-right"} +\inlineimage declarative-qmlintro-key-navigation1.png + +\inlineimage declarative-qmlintro-key-navigation2.png +\enddiv +\snippet examples/quick/tutorials/qmlintro/key-navigation.qml items + +The \c{leftRect} rectangle attaches the +\l{KeyNavigation::right}{KeyNavigation.right} property, setting it to refer +to the \c{rightRect} rectangle. The \c{rightRect} rectangle attaches the +\l{KeyNavigation::left}{KeyNavigation.left} property, referring to the +\c{leftRect} rectangle. + +Initially, the \c{leftRect} rectangle has the keyboard focus, since its +\l{Item::}{focus} property is set to \c true. When the user presses the +right cursor key, the focus is passed to the \c{rightRect} rectangle instead, +as defined by the \l KeyNavigation attached property for that item. Pressing +the left cursor key causes the focus to be passed back to \c{leftRect} +because as defined by the \l KeyNavigation attached property for +\c{rightRect}. + +*/ + +/*! +\page qml-intro-positioning-items.html +\contentspage Introduction to QML Application Development +\previouspage User Interaction with QML +\nextpage QML Application Development Tools +\title Generating Items with Repeaters +\brief How to generate and position items dynamically. + +\tableofcontents + +\section1 Repeaters + +\div {class="float-right"} +\inlineimage qml-repeater-grid-index.png +\enddiv + +Repeaters create items from a template for use with positioners, using data +from a model. Combining repeaters and positioners is an easy way to lay out +lots of items. A \l Repeater item is placed inside a positioner, and generates +items that the enclosing positioner arranges. + +Each Repeater creates a number of items by combining each row of data +from a model, specified using the \l{Repeater::model}{model} property, with +the template item, defined as a child item within the Repeater. +The total number of items is determined by the amount of data in the model. + +The following example shows a repeater used with a \l{#Grid}{Grid} item to +arrange a set of Rectangle items. The Repeater item creates a series of 24 +rectangles for the Grid item to position in a 5 by 5 arrangement. + +\snippet qml/repeaters/repeater-grid-index.qml document + +The number of items created by a Repeater is held by its \l{Repeater::}{count} +property. It is not possible to set this property to determine the number of +items to be created. Instead, as in the above example, we use an integer as +the model. This is explained in the \l{QML Data Models#An Integer}{QML Data Models} +document. + +It is also possible to use a delegate as the template for the items created +by a Repeater. This is specified using the \l{Repeater::}{delegate} property. + +\section1 Using Transitions + +Transitions can be used to animate items that are added to, moved within, +or removed from a positioner. + +Transitions for adding items apply to items that are created as part of a +positioner, as well as those that are reparented to become children of a +positioner. +Transitions for removing items apply to items within a positioner that are +deleted, as well as those that are removed from a positioner and given new +parents in a document. + +Additionally, changing the opacity of items to zero will cause them to +disappear using the remove transition, and making the opacity non-zero will +cause them to appear using the add transition. + +\section1 Other Ways to Position Items + +There are several other ways to position items in a user interface. In addition +to the basic technique of specifying their coordinates directly, they can be +positioned relative to other items with \l{anchor-layout}{anchors}, or used +with \l{QML Data Models} such as +\l{QML Data Models#VisualItemModel}{VisualItemModel}. +*/ + +/*! +\page qml-intro-tools.html +\contentspage Introduction to QML Application Development +\previouspage Generating Items with Repeaters +\nextpage Introduction to QML Application Development +\title QML Application Development Tools +\brief Tools provided to enable rapid QML application development + +\tableofcontents + +\section1 Qt Creator Tools + +Qt Creator is a complete integrated development environment (IDE) for creating +applications with Qt Quick and the Qt application framework. + +\image qmldesigner-visual-editor.png + +The main goal for Qt Creator is meeting the development needs of Qt Quick +developers who are looking for simplicity, usability, productivity, +extendibility and openness, while aiming to lower the barrier of entry for +newcomers to Qt Quick and Qt. The key features of Qt Creator allow UI designers +and developers to accomplish the following tasks: +\list +\li Get started with Qt Quick application development quickly and easily with +examples, tutorials, and project wizards. +\li Design application user interface with the integrated editor, Qt Quick +Designer, or use graphics software to design the user interface and use scripts +to export the design to Qt Quick Designer. +\li Develop applications with the advanced code editor that provides new powerful +features for completing code snippets, refactoring code, and viewing the object +hierarchy of QML files. +\li Build and deploy Qt Quick applications that target multiple desktop and +mobile platforms, such as Microsoft Windows, Mac OS X, Linux, and Maemo. +\li Debug JavaScript functions and execute JavaScript expressions in the current +context, and inspect QML at runtime to explore the object structure, debug +animations, and inspect colors. +\li Deploy applications to mobile devices and create application installation +packages for Maemo devices that can be published in the Ovi Store +and other channels. +\li Easily access information with the integrated context-sensitive Qt Help +system. +\endlist + +\image qtcreator-target-selector.png + +\section1 Where to Go from Here + +The \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} +page contains the most important information for QML application developers. + +\l{external: Developing Qt Quick Applications with Creator} +{Developing Qt Quick Applications with Creator} provides an overview +of user interface development using the visual \e{Qt Quick Designer} tool. + +The \l{qtqml-main.html}{Qt QML module} documentation contains in-depth +information about the QML language and the concepts behind QML. + +The \l{qtquick-main.html}{Qt Quick module} documentation contains in-depth +information about the QML types and functionality provided by Qt Quick, +which forms the basis for user-interfaces developed in QML. + +The \l{qtquick-codesamples.html}{Qt Quick Code Samples} page has a gallery of QML applications. + +\section1 License Information +\list +\li \l{qtquicklicense.html}{Qt Quick Licensing Information} +\endlist + +*/ diff --git a/src/quick/doc/src/appdevguide/qmlscene.qdoc b/src/quick/doc/src/appdevguide/qmlscene.qdoc new file mode 100644 index 0000000000..7ca404585d --- /dev/null +++ b/src/quick/doc/src/appdevguide/qmlscene.qdoc @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** 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-qmlscene.html +\ingroup qtquick-tools +\title Protoyping with qmlscene +\ingroup qttools +\brief a tool for testing and loading QML files + +The Qt SDK includes \c qmlscene, a tool for loading QML documents that +makes it easy to quickly develop and debug QML applications. It provides a simple +way of loading QML documents and also includes additional features useful for +the development of QML applications. + +The \c qmlscene tool should only be used for testing and developing QML applications. It is +\e not intended for use in a production environment and should not be used for the +deployment of QML applications. In those cases, a custom C++ application should be +written instead, or the QML file should be bundled in a module. See +\l {Deploying QML applications} for more information. + +The \c qmlscene tool is located at \c QTDIR/bin/qmlscene. To load a \c .qml file, +run the tool and select the file to be opened, or provide the +file path on the command line: + +\code + qmlscene myqmlfile.qml +\endcode + +To see the configuration options, run \c qmlscene with the \c -help argument. + + +\section1 Adding module import paths + +Additional module import paths can be provided using the \c -I flag. +For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates +a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced +identifier, \c qmlscene has to be run with the \c -I flag from the example's +base directory: + +\code +qmlscene -I . plugins.qml +\endcode + +This adds the current directory to the import path so that \c qmlscene will +find the plugin in the \c com/nokia/TimeExample directory. + +Note by default, the current directory is included in the import search path, +but namespaced modules like \c com.nokia.TimeExample are not found unless +the path is explicitly added. + + +\section1 Loading placeholder data + +Often, QML applications are prototyped with fake data that is later replaced +by real data sources from C++ plugins. The \c qmlscene tool assists in this aspect by +loading fake data into the application context: it looks for a directory named +"dummydata" in the same directory as the target QML file, and any \c .qml +files in that directory are loaded as QML objects and bound to the root context +as properties named after the files. + +For example, this QML document refers to a \c lottoNumbers property which does +not actually exist within the document: + +\qml +import QtQuick 2.0 + +ListView { + width: 200; height: 300 + model: lottoNumbers + delegate: Text { text: number } +} +\endqml + +If within the document's directory, there is a "dummydata" directory which +contains a \c lottoNumbers.qml file like this: + +\qml +import QtQuick 2.0 + +ListModel { + ListElement { number: 23 } + ListElement { number: 44 } + ListElement { number: 78 } +} +\endqml + +Then this model would be automatically loaded into the ListView in the previous document. + +Child properties are included when loaded from dummy data. The following document +refers to a \c clock.time property: + +\qml +import QtQuick 2.0 +Text { text: clock.time } +\endqml + +The text value could be filled by a \c dummydata/clock.qml file with a \c time +property in the root context: + +\qml +import QtQuick 2.0 +QtObject { property int time: 54321 } +\endqml + +To replace this with real data, you can simply bind the real data object to +the root context in C++ using QQmlContext::setContextProperty(). This +is detailed in \l{qtqml-cppintegration-topic.html}{Integrating QML and C++}. + +*/ + diff --git a/src/quick/doc/src/appdevguide/qtquicktest.qdoc b/src/quick/doc/src/appdevguide/qtquicktest.qdoc new file mode 100644 index 0000000000..50ce424464 --- /dev/null +++ b/src/quick/doc/src/appdevguide/qtquicktest.qdoc @@ -0,0 +1,108 @@ +/**************************************************************************** +** +** 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-qtquicktest.html +\inqmlmodule QtQuick 2 + \title QtQuickTest Reference Documentation + \keyword QtQuickTest Reference Documentation + \brief unit testing framework for QML + + \section1 Introduction + + QtQuickTest is a unit test framework for QML applications. + Test cases are written as JavaScript functions within a TestCase + element: + + \code + import QtQuick 2.0 + import QtTest 1.0 + + TestCase { + name: "MathTests" + + function test_math() { + compare(2 + 2, 4, "2 + 2 = 4") + } + + function test_fail() { + compare(2 + 2, 5, "2 + 2 = 5") + } + } + \endcode + + Functions whose names start with \c{test_} are treated as test cases + to be executed. See the documentation for the \l TestCase and + \l SignalSpy elements for more information on writing test cases. + + \section1 Running tests + + Test cases are launched by a C++ harness that consists of + the following code: + + \code + #include <QtQuickTest/quicktest.h> + QUICK_TEST_MAIN(example) + \endcode + + Where "example" is an identifier to use to uniquely identify + this set of tests. You should add \c{CONFIG += qmltestcase}. + for example: + + \code + TEMPLATE = app + TARGET = tst_example + CONFIG += warn_on qmltestcase + SOURCES += tst_example.cpp + \endcode + + The test harness scans the specified source directory recursively + for "tst_*.qml" files. If \c{QUICK_TEST_SOURCE_DIR} is not defined, + then the current directory will be scanned when the harness is run. + Other *.qml files may appear for auxillary QML components that are + used by the test. + + The \c{-input} command-line option can be set at runtime to run + test cases from a different directory. This may be needed to run + tests on a target device where the compiled-in directory name refers + to a host. For example: + + \code + tst_example -input /mnt/SDCard/qmltests + \endcode + + See \c{tests/qmlauto} in the source tree for an example of creating a + test harness that uses the \c{QUICK_TEST_SOURCE_DIR} macro. + + If your test case needs QML imports, then you can add them as + \c{-import} options to the the test program command-line by adding + the following line to your .pro file: + + \code + IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2 + \endcode +*/ diff --git a/src/quick/doc/src/appdevguide/quickstart/basics.qdoc b/src/quick/doc/src/appdevguide/quickstart/basics.qdoc new file mode 100644 index 0000000000..48942a5c88 --- /dev/null +++ b/src/quick/doc/src/appdevguide/quickstart/basics.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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-quickstart-basics.html +\title Quick Start Guide - QML Basics +\brief Basic QML application development examples + +\section1 Creating A QML Document + +\section1 Importing And Using The QtQuick Module + +\section1 Loading And Displaying The QML Document + +*/ diff --git a/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc b/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc new file mode 100644 index 0000000000..cace64f06e --- /dev/null +++ b/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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-quickstart-essentials.html +\title Quick Start Guide - QML Essentials +\brief Essential QML application development examples + +\section1 Bindings And Signals + +\section1 Handling User Input + +\section1 Defining Custom QML Types For Re-use + +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/animations.qdoc b/src/quick/doc/src/appdevguide/usecases/animations.qdoc new file mode 100644 index 0000000000..1ae5ac7816 --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/animations.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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-animations.html +\title Usecase - Animations In QML +\brief Example of how to include animations in QML applications +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/integratingcpp.qdoc b/src/quick/doc/src/appdevguide/usecases/integratingcpp.qdoc new file mode 100644 index 0000000000..27bb40c131 --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/integratingcpp.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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 new file mode 100644 index 0000000000..3a261a16d5 --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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-integratingjs.html +\title Use Case - Integrating JavaScript In QML +\brief Example of how to integrate JavaScript code in QML applications +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/layouts.qdoc b/src/quick/doc/src/appdevguide/usecases/layouts.qdoc new file mode 100644 index 0000000000..a32b8b527f --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/layouts.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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-layouts.html +\title Use Case - Layouts In QML +\brief Example of how to create layouts for visual elements in a QML application +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/modules.qdoc b/src/quick/doc/src/appdevguide/usecases/modules.qdoc new file mode 100644 index 0000000000..f453de1924 --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/modules.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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 new file mode 100644 index 0000000000..8af6987f4c --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/multimedia.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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 new file mode 100644 index 0000000000..4564e1cffd --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/styling.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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-styling.html +\title Use Case - Style And Theme Support +\brief Example of how to style user-interface elements in QML +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/text.qdoc b/src/quick/doc/src/appdevguide/usecases/text.qdoc new file mode 100644 index 0000000000..40b32d577d --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/text.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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-text.html +\title Use Case - Displaying Text In QML +\brief Example of how to display text in QML +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/userinput.qdoc b/src/quick/doc/src/appdevguide/usecases/userinput.qdoc new file mode 100644 index 0000000000..212eff257d --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/userinput.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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-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 +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/visual.qdoc b/src/quick/doc/src/appdevguide/usecases/visual.qdoc new file mode 100644 index 0000000000..66244381e6 --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/visual.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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-visual.html +\title Use Case - Visual Elements In QML +\brief Example of how to display visual item types in a QML application +*/ |