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
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page ios_support.html
\title Qt for iOS
\brief Provides insight into Qt's iOS port and how to use it.
\ingroup supportedplatform
Qt's iOS port allows you to run Qt applications on iOS devices,
such as iPhones and iPads.
\section1 Getting Started
Development and deployment is done using Xcode. The supported
workflow is to maintain a \c .pro file based project, which
generates an Xcode project. Building and deploying can be done
using either Xcode or Qt Creator. We will look at that in more
detail in the next section.
The minimum deployment target for Qt applications is iOS 5.0. Qt
then supports the following devices (iOS might need to be upgraded
on some devices).
\list
\li iPhone 3GS and later
\li iPod Touch third and later generations
\li iPad 2 and later
\li iPad Mini
\endlist
\section2 Setting Up the Development Environment
You can download the Qt 5 installers from the \l Downloads page.
For more information, see \l{Getting Started with Qt}.
Before installing Qt, you first need to install
Xcode. You will find it in the Mac App Store \l{Xcode}{here}.
\note As \l{Xcode5Req}{required by Apple}, you should always use the latest
Xcode version when building your applications for the App Store.
In practice this means you also need the latest version of OS X to develop
iOS apps with Qt, due to Xcode's system requirements.
For running Qt applications in the simulator that comes with Xcode,
this is all you need. However, for running applications on a
device and publishing your applications in the App Store, you must
join the iOS Developer Program (see
\l{https://developer.apple.com/programs/ios/}), and set up
developer certificates and provisioning profiles. The easiest
solution is to use a profile that takes any App ID (a \c *).
Before building any Qt applications, you should test that Xcode
is set up correctly, for example, by running one of the standard
Xcode application templates on your device.
\section2 Building Applications From the Command Line
As mentioned previously, the development workflow on iOS consists
of maintaining a normal \c .pro file project and export it to
Xcode.
Here is how to build a project with Xcode:
\list
\li run qmake (if you have not done so previously)
\li open the resulting \c .xcodeproject file in Xcode
\li build the application in Xcode
\endlist
Note that you must re-import the project if its setup changes, for
example, when adding or removing source files.
\section1 Building Applications with Qt Creator
You can find information on how to set up and run iOS applications
in Qt Creator's manual:
\list
\li \l{Qt Creator: Connecting iOS devices}{Connecting iOS Devices}.
\endlist
As mentioned previously, you must have Xcode installed.
\section2 Examples for iOS
In Qt Creator, tested examples on iOS can be looked up. Use the \c ios
keyword to search for examples in the Qt Creator Welcome mode. Note that
some examples may have limited functionality.
For a list of examples known to work on iOS devices, visit
\l{Qt for iOS Examples}.
\section1 Using Objective-C Code in Qt Applications
Clang, the compiler used for iOS applications, allows mixing C++
and Objective-C code. To enable this mode, suffix your source
files with \.c mm, and add them to \c OBJECTIVE_SOURCES instead of
\c SOURCES in the \c .pro file. This makes it possible to use
frameworks from Apple's iOS Developer Library in Qt applications.
Most useful is perhaps the possibility for adding In-App
Purchasing with the StoreKit framework.
We currently have one example mixing Objective-C and C++ code. You
find it
\l{http://wiki.qt.io/Mixing_C_and_ObjectiveC_Code}{here}.
\section1 Related Topics
The following topics provide more details about Qt for iOS:
\list
\li \l {Porting to iOS}{Porting a Qt Quick Application}
\li \l {Platform Notes - iOS}{Platform Notes}
\li \l {Qt for iOS - Building from Source}
\endlist
*/
/*!
\page building-from-source-ios.html
\title Qt for iOS - Building from Source
\brief Provides instructions to build Qt from source for iOS platform.
Building \l {Qt for iOS} from sources requires \l Xcode with
command-line tools installed. This can be done within Xcode from
\gui Preferences > \gui Downloads > \gui Components >
\gui {Command Line Tools}.
Qt 5 sources can be obtained either by cloning the repositories or
downloading the source package(s).
We can then configure and build Qt. This is done from the Qt 5 top
directory:
\badcode
> ./configure -xplatform macx-ios-clang -release
\endcode
For other configure options, see \l{Qt Configure Options}.
Then, simply run \c{make}.
\note A default build will include both simulator and device
libraries. If you want to build for a single target, use the \c
-sdk argument with either \c iphoneos or \c iphonesimulator.
*/
/*!
\page porting-to-ios.html
\title Porting to iOS
\brief Provides instructions to port your existing Qt application to iOS.
In this section, we are going to port an existing Qt application to
\l{Qt for iOS}{iOS} and deploy it to the device.
Most Qt applications should be portable to iOS with ease, unless they
depend on a specific hardware or software feature not supported on iOS.
A major part of the porting effort consists of ensuring that all the
application's assets (for example, QML files, images, and icons) are
deployed correctly to the device.
\include porting-notes.qdocinc using resources
The following step-by-step instructions guide you to port an existing Qt Quick
application to iOS using the qrc approach:
\list 1
\li Open the existing project in Qt Creator and configure it with
\e {iOS} or \e {iOS Simulator} kit. For more information, see
\l{Qt Creator: Configuring Projects}.
\li Update all local directory imports in the \c{qml} files to use a local
namespace. For example, to import the QML documents in the "contents"
directory relative to \c{main.qml}, use the following import statement:
\code
import "contents" as Contents
\endcode
\li Identify all the resources used by your application and add them to one
or more qrc files.
Qt Creator updates your qmake project file with the \c RESOURCES
variable, listing the qrc files you added.
\li To load or refer to the resources in the qrc file from a C++ file,
use the "\c{qrc:}" prefix for the URL. For example:
\code
QQuickView viewer;
viewer.setSource(QUrl("qrc:qml/main.qml"));
viewer.show();
\endcode
\note QML documents can refer to files in the resources simply by
using the relative path to the document. Such references do not
require the "\c{qrc:}" or "\c{:/}" prefix.
\li Update the "Run" settings for your project as described in the
\l{Qt Creator: Specifying Run Settings}
\li If your application uses imports or plugins which depend on special Qt
modules, these Qt modules should be added to the .pro file. For example, if
your application uses the \l{Qt Multimedia} import in QML, you should add
the following to your .pro file:
\badcode
QT += multimedia
\endcode
In Qt for iOS, everything is compiled statically and placed into the application
bundle. The applications are "sandboxed" inside their bundles and cannot make use
of shared object files. Because of this, also the plugins used by the Qt modules
need to be statically linked. To do this, define the required plugins using the
\l QTPLUGIN variable. For example, to use the camera APIs from Qt Multimedia:
\badcode
QTPLUGIN += qavfcamera
\endcode
See \l {http://wiki.qt.io/QtMultimedia_iOS}{Qt Multimedia on iOS}
for information on other Qt Multimedia plugins. If your project uses APIs
from \l {Qt Sensors}, use the following:
\badcode
QT += sensors
QTPLUGIN += qtsensors_ios
\endcode
\li Save the changes to your project and run the application.
\endlist
Qt Creator deploys your application on the iOS device, if the
device is detected and configured correctly in Xcode. It is also possible to
test the application in iOS Simulator. For more information, see
\l {http://doc.qt.io/qtcreator/creator-developing-ios.html}{Connecting iOS Devices}.
\sa {Platform Notes - iOS}
*/
/*!
\page platform-notes-ios.html
\title Platform Notes - iOS
\brief This page contains information about building Qt applications for and running them on the iOS platform.
\section1 Deployment
Developing, building, running, and debugging a Qt for iOS application can all be done
with Qt Creator on OS X. The toolchain is provided by Apple's Xcode,
and running qmake on a project targeted for iOS will also generate an
Xcode project file (.xcodeproj), with initial application settings. As Qt
Creator does not provide an interface for managing all of the settings specific
to iOS platform, it is sometimes necessary to adjust them in Xcode directly.
Checking that the application is configured correctly is especially important
before submitting an application for publishing in Apple's App Store.
\target Info.plist
\section2 Information Property List Files
Information property list file (Info.plist) on iOS and OS X is used for configuring
an application bundle. These configuration settings include:
\list
\li Application display name and identifier
\li Required device capabilities
\li Supported user interface orientations
\li Icons and launch images
\endlist
See the documentation on \l {https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Introduction/Introduction.html}
{Information Property List File} in iOS Developer Library for details.
When qmake is run, an \c Info.plist file is generated with appropriate default values.
It is advisable to replace the generated Info.plist with your own copy, to prevent
it from being overwritten the next time qmake is run. You can define a custom information
property list with \l QMAKE_INFO_PLIST variable in your .pro file.
\badcode
ios {
QMAKE_INFO_PLIST = ios/Info.plist
}
\endcode
\section2 Application Assets
For files that cannot be bundled into Qt resources, \l QMAKE_BUNDLE_DATA qmake variable
provides a way to specify a set of files to be copied into the application bundle. For
example:
\badcode
ios {
fontFiles.files = fonts/*.ttf
fontFiles.path = fonts
QMAKE_BUNDLE_DATA += fontFiles
}
\endcode
For image resources, an alternative way is to make use of \l {https://developer.apple.com/library/ios/recipes/xcode_help-image_catalog-1.0/Recipe.html}
{asset catalogs} in Xcode, which can be added in a similar way:
\badcode
ios {
assets_catalogs.files = $$files($$PWD/*.xcassets)
QMAKE_BUNDLE_DATA += assets_catalogs
}
\endcode
Important: resources are compiled only if the .path variable is not set.
It is possible to recursively copy and compile directories though.
\section2 Icons
Icons need to be set in the Info.plist and copied to the application bundle.
Xcode has special support for icons, but when using Qt, it is usually better
to set them in the .pro file.
To support all resolutions and devices, several images should be created.
A detailed list of what is required is available at \l {https://developer.apple.com/library/ios/qa/qa1686/_index.html}{Icon files}.
The filename is not important, but the actual pixel size is.
Just a few icons are required, especially if one does not support iOS 6.1 or earlier.
However, to support both iPhone and iPad, and iOS 6.1 or earlier, the following images
are required:
\list
\li AppIcon29x29.png: 29 x 29
\li AppIcon29x29@2x.png: 58 x 58
\li AppIcon29x29@2x~ipad.png: 58 x 58
\li AppIcon29x29~ipad.png: 29 x 29
\li AppIcon40x40@2x.png: 80 x 80
\li AppIcon40x40@2x~ipad.png: 80 x 80
\li AppIcon40x40~ipad.png: 40 x 40
\li AppIcon50x50@2x~ipad.png: 100 x 100
\li AppIcon50x50~ipad.png: 50 x 50
\li AppIcon57x57.png: 57 x 57
\li AppIcon57x57@2x.png: 114 x 114
\li AppIcon60x60@2x.png: 120 x 120
\li AppIcon72x72@2x~ipad.png: 144 x 144
\li AppIcon72x72~ipad.png: 72 x 72
\li AppIcon76x76@2x~ipad.png: 152 x 152
\li AppIcon76x76~ipad.png: 76 x 76
\endlist
These files should be copied to the application bundle by adding something
like the following code snippet to the .pro file:
\badcode
ios {
ios_icon.files = $$files($$PWD/ios/AppIcon*.png)
QMAKE_BUNDLE_DATA += ios_icon
}
\endcode
For the icons to be used, the filenames also have to be listed in the Info.plist. The best way is to list all icon files
using the \c CFBundleIconFiles key.
The iPad specific version can be given using the \c CFBundleIcons~ipad key, by adding something
like the following code snippet to Info.plist:
\badcode
<key>CFBundleIcons</key>
<dict>
<key>CFBundlePrimaryIcon</key>
<dict>
<key>CFBundleIconFiles</key>
<array>
<string>AppIcon29x29.png</string>
<string>AppIcon29x29@2x.png</string>
<string>AppIcon40x40@2x.png</string>
<string>AppIcon57x57.png</string>
<string>AppIcon57x57@2x.png</string>
<string>AppIcon60x60@2x.png</string>
</array>
</dict>
</dict>
<key>CFBundleIcons~ipad</key>
<dict>
<key>CFBundlePrimaryIcon</key>
<dict>
<key>CFBundleIconFiles</key>
<array>
<string>AppIcon29x29.png</string>
<string>AppIcon29x29@2x.png</string>
<string>AppIcon40x40@2x.png</string>
<string>AppIcon57x57.png</string>
<string>AppIcon57x57@2x.png</string>
<string>AppIcon60x60@2x.png</string>
<string>AppIcon29x29~ipad.png</string>
<string>AppIcon29x29@2x~ipad.png</string>
<string>AppIcon40x40~ipad.png</string>
<string>AppIcon40x40@2x~ipad.png</string>
<string>AppIcon50x50~ipad.png</string>
<string>AppIcon50x50@2x~ipad.png</string>
<string>AppIcon72x72~ipad.png</string>
<string>AppIcon72x72@2x~ipad.png</string>
<string>AppIcon76x76~ipad.png</string>
<string>AppIcon76x76@2x~ipad.png</string>
</array>
</dict>
</dict>
\endcode
This ensures that the appropriate files are copied to the right place and the correct icons are
used as required by the Apple App Store.
Ad-hoc distributions should also include the following filenames in the application bundle
to visualize the application in iTunes:
\list
\li iTunesArtwork 512x512
\li iTunesArtwork@2x 1024x1024
\endlist
\section2 Launch Images
Like icons, launch images consist of images that need to be copied to the application bundle
and keys that have to be set in the Info.plist.
To support the iPhone 6, a launch file (an interface builder .xib file or a storyboard file) should be provided.
For more information, see \l{https://developer.apple.com/library/ios/documentati on/userexperience/conceptual/MobileHIG/LaunchImages.html}{Launch Images}.
Assuming that you called the launch file Launch.xib, it can be added to the Info.plist as follows:
\badcode
<key>UILaunchStoryboardName</key>
<string>Launch</string>
\endcode
It is possible to use launch images (PNG files), as described below, to support the iPhone 6, but it is not recommended.
Qmake generates a default LaunchScreen.xib, so it is better to use another name for a custom launch screen to avoid clashes.
Starting with iOS 7, the launch images are defined using the \c UILaunchImages key.
To support these devices, you need to prepare the following images:
\list
\li LaunchImage-iOS7-568h@2x.png: 640 x 1136
\li LaunchImage-iOS7-Landscape.png: 1024 x 768
\li LaunchImage-iOS7-Landscape@2x.png: 2048 x 1536
\li LaunchImage-iOS7-Portrait.png: 768 x 1024
\li LaunchImage-iOS7-Portrait@2x.png: 1536 x 2048
\li LaunchImage-iOS7@2x.png: 640 x 960
\endlist
The images can be added to the Info.plist as follows:
\badcode
<key>UILaunchImages</key>
<array>
<dict>
<key>UILaunchImageMinimumOSVersion</key>
<string>7.0</string>
<key>UILaunchImageName</key>
<string>LaunchImage-iOS7</string>
<key>UILaunchImageOrientation</key>
<string>Portrait</string>
<key>UILaunchImageSize</key>
<string>{320, 568}</string>
</dict>
<dict>
<key>UILaunchImageMinimumOSVersion</key>
<string>7.0</string>
<key>UILaunchImageName</key>
<string>LaunchImage-iOS7</string>
<key>UILaunchImageOrientation</key>
<string>Portrait</string>
<key>UILaunchImageSize</key>
<string>{320, 480}</string>
</dict>
</array>
<key>UILaunchImages~ipad</key>
<array>
<dict>
<key>UILaunchImageMinimumOSVersion</key>
<string>7.0</string>
<key>UILaunchImageName</key>
<string>LaunchImage-iOS7-Landscape</string>
<key>UILaunchImageOrientation</key>
<string>Landscape</string>
<key>UILaunchImageSize</key>
<string>{768, 1024}</string>
</dict>
<dict>
<key>UILaunchImageMinimumOSVersion</key>
<string>7.0</string>
<key>UILaunchImageName</key>
<string>LaunchImage-iOS7-Portrait</string>
<key>UILaunchImageOrientation</key>
<string>Portrait</string>
<key>UILaunchImageSize</key>
<string>{768, 1024}</string>
</dict>
<dict>
<key>UILaunchImageMinimumOSVersion</key>
<string>7.0</string>
<key>UILaunchImageName</key>
<string>LaunchImage-iOS7</string>
<key>UILaunchImageOrientation</key>
<string>Portrait</string>
<key>UILaunchImageSize</key>
<string>{320, 568}</string>
</dict>
<dict>
<key>UILaunchImageMinimumOSVersion</key>
<string>7.0</string>
<key>UILaunchImageName</key>
<string>LaunchImage-iOS7</string>
<key>UILaunchImageOrientation</key>
<string>Portrait</string>
<key>UILaunchImageSize</key>
<string>{320, 480}</string>
</dict>
</array>
\endcode
To support earlier iOS versions, one can use the \c UILaunchImageFile string in the Info.plist:
\badcode
<key>UILaunchImageFile</key>
<string>LaunchImage</string>
\endcode
The name defaults to \c Default, but qmake generates some of the images, so it is easier to use another name (for example LaunchImage as we did) to avoid clashes.
\list
\li LaunchImage.png: 320 x 480
\li LaunchImage@2x.png: 640 x 960
\li LaunchImage-568h@2x.png: 640 x 1136
\li LaunchImage-Landscape.png: 1024 x 748
\li LaunchImage-Landscape@2x.png: 2048 x 1496
\li LaunchImage-Portrait.png: 768 x 1004
\li LaunchImage-Portrait@2x.png: 1536 x 2008
\endlist
You can change the filenames as long as the Info.plist and filenames stay in sync.
Finally, all these files have to be copied to the application bundle by adding something
like the following code snippet to the .pro file:
\badcode
ios {
app_launch_images.files = $$PWD/ios/Launch.xib $$files($$PWD/ios/LaunchImage*.png)
QMAKE_BUNDLE_DATA += app_launch_images
}
\endcode
This allows you to produce universal applications with valid LaunchImages as required by the Apple App Store.
\important \c "launch_images" is used internally by Qt, so it will be overwritten if used in your .pro file.
\section1 Publishing to Apple App Store
Verifying that your Qt for iOS application is ready for publishing to App Store can be done
as described in \l {https://developer.apple.com/Library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/SubmittingTheApp.html} {Submitting the Application}.
To submit the application, you can use Xcode, or the Application Loader (installed with Xcode).
Qt Creator does not provide an interface for managing all of the settings in an Xcode project configuration.
The application should be tested on a variety of iOS versions and devices, depending on what
it's targeted to support. The minimum deployment target for Qt applications is iOS 5.0.
The actual publishing process involves creating a distribution certificate and a provision profile,
creating a signed archive of your application, and running a set of validation tests on it.
See the \l {https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html}
{App Distribution Guide} in iOS Developer Library for more information.
*/
|