doc/src/declarative/qmlruntime.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qmlruntime.html
  30 \title Qt Declarative UI Runtime
  31
  32 QML documents are loaded and executed by the QML runtime. This includes the
  33 Declarative UI engine along with the built-in QML elements and plugin modules,
  34 and it also provides access to third-party QML elements and modules.
  35
  36 Applications that use QML need to invoke the QML runtime in order to
  37 execute QML documents. This can be done by creating a QDeclarativeView
  38 or a QDeclarativeEngine, as described below. In addition, the Declarative UI
  39 package includes the \QQV tool, which loads \c .qml files. This tool is
  40 useful for developing and testing QML code without the need to write
  41 a C++ application to load the QML runtime.
  42
  43
  44
  45 \section1 Deploying QML-based applications
  46
  47 To deploy an application that uses QML, the QML runtime must be invoked by
  48 the application. This is done by writing a Qt C++ application that loads the
  49 QDeclarativeEngine by either:
  50
  51 \list
  52 \o Loading the QML file through a QDeclarativeView instance, or
  53 \o Creating a QDeclarativeEngine instance and loading QML files with QDeclarativeComponent
  54 \endlist
  55
  56
  57 \section2 Deploying with QDeclarativeView
  58
  59 QDeclarativeView is a QWidget-based class that is able to load QML files.
  60 For example, if there is a QML file, \c application.qml, like this:
  61
  62 \qml
  63     import QtQuick 1.0
  64
  65     Rectangle { width: 100; height: 100; color: "red" }
  66 \endqml
  67
  68 It can be loaded in a Qt application's \c main.cpp file like this:
  69
  70 \code
  71     #include <QApplication>
  72     #include <QDeclarativeView>
  73
  74     int main(int argc, char *argv[])
  75     {
  76         QApplication app(argc, argv);
  77
  78         QDeclarativeView view;
  79         view.setSource(QUrl::fromLocalFile("application.qml"));
  80         view.show();
  81
  82         return app.exec();
  83     }
  84 \endcode
  85
  86 This creates a QWidget-based view that displays the contents of
  87 \c application.qml.
  88
  89 The application's \c .pro \l{qmake Project Files}{project file} must specify
  90 the \c declarative module for the \c QT variable. For example:
  91
  92 \code
  93     TEMPLATE += app
  94     QT += gui declarative
  95     SOURCES += main.cpp
  96 \endcode
  97
  98
  99 \section2 Creating a QDeclarativeEngine directly
 100
 101 If \c application.qml does not have any graphical components, or if it is
 102 preferred to avoid QDeclarativeView for other reasons, the QDeclarativeEngine
 103 can be constructed directly instead. In this case, \c application.qml is
 104 loaded as a QDeclarativeComponent instance rather than placed into a view:
 105
 106 \code
 107     #include <QApplication>
 108     #include <QDeclarativeEngine>
 109     #include <QDeclarativeContext>
 110     #include <QDeclarativeComponent>
 111
 112     int main(int argc, char *argv[])
 113     {
 114         QApplication app(argc, argv);
 115
 116         QDeclarativeEngine engine;
 117         QDeclarativeContext *objectContext = new QDeclarativeContext(engine.rootContext());
 118
 119         QDeclarativeComponent component(&engine, "application.qml");
 120         QObject *object = component.create(objectContext);
 121
 122         // ... delete object and objectContext when necessary
 123
 124         return app.exec();
 125     }
 126 \endcode
 127
 128 See \l {Using QML Bindings in C++ Applications} for more information about using
 129 QDeclarativeEngine, QDeclarativeContext and QDeclarativeComponent, as well
 130 as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}.
 131
 132
 133
 134 \section1 Developing and prototyping with QML Viewer
 135
 136 The Declarative UI package includes a QML runtime tool, the \QQV, which loads
 137 and displays QML documents. This is useful during the application development
 138 phase for prototyping QML-based applications without writing your own C++
 139 applications to invoke the QML runtime.
 140
 141 See the \l{QML Viewer} documentation for more details.
 142
 143 */
 144