What this guide is about
- Minimum Titanium SDK version: 5.2.0
- Minimum iOS SDK version: 8.0
What are Launch Files?
Until now, you used to create a bunch of
Default*.png Launch Images. In iOS 8 Apple introduced Launch Files. These are the same XIB files or Storyboards that you’d normally build you UI with in Xcode. This means you can use any iOS UI component and only need one file to support all devices. When you app first runs, iOS takes a snapshot image of the launch file to use as launch image. A great way to slim down your IPA!
Why use Launch Files?
The iPad Pro no longer supports Launch Images. Without it, a (Titanium) iOS app will be stretched to fit the iPad Pro:
Split View and Slide Over for the iPad also requires Launch Files. Since your app might now be opened as Slide Over in either landscape or portrait you would otherwise need 6 more launch images to cover the different sizes of iPad screens out there.
Launch Files allow you to strip down the size of your final
.ipa considerably. You only need a single storyboard and a logo in a handful of densities to cover all iOS devices.
How to enable Launch Files?
You have two ways to use Launch Files: with our builtin Storyboard or your own.
Both need to be enabled in the
<ios> section of your tiapp.xml:
The templates for new Titanium projects have this property enabled by default.
Option A: Use the builtin Storyboard
Customising the image
By default we’ll generate the image from
DefaultIcon[-ios].png. To use a different image, add the following
LaunchLogo*.png files to the app/assets/iphone folder:
Customising the background color
By default the background color is white. You can set a different color via the
<ios> section of your tiapp.xml:
This will also change the background color of your app between after the launch files is dismissed and before a view (with a solid background color) is opened, or Ti.UI.backgroundColor is set. The sample opens with a 2s delay so you can see this better.
Option B: Use a custom Storyboard
To use a custom Storyboard, put this file in app/platform/ios/LaunchScreen.storyboard (for Alloy projects) or platform/ios/LaunchScreen.storyboard (for classic projects). As you can see the sample has it disabled using a
_ prefix. Just remove the underscore and do a clean build to see the difference:
As you can see I’ve used an iOS Activity Indicator. Notice that it is not spinning as iOS uses a snapshot image of the storyboard.
To use an image in your custom Storyboard, simply set the
Image property of an Image View to the path under
app/assets/ without the image modifier (
@2x) or extension:
Important: If you have the use-app-thinning enabled, you will have to use the name of the generated asset catalog. This is a hash based on the image path. To find out the hash for your image build the app, look up the right
build/iphone/Assets.xcassets/ and use the
Using native Storyboards, you can even do complex complex layouts inside your launch-screen, for example split-screen layouts. To do so, open the
LaunchScreen.storyboard in Xcode and start adding UI-elements from the bottom right "Object library":
Now drag the "Split View Controller" element to the center, remove the old "View Controller" and set the Split View Controller as the "Initial View Controller". Finally, add a label to the detail-view by searching and dragging the "Label" object into your space:
Thats it! Save the storyboard, clean the build directory and cache (see chapter below) and run your app. If you want to include images, make sure to check the "Use images" paragraph above to handle image hashes.
Dealing with Launch File cache
As you modify the (custom) storyboard, you might not always see your changes immediately. This is because iOS caches the snapshot it makes from your Launch File and a known issue where Titanium does not always recompile the storyboard.
To deal with this follow these steps before you build:
- Use Simulator > Reset Content and Settings…
- Use Project > Clean… or
appc ti cleanfrom CLI.
Alternatively you can reset an individual app using a tool like SimPholders. With this app, just hold
alt/⌥ and click the app from the dropdown: