summaryrefslogtreecommitdiffstats
path: root/doc/src/declarative/qmlruntime.qdoc
blob: cef5e6320a9670f377b7aac0cde9bbc385767e81 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
/****************************************************************************
**
** 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 Viewer
    \ingroup qttools

    This page documents the \e{Declarative UI Runtime} for the Qt GUI
    toolkit, and the \QQV which can be used to run apps
    written for the runtime. The \QQV 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 \QQV.
    The launcher 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 \QQV.
    \endlist

    To run an application with the \QQV, pass the filename as an argument:

    \code
    qmlviewer myQmlFile.qml
    \endcode

    Deploying a QML application via the \QQV 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 'qmlviewer MyApp.qml' or by
    opening the file if your system has the \QQV 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 Qt QML Viewer functionality
    The \QQV implements some additional functionality to help it supporting
    myriad applications. If you implement your own 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, \c qmlviewer shows available options.

    \section2 Translations

    When the launcher 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_<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".

    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 launcher will load translation files specified on the
    command line via the \c -translation option.

    \section2 Dummy Data

    The secondary use of the launcher 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 launcher 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 launcher 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 launcher
    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 launcher 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

*/