1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
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
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
30 \ingroup qtquick-tools
33 \brief a tool for testing and loading QML files
35 The Declarative UI package includes QML Viewer, 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.
40 The QML Viewer is a tool for testing and developing QML applications. It is
41 \i 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
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:
51 qmlviewer myqmlfile.qml
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:
59 QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml
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.
66 To see the configuration options, run \c qmlviewer with the \c -help argument.
69 \section1 Adding module import paths
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
78 qmlviewer -I . plugins.qml
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.
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.
89 \section1 Loading translation files
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
98 Such files can be created using \l {Qt Linguist}.
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.
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.
109 \section1 Loading placeholder data with QML Viewer
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.
118 For example, this QML document refers to a \c lottoNumbers property which does
119 not actually exist within the document:
125 width: 200; height: 300
127 delegate: Text { text: number }
131 If within the document's directory, there is a "dummydata" directory which
132 contains a \c lottoNumbers.qml file like this:
138 ListElement { number: 23 }
139 ListElement { number: 44 }
140 ListElement { number: 78 }
144 Then this model would be automatically loaded into the ListView in the previous document.
146 Child properties are included when loaded from dummy data. The following document
147 refers to a \c clock.time property:
151 Text { text: clock.time }
154 The text value could be filled by a \c dummydata/clock.qml file with a \c time
155 property in the root context:
159 QtObject { property int time: 54321 }
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}.
166 \section1 Using the \c runtime object
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:
175 \o \c runtime.isActiveWindow
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.
181 For example, the following animation is only played when the QML Viewer is
186 width: 200; height: 200
188 ColorAnimation on color {
189 running: runtime.isActiveWindow
190 loops: Animation.Infinite
191 from: "green"; to: "blue"; duration: 2000
196 \bold{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.
201 \o \c runtime.orientation
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 \i {Settings -> Properties} menu. The \c orientation value can be one of the following:
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)
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:
222 width: 640; height: 480
226 PropertyChanges { target: window; width: 480; height: 640 }
228 state: (runtime.orientation == Orientation.Landscape
229 || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : ''