diff options
Diffstat (limited to 'doc/src/declarative/qmlruntime.qdoc')
-rw-r--r-- | doc/src/declarative/qmlruntime.qdoc | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc new file mode 100644 index 0000000000..a1f3f96be9 --- /dev/null +++ b/doc/src/declarative/qmlruntime.qdoc @@ -0,0 +1,144 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlruntime.html +\title Qt Declarative UI Runtime + +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 QDeclarativeView +or a QDeclarativeEngine, as described below. In addition, the Declarative UI +package includes the \QQV 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 +QDeclarativeEngine by either: + +\list +\o Loading the QML file through a QDeclarativeView instance, or +\o Creating a QDeclarativeEngine instance and loading QML files with QDeclarativeComponent +\endlist + + +\section2 Deploying with QDeclarativeView + +QDeclarativeView 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 1.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 <QDeclarativeView> + + int main(int argc, char *argv[]) + { + QApplication app(argc, argv); + + QDeclarativeView 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 QDeclarativeEngine directly + +If \c application.qml does not have any graphical components, or if it is +preferred to avoid QDeclarativeView for other reasons, the QDeclarativeEngine +can be constructed directly instead. In this case, \c application.qml is +loaded as a QDeclarativeComponent instance rather than placed into a view: + +\code + #include <QApplication> + #include <QDeclarativeEngine> + #include <QDeclarativeContext> + #include <QDeclarativeComponent> + + int main(int argc, char *argv[]) + { + QApplication app(argc, argv); + + QDeclarativeEngine engine; + QDeclarativeContext *objectContext = new QDeclarativeContext(engine.rootContext()); + + QDeclarativeComponent component(&engine, "application.qml"); + QObject *object = component.create(objectContext); + + // ... delete object and objectContext when necessary + + return app.exec(); + } +\endcode + +See \l {Using QML Bindings in C++ Applications} for more information about using +QDeclarativeEngine, QDeclarativeContext and QDeclarativeComponent, as well +as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}. + + + +\section1 Developing and prototyping with QML Viewer + +The Declarative UI package includes a QML runtime tool, the \QQV, 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. + +See the \l{QML Viewer} documentation for more details. + +*/ + |