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
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
|
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page winrt_support.html
\title Qt for WinRT
\brief Provides insight into Qt's WinRT port and how to use it.
\ingroup supportedplatform
Qt for WinRT allows you to run Qt applications on devices supporting the
Windows Store App APIs. This covers Modern UI applications on Windows 10,
Windows 10 Mobile and Windows 10 IoT.
Microsoft introduced a new design paradigm with the Windows 8 Modern UI. A
core part of this new approach is Windows Runtime (WinRT) that supports
development using different programming languages, such as C++/CX (component
extensions), C# VB.NET, or JavaScript. The Qt port uses the C++
capabilities. While WinRT supports the component extensions internally, they
are not used inside Qt and you do not need to use them. WinRT applications
run in a sandboxed environment for security reasons and support different
architectures, such as ARM and x86.
\target winrt-supported-configurations
\section1 Supported Configurations
The following configurations are supported.
\include supported-platforms.qdocinc winrt
\section1 Requirements
Development for Windows Runtime requires a Microsoft Windows development host.
The minimum version supported is Windows 10.
Depending on your device target you will need the following tools provided
by Microsoft to be installed:
\table
\header
\li Device Target
\li Environment
\row
\li Windows 10 Mobile
\li Visual Studio 2015
\row
\li Windows 10 Desktop
\li Visual Studio 2015
\row
\li Windows 10 IoT
\li Visual Studio 2015
\row
\li XBox One
\li Visual Studio 2015
\endtable
If you are targeting a remote device, please follow all instructions by
Visual Studio to set it up correctly.
\section1 Getting Started
\section2 Notes to Desktop Users
As WinRT applications run in a sandboxed environment, some restrictions should be taken
into account when considering porting or writing cross-platform applications:
\list
\li The class QProcess is not implemented (indicated by the macro \c QT_NO_PROCESS
being defined) as no subprocesses can be launched.
\li Some paths returned by QStandardPaths::writableLocation() may be empty.
\li A WinRT application may not do socket-based communication with another application
running on the same host (as this would violate the sandboxing).
\li Applications run in fullscreen mode only (see QStyleHints). On desktop,
the screen size varies as the application is resized.
\li There are no environment variables. Qt emulates the functionality
by maintaining the values locally, so that qputenv() and related
functions continue to work. All known variables influencing Qt can
be set in source code.
\li WinRT applications are UI applications by nature. This implies that
console type applications will have a window created internally,
which is always visible.
\li Applications should not exit programmatically. In particular, calling
exit() before the UI is shown causes a crash.
\li The WinRT clipboard is local to the application; it cannot be retrieved
by a desktop application.
\endlist
\section2 Building Applications
You can develop applications for WinRT just as any other Qt applications.
Use your favorite editor or IDE (such as Qt Creator) and create your
application or load a Qt example. Then run \c qmake and \c {nmake/jom} to
build your application.
\section3 Building Applications with Visual Studio
To launch your project with Visual Studio a corresponding project needs to
be created. \c qmake supports converting a \c .pro project into Visual
Studio format by passing the parameters \c -tp vc.
\code
qmake -tp vc <your project>.pro
\endcode
Be aware of using the correct match of \c qmake and Visual Studio. As the
Visual Studio format is generic, it does not return an immediate error if
for instance you open a Windows Phone project inside Visual Studio
for Windows.
This creates a project which supports building applications and running them
with Visual Studio. It does not embed Qt libraries into the package and
requires you to add them manually. For this purpose, the command line
tool \l{The Windows Deployment Tool}{windeployqt} has been included in the installed package. To
enable automatic parsing of dependencies and adding the libraries and
dependencies into the application package, create the project with the
following options:
\code
qmake -tp vc <your project>.pro "CONFIG+=windeployqt"
\endcode
\section3 Building Applications with Qt Creator
You will not need to do any conversion to open your project in Qt Creator.
Please follow the generic instructions on how to open and build a project.
Qt Creator deploys your application on the WinRT device, if the
device is detected by the PC.
\note Remote PCs, such as the Surface, are not yet supported for deployment by Creator.
\section1 Building from Source
We assume that you have cloned the Qt 5 repositories (or obtained
the Qt sources elsewhere) and followed the platform-independent
requirements for building Qt. The process of building Qt is found
in the \l{Building Qt Sources} page.
Qt for WinRT is always built as a cross-build, because tools, such as qmake,
are built as desktop applications. For compiling those, a desktop development
environment is required. If you have installed Visual Studio 2013 for Windows,
this will only create binaries for WinRT. You will need Visual Studio for
Windows Desktop as well to create those desktop tools.
Please make sure to use an x86 command prompt (either use the \e {VS x86 Native
Tools Command Prompt} or call \e vcvarsall.bat without any parameter or with \c x86)
for every WinRT build. While the toolchain which is used for the
target is set automatically, the command prompt decides what will be used for the
host tools like \e qmake or \e moc. Building these tools might fail if another
command prompt is used.
The WinRT mkspec format is \c {<platform>-<architecture>-<toolchain>}
where architecture can be \c arm, \c x86, or \c x64. The following is an
example of building qtbase for WinRT:
\code
> ./configure -xplatform winrt-x64-msvc2013 -release
> nmake/jom
\endcode
\section1 Running Applications from Command Line
WinRT applications must be packaged (including all dependencies) and
installed or registered with the application service in order to be
launched. \l{winrtrunner}{The WinRT Runner Tool} can be used to
launch these applications from the command line.
\section2 Package Content
Package content
consists of the application executable and its dependencies, as for every
Windows application. The dependencies are the needed (Qt)
libraries and plugins. Note that Qt plugins have to be put into a folder
named after their category (platforms, imageformats, and so on) without
using a \c plugins folder as root. For more information, see
\l{Qt for Windows - Deployment}.
As WinRT applications are run in a sandboxed environment, setting
the path variable to point to the files required will not work.
The \l{The Windows Deployment Tool}{windeployqt} convenience tool looks up
the application's dependencies
and copies Qt libraries and plugins to the appropriate directories, as
necessary.
Because all resources are placed to one directory, you can register the
directory using an XML file (AppxManifest.xml) and Windows Powershell. The reference
for these manifest files can be found
\l{http://msdn.microsoft.com/en-us/library/windows/apps/br211473.aspx}{here}.
The target processor architecture must be specified (as opposed to the default,
'neutral').
As soon as these requirements are met, change into your \e packaged directory in
PowerShell and call:
\code
> Add-AppxPackage -Register AppxManifest.xml
\endcode
\note \l{winrtrunner}{The WinRT Runner Tool} can perform the same operation with the --install option.
If that worked, you should be able to find your application in Windows'
start screen. To remove your application, use Windows' built-in way to
uninstall applications (right-click or tap and hold the application and
choose \c{Uninstall}).
\note \l{winrtrunner}{The WinRT Runner Tool} can perform the same operation with the --remove option.
\section2 WinRT Runner Tool
\target winrtrunner
The WinRT Runner Tool can be found in QTDIR/bin/winrtrunner. It is
intended to aid in the deployment, launching, and debugging of Qt for WinRT
applications. It can be used from the command line, or invoked by the IDE.
\badcode
Usage: winrtrunner [options] package [arguments]
winrtrunner installs, runs, and collects test results for packages made with Qt.
Options:
--test Install, start, collect output, stop (if
needed), and uninstall the package. This is
the default action of winrtrunner.
--start Start the package. The package is installed
if it is not already installed. Pass
--install to force reinstallation.
--debug <debugger> Start the package with the debugger
attached. The package is installed if it is
not already installed. Pass --install to
force reinstallation.
--debugger-arguments <arguments> Arguments that are passed to the debugger
when --debug is used. If no debugger was
provided this option is ignored.
--suspend Suspend a running package. When combined
with --stop or --test, the app will be
suspended before being terminated.
--stop Terminate a running package. Can be be
combined with --start and --suspend.
--wait <seconds> If the package is running, waits the given
number of seconds before continuing to the
next task. Passing 0 causes the runner to
wait indefinitely.
--install (Re)installs the package.
--remove Uninstalls the package.
--device <name|index> Specifies the device to target as a device
name or index. Use --list-devices to find
available devices. The default device is the
first device found for the active run
profile.
--profile <name> Force a particular run profile.
--list-devices List the available devices (for use with
--device).
--verbose <level> The verbosity level of the message output
(0 - silent, 1 - info, 2 - debug). Defaults
to 1.
--ignore-errors Always exit with code 0, regardless of the
error state.
--loopbackexempt <mode> Enables localhost communication for
clients,servers or both. Adding this
possibility for servers needs elevated
rights and might ask for these in a
dialog.Possible values: client, server,
clientserver
-?, -h, --help Displays this help.
Arguments:
package [arguments] The executable or package manifest to act
upon. Arguments after the package name will
be passed to the application when it starts.
\endcode
*/
|
