Application Icon Troubles

I have posted several times about updating the icon files for an application. First when building a universal app for the iPad and more recently when updating an app for the iPhone 4 retinal display. Apple introduced a new naming convention with iOS 4 to make it easier to handle high and low resolution versions of the same image file (thus we have Icon.png and Icon@2x.png). They also introduced a convention for the CFBundleIconFiles key to avoid having to specify both variations of the file. Here is what the Apple Application Programming Guide says:

When specifying icon files using the CFBundleIconFiles key, it is best to omit the filename extensions of your image files. If you include a filename extension, you must explicitly add all of your image files (including any high-resolution variants) to the array. When you omit the filename extension, the system automatically detects high-resolution variants of your file using the base filename you provide.

This even seems to work at first when testing in the simulator or a device. The problem comes when you validate the built product or try to upload it with the Apple application loader. Unfortunately you are likely to be driven crazy by the following validation error:

Icon specified in the Info.plist CFBundleIconFile does not have an extension: Icon (-19006)

I have not seen any official confirmation from Apple but based on some comments from Apple employees in the development forums it would appear that this is actually a known problem with the application loader supplied with Xcode 3.2.3. For the time being I would recommend specifying the icon names with the extension to avoid this problem.

Test Application Icons

I got sufficiently frustrated with this situation to create a set of application icons covering all possible dimensions to make it possible to understand which icons are actually getting used. The icons are a simple black background with a white number in the middle indicating the size of the file. The icon files are named as follows:

• Icon.png (57 x 57)
• Icon@2x.png (114 x 114)
• Icon-72.png (72 x 72)
• Icon-Small.png (29 x 29)
• Icon-Small@2x.png (58 x 58)
• Icon-Small-50.png (50x50)

If you want them you can download these with a sample application that I created to test out some common scenarios. The application does nothing - it is just the standard Xcode template for a view application. It contains three targets setup as follows:

iPhone 4 Only Application

This setup is for an application that will target only the iPhone running iOS 4 (no iPad or pre iOS 4 releases). It includes standard and high resolution icons for the iPhone 4 device.

• Target Name: Icon40
• Targeted Device Family: iPhone
• iPhone OS Deployment Target: iPhone OS 4.0

The Info.plist file does NOT have the CFBundleIconFile string key, instead it has the CFBundleIconFiles array key which contains two entries (Icon.png and Icon@2x.png).

When run on a normal iPhone or iPod Touch device (running iOS 4) the home screen icon displayed should show “57”. When run on the high-resolution iPhone 4 the home screen icon should show “114”. In addition if you go the spotlight search page and search for Icon you should see the “29” image on the normal phone and “58” on the iPhone 4.

iPhone 4 and iPad 3.2 Application

This scenario adds the iPad and has the following basic target settings:

• Target Name: Icon32
• Targeted Device Family: iPhone/iPad
• iPhone OS Deployment Target: iPhone OS 3.2

The Info.plist file is similar to previous scenario with the addition of the Icon-72.png iPad icon to the CFBundleIconFiles array:

When running on iPhone devices (with iOS 4) it should perform as in the previous scenario. When run on the iPad the home screen icon should show “72” and the spotlight search page should show “50”.

iPhone 4, iPad 3.2 and iPhone 3.x Application

This setup if for all devices back to iPhone 3.x, the target settings are as follows:

• Target Name: Icon31
• Targeted Device Family: iPhone/iPad
• iPhone OS Deployment Target: iPhone OS 3.1

The Info.plist file contains the CFBundleIconFile key for 3.1 compatibility with the value Icon.png together with the CFBundleIconFiles key from the iPad example:

This should run with the older 3.x devices showing “57” on the home screen but with newer iPhone 4 devices showing 114 (and the iPad showing 72).

Updating for the iPhone 4 retinal display

The retinal display on the new iPhone 4 doubles the pixel resolution of the display. However when it comes to laying out the UI elements you can still think about a full screen display with dimensions of 320 x 480 in portrait mode. The big difference is that these dimensions are now expressed in points NOT pixels. What has changed is the scaling factor of the screen which determines how a point relates to a pixel. For the iPhone 4 the display has a scale of 2 so that 1 point = 2 pixels.

The number of pixels on the display has doubled to 640 x 960 but if you are using UIKit this added complexity is mostly hidden from the application. The UI layout is configured using the point dimensions so thankfully you do not have to worry about redoing the layout just for iPhone 4 devices. Also things like text and standard Apple UI components such as navigation bars, system buttons, etc are automatically displayed at the higher pixel resolution. Note that if you are using core graphics or core animation you will have some additional work to do as those frameworks only work with pixels not points.

There are some additional steps that are worth doing if you want your app to look its best on the iPhone 4.

2x Image Files

Apple has introduced a simple naming convention to allow image files at double the resolution to be loaded when the display will support it. To make use of this feature you need to go back to your original image files and create versions at twice the existing size. So if you have an image that is currently 100x100 pixels named myImage.png you need to create a new version which is 200x200 pixels named myImage@2x.png.

You should probably avoid just taking the existing image file and scaling it up to double the size. Ideally you want to create your images at the higher resolution and then scale down to the standard resolution so that both sizes look their best.

Once you have the high-resolution image files you just need to add them to your project and they will be selected automatically anytime you use UIImage class methods such as +imageNamed: or +imageWithContentsOfFile: So for example:

UIImage *myImage = [UIImage imageNamed:@”myImage.png”];

will load myImage.png on iPhone 3 and iPad devices but will load myImage@2x.png on the iPhone 4. It is possible to omit the filename extension from the name of the image file with iOS 4 but you will need to include it if you want to maintain compatibility with 3.x releases.

Applications Icons

As well as updating image files you should also update the application icon files to include high-resolution versions of each file. So since the original iPhone application icon file is 57x57 pixels the 2x version needs to be 114x114 pixels. In addition the settings/search icon which is normally 29x29 pixels needs a high-resolution version that is 58x58 pixels.

With iPhone OS 3.2 for the IPad a new key (CFBundleIconFiles) was introduced to Info.plist to specify the ever growing list of icon files. If you are producing an App that will only run only on iOS 4.0 and 3.2 you can use CFBundleIconFiles (you can delete the old CFBundleIconFile key if you want since it will no longer be used).

If you do not specify the filename extensions you can avoid listing all of the 2x variations of the file. So if we have an iPhone icon, an IPad icon and the corresponding settings/search icons the entry in Info.plist would be as follows:

If we want to maintain compatibility with pre-3.2 devices we cannot rely on the CFBundleIconFiles key. Instead we need to specify the icon files using the Apple determined naming convention. The files we would need to support all devices would be as follows:

• Icon.png - 57x57 pixels application icon for standard resolution iPhone
• Icon@2x.png - 114x114 pixels application icon for high resolution iPhone 4
• Icon-72.png - 72x72 pixels application icon for iPad
• Icon-Small.png - 29x29 pixels settings icon for standard resolution iPhone
• Icon-Small@2x.png - 58x58 pixels settings icon for high resolution iPhone
• Icon-Small-50.png - 50x50 pixels settings icon for iPad

Then in the Info.plist file we need to use the original CFBundleIconFile key to specify just the basename of the icon file (“Icon.png”) as follows:

Launch Images

As with the application icons you can also specify high-resolution versions of your launch images. So a standard resolution portrait launch image named Launch.png is 320x480 pixels. The high resolution version would be 640x960 pixels and named Launch@2x.png.

Likewise a landscape version of the file named Default-Landscape.png would be 480x320 in standard resolution (assuming a status bar) and named Default-Landscape@2x.png with 960x640 pixels in high resolution.

Update on Tuesday, August 3, 2010 by Keith

To avoid validation errors when uploading to the App Store I find that the old CFBundleIconFile needs to also specify the extension (Icon.png). I have created an example app to illustrate the different configurations that I will try to post in the next few days to clear up the confusion.

See this post for more details on the problem with the version of Application Loader shipped with Xcode 3.2.3: Application Icon Troubles.