Important: Please read the Qt Code of Conduct - https://forum.qt.io/topic/113070/qt-code-of-conduct

Use Launch images in iOS project



  • Hello there,
    I am using Qt 5.13.0 for iOS app development. I was trying to add custom launch images by following this guide: https://doc.qt.io/qt-5/ios-platform-notes.html#native-image-picker and I got lost.

    First of all, I have copied the generated by default info.plist file to my custom dir:

    ios {
        QMAKE_INFO_PLIST = ios/info.plist
    }
    

    Then I created these 6 images and added them to the ios dir:

    LaunchImage-iOS7-568h@2x.png: 640 x 1136
    LaunchImage-iOS7-Landscape.png: 1024 x 768
    LaunchImage-iOS7-Landscape@2x.png: 2048 x 1536
    LaunchImage-iOS7-Portrait.png: 768 x 1024
    LaunchImage-iOS7-Portrait@2x.png: 1536 x 2048
    LaunchImage-iOS7@2x.png: 640 x 960
    

    My plist then looks as follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
    	<key>CFBundleDisplayName</key>
    	<string>${PRODUCT_NAME}</string>
    	<key>CFBundleExecutable</key>
    	<string>${EXECUTABLE_NAME}</string>
    	<key>CFBundleGetInfoString</key>
    	<string>Created by Qt/QMake</string>
    	<key>CFBundleIconFile</key>
    	<string>${ASSETCATALOG_COMPILER_APPICON_NAME}</string>
    	<key>CFBundleIdentifier</key>
    	<string>${PRODUCT_BUNDLE_IDENTIFIER}</string>
    	<key>CFBundleName</key>
    	<string>${PRODUCT_NAME}</string>
    	<key>CFBundlePackageType</key>
    	<string>APPL</string>
    	<key>CFBundleShortVersionString</key>
    	<string>${QMAKE_SHORT_VERSION}</string>
    	<key>CFBundleSignature</key>
    	<string>${QMAKE_PKGINFO_TYPEINFO}</string>
    	<key>CFBundleVersion</key>
    	<string>${QMAKE_FULL_VERSION}</string>
    	<key>LSRequiresIPhoneOS</key>
    	<true/>
    	<key>MinimumOSVersion</key>
    	<string>${IPHONEOS_DEPLOYMENT_TARGET}</string>
    	<key>NOTE</key>
    	<string>This file was generated by Qt/QMake.</string>
    	<key>UILaunchStoryboardName</key>
    	<string>Launch</string>
    	<key>UISupportedInterfaceOrientations</key>
    	<array>
    		<string>UIInterfaceOrientationPortrait</string>
    		<string>UIInterfaceOrientationPortraitUpsideDown</string>
    		<string>UIInterfaceOrientationLandscapeLeft</string>
    		<string>UIInterfaceOrientationLandscapeRight</string>
    	</array>
    	<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>
    </dict>
    </plist>
    

    Now modified the *pro file:

    ios: {
        QMAKE_INFO_PLIST = ios/info.plist
        app_launch_images.files = $$PWD/ios/Launch.xib $$files($$PWD/ios/LaunchImage*.png)
        QMAKE_BUNDLE_DATA += app_launch_images
    }
    

    And my problem now is that I don't know how am I supposed to get the Launch.xib file. Initially, I have copied the created by default 'LaunchScreen.xib" to my ios dir as Launch.xib. The project then compiled, but the launch screen is not showing when the app is opening.

    I would appreciate all help.



  • Hi,
    I'll leave my solution for those who'll be seeking it.
    There was a bug https://bugreports.qt.io/browse/QTBUG-57502 regarding this and though it's marked as closed, I don't see it solved.

    1. Add xcassets catalog to your project that would include AppIcon.appiconset and LaunchImage.launchimage folders. Add the images and corresponding Contents.json. (The easiest way is to create a dummy project in Xcode, add everything there, and then copy the resulting catalog to your project.)
      Add the catalog in the ios section of your .pro file, e.g.:
      QMAKE_ASSET_CATALOGS += resources/Images.xcassets

    2. Add following key to you plist file:

    <key>UILaunchImageFile</key>
    <string>LaunchImage</string>
    

    Where LaunchImage is the base name of the the image inside the .launchimage folder of the catalog (see Apple's docs on how the names can be constructed). Make sure the UILaunchStoryboardName key is not present.

    1. Add a magical command to the .pro file as suggested in the bug report:
       asset_catalog_launchimage.name = "ASSETCATALOG_COMPILER_LAUNCHIMAGE_NAME"
       asset_catalog_launchimage.value = LaunchImage
       QMAKE_MAC_XCODE_SETTINGS += asset_catalog_launchimage
    

    where the LaunchImage is the actual name (prefix) of the .launchimage folder.

    To explain: at the time of writing (under iOS 12) the launch images are described by the Contents.json of the .launchimage folder of an assets catalog. To use images instead of storyboard, a UILaunchImageFile must be specified (while the storyboard not) and a build variable ASSETCATALOG_COMPILER_LAUNCHIMAGE_NAME must be set in the Xcode project. The steps above do just that.
    Too bad official Qt platform notes for iOS are misleading at the moment (at least I couldn't get them to work).



  • @eliseev Hi, thank you for the answer!
    Ill try to follow your instructions as soon as I get to this topic again.



  • CORRECTION
    I have to confess I was wrong about Qt's documentation.
    The instructions at https://doc.qt.io/qt-5/ios-platform-notes.html#launch-images are correct, while my advice above has a limited use (it should work while you stay within list of devices managed by Xcode for launch images, but will fail for those unknown to it, e.g. all iPad Pro lineup).
    The only correction to Qt's documentation I would make is to remove all special suffixes from image names, i.e. don't name them like LaunchImage-iOS7-Landscape@2x.png but rather just like LaunchImage-iPadPro10-landscape.png, LaunchImage-iPadPro11-portrait.png etc. The suffixes screw things up in my experiences. Also an important note, when defining image sizes, e.g. {768, 1024}, do not swap the numbers for landscape, they are the same as for portrait despite logical assumption to make it {1024, 768} - it won't work.

    Note, for the UILaunchImages key the files must be added to the app bundle via e.g.

    ios {
        ios_launch_images = $$files($$PWD/img/ios/LaunchImages/*.png)
        QMAKE_BUNDLE_DATA += ios_launch_images
    }
    

    I think this piece is missing in the documentation.

    The bottom line:

    • Using UILaunchImages key in the plist file for adding launch images is a correct way for iOS12 (to be tested on 13).
    • Do not define UILaunchStoryboardName or UILaunchImageFile at the same time with UILaunchImages.
    • Avoid Naming Your Launch Image Files convention specified for UILaunchImageFile key.
    • Apple really wants us to use launch storyboard, go for it, if you can.

    Happy coding!

    -sergey



  • @eliseev Thanks for the update. I will try to make a retry on this asap.



  • Note that iOS has a bug where it caches old launch screens
    https://stackoverflow.com/a/35783070


Log in to reply