<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qmlviewer.qdoc -->
<title>Qt 4.8: QML Viewer</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>QML Viewer</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#adding-module-import-paths">Adding module import paths</a></li>
<li class="level1"><a href="#loading-translation-files">Loading translation files</a></li>
<li class="level1"><a href="#loading-placeholder-data-with-qml-viewer">Loading placeholder data with QML Viewer</a></li>
<li class="level1"><a href="#using-the-object">Using the <tt>runtime</tt> object</a></li>
</ul>
</div>
<h1 class="title">QML Viewer</h1>
<span class="subtitle"></span>
<!-- $$$qmlviewer.html-description -->
<div class="descr"> <a name="details"></a>
<p>The Declarative UI package includes <i>Qt QML Viewer</i>, a tool for loading QML documents that makes it easy to quickly develop and debug QML applications. It invokes the QML runtime to load QML documents and also includes additional features useful for the development of QML-based applications.</p>
<p>The QML Viewer is a tool for testing and developing QML applications. It is <i>not</i> intended for use in a production environment and should not be used for the deployment of QML applications. In those cases, the QML runtime should be invoked from a Qt application instead; see <a href="qmlruntime.html">Qt Declarative UI Runtime</a> for more information.</p>
<p>The viewer is located at <tt>QTDIR/bin/qmlviewer</tt>. To load a <tt>.qml</tt> file with the viewer, run the viewer and select the file to be opened, or provide the file path on the command line:</p>
<pre class="cpp"> qmlviewer myqmlfile<span class="operator">.</span>qml</pre>
<p>On Mac OS X, the QML Viewer application is named "QMLViewer" instead. You can launch the viewer by opening the QMLViewer application from the Finder, or from the command line:</p>
<pre class="cpp"> <span class="type">QMLViewer</span><span class="operator">.</span>app<span class="operator">/</span>Contents<span class="operator">/</span>MacOS<span class="operator">/</span><span class="type">QMLViewer</span> myqmlfile<span class="operator">.</span>qml</pre>
<p>The QML Viewer has a number of configuration options involving features such as fullscreen display, module import path configurations, video recording of QML animations, and OpenGL support.</p>
<p>To see the configuration options, run <tt>qmlviewer</tt> with the <tt>-help</tt> argument.</p>
<a name="adding-module-import-paths"></a>
<h2>Adding module import paths</h2>
<p>Additional module import paths can be provided using the <tt>-I</tt> flag. For example, the <a href="declarative-cppextensions-plugins.html">QML plugins example</a> creates a C++ plugin identified as <tt>com.nokia.TimeExample</tt>. Since this has a namespaced identifier, the viewer has to be run with the <tt>-I</tt> flag from the example's base directory:</p>
<pre class="cpp"> qmlviewer <span class="operator">-</span>I <span class="operator">.</span> plugins<span class="operator">.</span>qml</pre>
<p>This adds the current directory to the import path so that the viewer will find the plugin in the <tt>com/nokia/TimeExample</tt> directory.</p>
<p>Note by default, the current directory is included in the import search path, but namespaced modules like <tt>com.nokia.TimeExample</tt> are not found unless the path is explicitly added.</p>
<a name="loading-translation-files"></a>
<h2>Loading translation files</h2>
<p>When the QML Viewer loads a QML file, it installs a translation file from a "i18n" subdirectory relative to that initial file. This directory should contain translation files named "qml_<language>.qm", where <language> is a two-letter ISO 639 language, such as "qml_fr.qm", optionally followed by an underscore and an uppercase two-letter ISO 3166 country code, such as "qml_fr_FR.qm" or "qml_fr_CA.qm".</p>
<p>Such files can be created using <a href="linguist-manual.html#qt-linguist">Qt Linguist</a>.</p>
<p>The actual translation file that is loaded depends on the system locale. Additionally, the viewer will load any translation files specified on the command line via the <tt>-translation</tt> option.</p>
<p>See the <a href="declarative-i18n.html">QML i18n example</a> for an example. Also, the <a href="scripting.html#internationalization">Qt Internationalization</a> documentation shows how JavaScript code in QML files can be made to use translatable strings.</p>
<a name="loading-placeholder-data-with-qml-viewer"></a>
<h2>Loading placeholder data with QML Viewer</h2>
<p>Often, QML applications are prototyped with fake data that is later replaced by real data sources from C++ plugins. QML Viewer assists in this aspect by loading fake data into the application context: it looks for a directory named "dummydata" in the same directory as the target QML file, and any <tt>.qml</tt> files in that directory are loaded as QML objects and bound to the root context as properties named after the files.</p>
<p>For example, this QML document refers to a <tt>lottoNumbers</tt> property which does not actually exist within the document:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-listview.html">ListView</a></span> {
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">300</span>
<span class="name">model</span>: <span class="name">lottoNumbers</span>
<span class="name">delegate</span>: <span class="name">Text</span> { <span class="name">text</span>: <span class="name">number</span> }
}</pre>
<p>If within the document's directory, there is a "dummydata" directory which contains a <tt>lottoNumbers.qml</tt> file like this:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-listmodel.html">ListModel</a></span> {
<span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">number</span>: <span class="number">23</span> }
<span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">number</span>: <span class="number">44</span> }
<span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">number</span>: <span class="number">78</span> }
}</pre>
<p>Then this model would be automatically loaded into the <a href="qml-listview.html">ListView</a> in the previous document.</p>
<p>Child properties are included when loaded from dummy data. The following document refers to a <tt>clock.time</tt> property:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-text.html">Text</a></span> { <span class="name">text</span>: <span class="name">clock</span>.<span class="name">time</span> }</pre>
<p>The text value could be filled by a <tt>dummydata/clock.qml</tt> file with a <tt>time</tt> property in the root context:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type">QtObject</span> { property <span class="type">int</span> <span class="name">time</span>: <span class="number">54321</span> }</pre>
<p>To replace this with real data, you can simply bind the real data object to the root context in C++ using <a href="qdeclarativecontext.html#setContextProperty">QDeclarativeContext::setContextProperty</a>(). This is detailed in <a href="qtbinding.html">Using QML Bindings in C++ Applications</a>.</p>
<a name="using-the-object"></a>
<h2>Using the <tt>runtime</tt> object</h2>
<p>QML applications that are loaded with the QML Viewer have access to a special <tt>runtime</tt> property on the root context. This property provides additional information about the application's runtime environment through the following properties:</p>
<table class="generic">
<tr valign="top" class="odd"><td ><tt>runtime.isActiveWindow</tt></td><td >This property indicates whether the QML Viewer window is the current active window on the system. It is useful for "pausing" an application, particularly animations, when the QML Viewer loses focus or moves to the background.<p>For example, the following animation is only played when the QML Viewer is the active window:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">200</span>
ColorAnimation on <span class="name">color</span> {
<span class="name">running</span>: <span class="name">runtime</span>.<span class="name">isActiveWindow</span>
<span class="name">loops</span>: <span class="name">Animation</span>.<span class="name">Infinite</span>
<span class="name">from</span>: <span class="string">"green"</span>; <span class="name">to</span>: <span class="string">"blue"</span>; <span class="name">duration</span>: <span class="number">2000</span>
}
}</pre>
<p><b>Note:</b> Since Qt Quick 1.1 this information is accessible outside of the QML Viewer, through the <tt>active</tt> property of the <a href="qml-qt.html#application-prop">Qt.application</a> object.</p>
</td></tr>
<tr valign="top" class="even"><td ><tt>runtime.orientation</tt></td><td >This property indicates the current orientation of the QML Viewer. On the N900 platform and most S60 5.0-based or newer Symbian devices, this property automatically updates to reflect the device's actual orientation; on other platforms, this indicates the orientation currently selected in the QML Viewer's <i>Settings -> Properties</i> menu. The <tt>orientation</tt> value can be one of the following:<ul>
<li><tt>Orientation.Portrait</tt></li>
<li><tt>Orientation.Landscape</tt></li>
<li><tt>Orientation.PortraitInverted</tt> (Portrait orientation, upside-down)</li>
<li><tt>Orientation.LandscapeInverted</tt> (Landscape orientation, upside-down)</li>
</ul>
<p>When the viewer's orientation changes, the appearance of the loaded QML document does not change unless it has been set to respond to changes in <tt>runtime.orientation</tt>. For example, the following Rectangle changes its aspect ratio depending on the orientation of the QML Viewer:</p>
<pre class="qml"> <span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">window</span>
<span class="name">width</span>: <span class="number">640</span>; <span class="name">height</span>: <span class="number">480</span>
<span class="name">states</span>: <span class="name">State</span> {
<span class="name">name</span>: <span class="string">"landscape"</span>
<span class="type"><a href="qml-propertychanges.html">PropertyChanges</a></span> { <span class="name">target</span>: <span class="name">window</span>; <span class="name">width</span>: <span class="number">480</span>; <span class="name">height</span>: <span class="number">640</span> }
}
<span class="name">state</span>: (<span class="name">runtime</span>.<span class="name">orientation</span> <span class="operator">==</span> <span class="name">Orientation</span>.<span class="name">Landscape</span>
<span class="operator">||</span> <span class="name">runtime</span>.<span class="name">orientation</span> <span class="operator">==</span> <span class="name">Orientation</span>.<span class="name">LandscapeInverted</span>) ? <span class="string">'landscape'</span> : <span class="string">''</span>
}</pre>
</td></tr>
</table>
</div>
<!-- @@@qmlviewer.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
