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
|
/****************************************************************************
**
** 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 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
*/
|
