src/quick/doc/src/appdevguide/qmlscene.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qtquick-qmlscene.html
  30 \ingroup qtquick-tools
  31 \title Prototyping with qmlscene
  32 \ingroup qttools
  33 \brief a tool for testing and loading QML files
  34
  35 The Qt SDK includes \c qmlscene, a tool for loading QML documents that
  36 makes it easy to quickly develop and debug QML applications. It provides a simple
  37 way of loading QML documents and also includes additional features useful for
  38 the development of QML applications.
  39
  40 The \c qmlscene tool should only be used for testing and developing QML applications. It is
  41 \e not intended for use in a production environment and should not be used for the
  42 deployment of QML applications. In those cases, a custom C++ application should be
  43 written instead, or the QML file should be bundled in a module. See
  44 \l {Deploying QML applications} for more information.
  45
  46 The \c qmlscene tool is located at \c QTDIR/bin/qmlscene. To load a \c .qml file,
  47 run the tool and select the file to be opened, or provide the
  48 file path on the command line:
  49
  50 \code
  51     qmlscene myqmlfile.qml
  52 \endcode
  53
  54 To see the configuration options, run \c qmlscene with the \c -help argument.
  55
  56
  57 \section1 Adding module import paths
  58
  59 Additional module import paths can be provided using the \c -I flag.
  60 For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates
  61 a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced
  62 identifier, \c qmlscene has to be run with the \c -I flag from the example's
  63 base directory:
  64
  65 \code
  66 qmlscene -I . plugins.qml
  67 \endcode
  68
  69 This adds the current directory to the import path so that \c qmlscene will
  70 find the plugin in the \c com/nokia/TimeExample directory.
  71
  72 Note by default, the current directory is included in the import search path,
  73 but namespaced modules like \c com.nokia.TimeExample are not found unless
  74 the path is explicitly added.
  75
  76
  77 \section1 Loading placeholder data
  78
  79 Often, QML applications are prototyped with fake data that is later replaced
  80 by real data sources from C++ plugins. The \c qmlscene tool assists in this aspect by
  81 loading fake data into the application context: it looks for a directory named
  82 "dummydata" in the same directory as the target QML file, and any \c .qml
  83 files in that directory are loaded as QML objects and bound to the root context
  84 as properties named after the files.
  85
  86 For example, this QML document refers to a \c lottoNumbers property which does
  87 not actually exist within the document:
  88
  89 \qml
  90 import QtQuick 2.0
  91
  92 ListView {
  93     width: 200; height: 300
  94     model: lottoNumbers
  95     delegate: Text { text: number }
  96 }
  97 \endqml
  98
  99 If within the document's directory, there is a "dummydata" directory which
 100 contains a \c lottoNumbers.qml file like this:
 101
 102 \qml
 103 import QtQuick 2.0
 104
 105 ListModel {
 106     ListElement { number: 23 }
 107     ListElement { number: 44 }
 108     ListElement { number: 78 }
 109 }
 110 \endqml
 111
 112 Then this model would be automatically loaded into the ListView in the previous document.
 113
 114 Child properties are included when loaded from dummy data. The following document
 115 refers to a \c clock.time property:
 116
 117 \qml
 118 import QtQuick 2.0
 119 Text { text: clock.time }
 120 \endqml
 121
 122 The text value could be filled by a \c dummydata/clock.qml file with a \c time
 123 property in the root context:
 124
 125 \qml
 126 import QtQuick 2.0
 127 QtObject { property int time: 54321 }
 128 \endqml
 129
 130 To replace this with real data, you can simply bind the real data object to
 131 the root context in C++ using QQmlContext::setContextProperty(). This
 132 is detailed in \l{qtqml-cppintegration-topic.html}{Integrating QML and C++}.
 133
 134 */
 135