doc/src/qtquick1/qmlviewer.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
  30 \page qmlviewer.html
  31 \inqmlmodule QtQuick 1
  32 \title QML Viewer
  33 \ingroup qttools
  34
  35 The Declarative UI package includes \QQV, a tool for loading QML documents that
  36 makes it easy to quickly develop and debug QML applications. It invokes the QML
  37 runtime to load QML documents and also includes additional features useful for
  38 the development of QML-based applications.
  39
  40 The QML Viewer is a tool 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, the QML runtime should be invoked
  43 from a Qt application instead; see \l {Qt Declarative UI Runtime} for more
  44 information.
  45
  46 The viewer is located at \c QTDIR/bin/qmlviewer. To load a \c .qml file
  47 with the viewer, run the viewer and select the file to be opened, or provide the
  48 file path on the command line:
  49
  50 \code
  51     qmlviewer myqmlfile.qml
  52 \endcode
  53
  54 On Mac OS X, the QML Viewer application is named "QMLViewer" instead. You
  55 can launch the viewer by opening the QMLViewer application from the Finder, or
  56 from the command line:
  57
  58 \code
  59     QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml
  60 \endcode
  61
  62 The QML Viewer has a number of configuration options involving features such as
  63 fullscreen display, module import path configurations, video recording of QML
  64 animations, and OpenGL support.
  65
  66 To see the configuration options, run \c qmlviewer with the \c -help argument.
  67
  68
  69 \section1 Adding module import paths
  70
  71 Additional module import paths can be provided using the \c -I flag.
  72 For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates
  73 a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced
  74 identifier, the viewer has to be run with the \c -I flag from the example's
  75 base directory:
  76
  77 \code
  78 qmlviewer -I . plugins.qml
  79 \endcode
  80
  81 This adds the current directory to the import path so that the viewer will
  82 find the plugin in the \c com/nokia/TimeExample directory.
  83
  84 Note by default, the current directory is included in the import search path,
  85 but namespaced modules like \c com.nokia.TimeExample are not found unless
  86 the path is explicitly added.
  87
  88
  89 \section1 Loading translation files
  90
  91 When the QML Viewer loads a QML file, it installs a translation file from a
  92 "i18n" subdirectory relative to that initial file. This directory should contain
  93 translation files named "qml_<language>.qm", where <language> is a two-letter
  94 ISO 639 language, such as "qml_fr.qm", optionally followed by an underscore and
  95 an uppercase two-letter ISO 3166 country code, such as "qml_fr_FR.qm" or
  96 "qml_fr_CA.qm".
  97
  98 Such files can be created using \l {Qt Linguist}.
  99
 100 The actual translation file that is loaded depends on the system locale.
 101 Additionally, the viewer will load any translation files specified on the command
 102 line via the \c -translation option.
 103
 104 See the \l{declarative/i18n}{QML i18n example} for an example. Also, the
 105 \l{scripting.html#internationalization}{Qt Internationalization} documentation
 106 shows how JavaScript code in QML files can be made to use translatable strings.
 107
 108
 109 \section1 Loading placeholder data with QML Viewer
 110
 111 Often, QML applications are prototyped with fake data that is later replaced
 112 by real data sources from C++ plugins. QML Viewer assists in this aspect by
 113 loading fake data into the application context: it looks for a directory named
 114 "dummydata" in the same directory as the target QML file, and any \c .qml
 115 files in that directory are loaded as QML objects and bound to the root context
 116 as properties named after the files.
 117
 118 For example, this QML document refers to a \c lottoNumbers property which does
 119 not actually exist within the document:
 120
 121 \qml
 122 import QtQuick 1.0
 123
 124 ListView {
 125     width: 200; height: 300
 126     model: lottoNumbers
 127     delegate: Text { text: number }
 128 }
 129 \endqml
 130
 131 If within the document's directory, there is a "dummydata" directory which
 132 contains a \c lottoNumbers.qml file like this:
 133
 134 \qml
 135 import QtQuick 1.0
 136
 137 ListModel {
 138     ListElement { number: 23 }
 139     ListElement { number: 44 }
 140     ListElement { number: 78 }
 141 }
 142 \endqml
 143
 144 Then this model would be automatically loaded into the ListView in the previous document.
 145
 146 Child properties are included when loaded from dummy data. The following document
 147 refers to a \c clock.time property:
 148
 149 \qml
 150 import QtQuick 1.0
 151 Text { text: clock.time }
 152 \endqml
 153
 154 The text value could be filled by a \c dummydata/clock.qml file with a \c time
 155 property in the root context:
 156
 157 \qml
 158 import QtQuick 1.0
 159 QtObject { property int time: 54321 }
 160 \endqml
 161
 162 To replace this with real data, you can simply bind the real data object to
 163 the root context in C++ using QDeclarativeContext::setContextProperty(). This
 164 is detailed in \l {Using QML Bindings in C++ Applications}.
 165
 166 \section1 Using the \c runtime object
 167
 168 QML applications that are loaded with the QML Viewer have access to a special
 169 \c runtime property on the root context. This property provides additional
 170 information about the application's runtime environment through the following properties:
 171
 172 \table
 173 \row
 174
 175 \o \c runtime.isActiveWindow
 176
 177 \o This property indicates whether the QML Viewer window is the current active
 178 window on the system. It is useful for "pausing" an application, particularly
 179 animations, when the QML Viewer loses focus or moves to the background.
 180
 181 For example, the following animation is only played when the QML Viewer is
 182 the active window:
 183
 184 \qml
 185 Rectangle {
 186     width: 200; height: 200
 187
 188     ColorAnimation on color {
 189         running: runtime.isActiveWindow
 190         loops: Animation.Infinite
 191         from: "green"; to: "blue"; duration: 2000
 192     }
 193 }
 194 \endqml
 195
 196 \note Since Qt Quick 1.1 this information is accessible outside of the QML Viewer,
 197 through the \c active property of the \l {QML:Qt::application}{Qt.application} object.
 198
 199 \row
 200
 201 \o \c runtime.orientation
 202
 203 \o This property indicates the current orientation of the QML Viewer.
 204 This indicates the orientation currently selected in the QML Viewer's
 205 \e {Settings -> Properties} menu. The \c orientation value can be one of the following:
 206
 207 \list
 208 \o \c Orientation.Portrait
 209 \o \c Orientation.Landscape
 210 \o \c Orientation.PortraitInverted (Portrait orientation, upside-down)
 211 \o \c Orientation.LandscapeInverted (Landscape orientation, upside-down)
 212 \endlist
 213
 214 When the viewer's orientation changes, the appearance of the loaded QML document
 215 does not change unless it has been set to respond to changes in
 216 \c runtime.orientation. For example, the following Rectangle changes its
 217 aspect ratio depending on the orientation of the QML Viewer:
 218
 219 \qml
 220 Rectangle {
 221     id: window
 222     width: 640; height: 480
 223
 224     states: State {
 225         name: "landscape"
 226         PropertyChanges { target: window; width: 480; height: 640 }
 227     }
 228     state: (runtime.orientation == Orientation.Landscape
 229             || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : ''
 230 }
 231 \endqml
 232
 233 \endtable
 234
 235 */
 236