| /**************************************************************************** |
| ** |
| ** Copyright (C) 2017 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 ios.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, iPads, and iPod Touches. |
| |
| \target ios-supported-configurations |
| \section1 Supported Configurations |
| |
| The following configurations are supported. |
| |
| \include supported-platforms.qdocinc ios |
| |
| \include apple-getting-started.qdocinc getting started |
| |
| \section1 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 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 ios-building-from-source.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 ios-platform-notes.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 \macos. 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 \macos 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 = $$files(fonts/*.ttf) |
| fontFiles.path = fonts |
| QMAKE_BUNDLE_DATA += fontFiles |
| } |
| \endcode |
| |
| For image resources, an alternative way is to make use of \l {Create asset catalogs and sets} |
| {asset catalogs} in Xcode, which can be added in a similar way: |
| \badcode |
| ios { |
| QMAKE_ASSET_CATALOGS += ios/Assets.xcassets |
| } |
| \endcode |
| |
| \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 {App Icons on iPhone, iPad and Apple Watch}{Icon files}. |
| The filename is not important, but the actual pixel size is. |
| Just a few icons are required. |
| However, to support both iPhone and iPad, 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/design/human-interface-guidelines/ios/icons-and-images/launch-screen/}{Launch Screen}. |
| 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. |
| |
| \section2 Native Image Picker |
| |
| If your \c Info.plist file contains an entry for \c NSPhotoLibraryUsageDescription, qmake will |
| automatically include an extra plugin which enables access to the native image picker. If the directory |
| in your QFileDialog is set to: |
| |
| \badcode |
| QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last(); |
| \endcode |
| |
| or alternatively the folder in a FileDialog in QML to: |
| |
| \badcode |
| shortcuts.pictures |
| \endcode |
| |
| then the native image picker is shown to allow access to the user's photo album. |
| |
| \section2 Expressing Supported iOS Versions |
| |
| \include expressing-apple-os-versions.qdocinc expressing os versions |
| |
| \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 the iOS versions and devices that it is |
| targeted to support. The minimum deployment target for Qt applications |
| varies by Qt version. For more information, see |
| \l{ios-supported-configurations}{supported configurations}. |
| |
| 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. |
| */ |