/**************************************************************************** ** ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** No Commercial Usage ** This file contains pre-release code and may not be distributed. ** You may use this file in accordance with the terms and conditions ** contained in the Technology Preview License Agreement accompanying ** this package. ** ** GNU Lesser General Public License Usage ** Alternatively, this file may be used under the terms of the GNU Lesser ** General Public License version 2.1 as published by the Free Software ** Foundation and appearing in the file LICENSE.LGPL included in the ** packaging of this file. Please review the following information to ** ensure the GNU Lesser General Public License version 2.1 requirements ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. ** ** In addition, as a special exception, Nokia gives you certain additional ** rights. These rights are described in the Nokia Qt LGPL Exception ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. ** ** If you have questions regarding the use of this file, please contact ** Nokia at qt-info@nokia.com. ** ** ** ** ** ** ** ** ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page qmlruntime.html \title Qt Declarative UI Runtime \keyword qml runtime \ingroup qttools This page documents the \e{Declarative UI Runtime} for the Qt GUI toolkit, and the \c qml executable which can be used to run apps written for the runtime. The \c qml executable reads a declarative user interface definition (\c .qml) file and displays the user interface it describes. QML is a runtime, as you can run plain qml files which pull in their required modules. To run apps with the QML runtime, you can either start the runtime from your own application (using a QDeclarativeView) or with the simple \c qml application. The \c qml application can be installed in a production environment, assuming that it is not already present in the system. It is generally packaged alongside Qt. To deploy an application using the QML runtime, you have two options: \list \o Write your own Qt application including a QDeclarative view and deploy it the same as any other Qt application (not discussed further on this page), or \o Write a main QML file for your application, and run your application using the included \c qml tool. \endlist To run an application with the \c qml tool, pass the filename as an argument: \code qml myQmlFile.qml \endcode Deploying a QML application via the \c qml executable allows for QML only deployments, but can also include custom C++ modules just as easily. Below is an example of how you might structure a complex application deployed via the qml runtime, it is a listing of the files that would be included in the deployment package. \code MyApp.qml MyAppCore/qmldir MyAppCore/libMyAppCore.so MyAppCore/MyAppCore.dll MyAppCore/AnAppElement.qml MyAppCore/AnotherElement.qml MyAppCore/images/Logo.png OtherModule/qmldir OtherModule/OtherElement.qml \endcode Note that this example is for deploying the example to both windows and linux. You will still need to compile the C++ modules for each target platform, but you can deploy multiple versions of the modules across platforms with different naming conventions, as the appropriate module file is chosen based on platform naming conventions. The C++ modules must contain a QDeclarativeExtentionPlugin subclass. The application would be executed either with your own application, the command 'qml MyApp.qml' or by opening the qml file if your system has the \c qml executable registered as the handler for qml files. The MyApp.qml file would have access to all of the deployed types using the import statements such as the following: \code import "MyAppCore" import "OtherModule" 1.0 as Other \endcode \section1 \c qml application functionality The \c qml application implements some additional functionality to help it serve the role of a launcher for myriad applications. If you implement your own launcher application, you may also wish to reimplement some or all of this functionality. However, much of this functionality is intended to aid the prototyping of qml applications and may not be necessary for a deployed application. \section2 Options When run with the \c -help option, qml shows available options. \section2 Translations When the runtime loads an initial QML file, it will install a translation file from a "i18n" subdirectory relative to that initial QML file. The actual translation file loaded will be according to the system locale and have the form "qml_.qm", where 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". Such files can be created using \l{Qt Linguist}. See the \l{scripting.html#internationalization}{Qt Internationalization} documentation for information about how to make the JavaScript in QML files use translatable strings. Additionally, the QML runtime will load translation files specified on the command line via the \c -translation option. \section2 Dummy Data The secondary use of the qml runtime is to allow QML files to be viewed with dummy data. This is useful when prototyping the UI, as the dummy data can be later replaced with actual data and bindings from a C++ plugin. To provide dummy data: create a directory called "dummydata" in the same directory as the target QML file and create files there with the "qml" extension. All such files will be loaded as QML objects and bound to the root context as a property with the name of the file (without ".qml"). To replace this with real data, you simply bind the real object to the root context in C++. For example, if the Qt application has a "clock.time" property that is a qreal from 0 to 86400 representing the number of seconds since midnight, dummy data for this could be provided by \c dummydata/clock.qml: \code QtObject { property real time: 12345 } \endcode Any QML can be used in the dummy data files. You could even animate the fictional data! \section2 Runtime Object All applications using the qmlruntime will have access to the 'runtime' property on the root context. This property contains several pieces of information about the runtime environment of the application. \section3 Screen Orientation A special piece of dummy data which is integrated into the runtime is a simple orientation property. The orientation can be set via the settings menu in the application, or by pressing Ctrl+T to toggle it. To use this from within your QML file, access runtime.orientation, which can be either Orientation.Landscape or Orientation.Portrait and which can be bound to in your application. An example is below: \code Item { state: (runtime.orientation == Orientation.Landscape) ? 'landscape' : '' } \endcode This allows your application to respond to the orientation of the screen changing. The runtime will automatically update this on some platforms (currently the N900 only) to match the physical screen's orientation. On other plaforms orientation changes will only happen when explictly asked for. \section3 Window Active The runtime.isActiveWindow property tells whether the main window of the qml runtime is currently active or not. This is especially useful for embedded devices when you want to pause parts of your application, including animations, when your application loses focus or goes to the background. The example below, stops the animation when the application's window is deactivated and resumes on activation: \code Item { width: 300; height: 200 Rectangle { width: 100; height: 100 color: "green" SequentialAnimation on x { running: runtime.isActiveWindow loops: Animation.Infinite NumberAnimation {to: 200} NumberAnimation {to: 0} } } } \endcode */