qt-everywhere-src-5.15.1/qtdoc/doc/src/platforms/ios.qdoc - orbit - Git at Google

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