This article examines how to use images in Xamarin.iOS, both application support images (such as icons, loading images, etc.) and images within applications (such as images applied to controls). It also covers how to use your IDE to incorporate images as well as how to interact with images from code.
Xamarin.iOS makes it easy to add great artwork to your iOS applications. This article looks at how to use Xamarin.iOS to take advantage of iOS image support. iOS defines two basic categories where icons and images are used, application support images and images applied to controls. In both cases, iOS has built in support for handling various device resolutions. More specifically, here are the three iOS image-handling topics we’re going to cover in this article:
- Application Support Images – These include image locations defined by the system such as application icons, loading screens, settings, and spotlight search icons.
- Resolution Independent Images – iOS includes built-in support for working with images across different device resolutions
- Images in Code – The UIImage class includes methods for loading images that can be applied to controls.
Application Support Images
There are several different places where iOS uses images to support applications. Application icons and launch screen images are two of the types of images used in this way. For example, here are three iOS 7 screenshots on the iPad that illustrate the main application icon, the icons that show up in spotlight, and the icons on the Settings screen:
Applications that target iOS 7 and later require only the following icons (all sizes are given in pixels):
|Image||Platform||Normal size||Retina (@2x)|
|Spotlight search results||All||40x40||80x80|
The following table lists the various images required by iOS 6.1 and earlier:
|Image||Description||iPhone||iPhone Retina Display||iPad||iPad Retina Display||iPhone5|
|Application Icon||Icon displayed on the device’s home screen, used to launch an application.||57x57||114x114||72x72||144x144||114x114|
|Settings Icon||Icon used to identity an application in the iOS Settings Application.||29x29||58x58||29x29||58x58||58x58|
|Spotlight Search (uses same image as Setttings on iPhone)||Icon used to identify an application in the Spotlight Search results.||29x29||58x58||50x50||100x100||58x58|
To support both iOS 6.1 and iOS 7 applications should embed icon images from both preceding tables.
In addition to application icons, a launch image and an iTunes image should be supplied (these are required for both iOS 6.1 and earlier, as well as iOS 7). The dimensions for each platform are:
|Image||Description||iPhone||iPhone Retina Display||iPad||iPad Retina Display||iPhone5|
|iTunes Image||Large image used by iTunes during ad hoc distribution.||512x512||512x512||512x512||512x512||1024x1024|
|Launch Image||Image used as a placeholder screen while the application loads.||320x480||640x960||Portrait: 768x1004 Landscape: 1024x748||Portrait: 1536x2008 Landscape: 2048x1496||640x1136|
iOS is designed to make it easy to offer a consistent, familiar user experience across applications. Relying on the system-defined standards for various images, both within the application and at various places in the operating system is one way it achieves this.
The Application Icon
Every iOS application must define an application icon. This is the icon that the user will tap from the iOS home screen to launch the application. Additionally, this icon is used by Game Center, if applicable. For example, the following screenshot illustrates the application icon on the iOS home screen for an application called “Images:”
On older versions of iOS (6.1 and earlier), the application icon resolution was 57x57 pixels for earlier models and 114x114 for Retina iPhone devices; and 72 or 144 pixels square for normal and Retina iPads respectively.
iOS 7 uses different sizes: 60x60 (120x120 Retina) for iPhones and 76x76 (152x152 Retina) for iPads. In order to support both the older and newer generation operating systems you should provide images for all applicable resolutions.
Note: The examples in this section use a universal application created from the Xamarin.iOS Project – Universal application template in Xamarin Studio.
Adding Images with Xamarin Studio and Visual Studio
In order to add the images for an application icon, we first need to add the images to the project. To accomplish this perform the following steps in Xamarin Studio:
- Right-click on the Resources folder (or Ctrl-Click) and select Add > Add Files…, displaying the Add files dialog window (shown below).
- Select the image files with the appropriate resolutions to add to the project.
- Select OK.
- Choose the option to copy the files into the project’s location.
In Visual Studio, use Add > Existing Item...
The images you selected will appear in the Solution Navigator, with their build actions set to Bundle Resource. When you use this build action, the content in your images is placed in your application bundle. If you right-click on any of the images in Xamarin Studio, you can view the current build action in the context menu as shown here:
In Visual Studio, right click on the image and select Preferences to bring up the preferences pane:
Configuring Icons with Property Lists
With the appropriately sized images included in your project, you are now ready to assign them to the application icon. In the solution pad, double-click on a file named Info.plist (or double-click on the project and select the iPhone Application item in the left pane) to bring up the built-in property list (pist) editor in Xamarin Studio.
Info.plist (plist stands for property list) is a file that contains various settings for an application, such as what icon files should be used, and what devices and orientations are supported. Both Xamarin Studio and Xcode provide user interfaces to make editing it easier, although it is an XML file, and so you can also edit it in your favorite text editor.
In the property list editor, under the Application tab, scroll down to the section titled Universal Icons. Under the App Icons section, you’ll see some placeholders showing the required resolution of each image:
Visual Studio provides limited support for plist editing. In Visual Studio, you can edit the project's Info.plist in project Preferences, under the iOS Application pane. The instructions for setting icons in Visual Studio are exactly the same as in Xamarin Studio:
Click on each of them to bring up the Select Icon… dialog, which will allow you to select the images you previously added to the project:
Select the 57x57 image for the first icon, the 114x114 one for the iPhone Retina display, and the 72x72 one for the iPad, and the 144x144 image for the iPad Retina display. After you select the images, you’ll see a preview of each in the Info.plist editor:
If you run the application now, the application icon will be replaced with the appropriate icon for the device you are running on.
Pre-rendered Icons (iOS 6.1 and earlier)
iOS and earlier automatically rounds the corners of your application icons, so icon images should be square (do not attempt to round the corners yourself). iOS6.1 and earlier applies a gloss as well, however you can opt-out of the gloss effect by setting the UIPreRenderedIcon key in Info.plist.
In order to use UIPreRenderedIcon for iOS 6.1 and earlier, check the "Prerendered" box in the App Icons row.
With the Prerendered option checked in Info.plist, iOS no longer adds a gloss effect to your application icon:
Settings and Spotlight Search Icons
You can optionally provide images for iOS to display in the Settings application and in spotlight search results. Much like the application icon, you should provide both low and high-resolution versions. Here are examples of settings and spotlight search icons:
The iPad and the iPhone/iPod Touch have different image requirements. For the size requirements, you should refer to the table at the beginning of this article.
The same image is used for both settings and for spotlight search on the iPhone. However, the iPad requires two different images.
Note: iOS adds a 1-pixel shadow around the spotlight image, resulting in the actual size being trimmed down to 48x48.
Adding images for the settings and spotlight icons is similar to the procedure you used to add the application icon. Simply assign the appropriately sized images under the Spotlight and Settings Icons section in Xamarin Studio or Visual Studio:
If you are planning on distributing your application using ad hoc distribution, you also need to supply a 1024x1024 image that will be used to represent your application by iTunes. You can add this image in your IDE under the iTunes Artwork section.
Here it is in Visual Studio:
Launch Screen Images
After the user taps the application icon and before the first view appears, a blank screen will be shown. Fortunately, iOS includes support for displaying an image of your choice in place of the blank screen. Some applications use this as a splash screen, and others display something that resembles the first view in their application.
Like other images, the resolution for this screen depends upon the device you are targeting. Additionally, if you’re targeting the iPad, remember that it supports different launch images for portrait or landscape orientations, as well as the Retina display. Unlike the other images we have looked at so far, launch images need to be located in the root of the project and they must follow specific naming conventions. Unlike application icons, as long as the launch images are present in the project’s root folder and appropriately named, they will appear when the application is launched.
iPhone Launch Images
For the iPhone/iPod Touch you should supply both low and high-resolution versions of the launch images as specified in the table below:
|Device Target||File Name||Size (in pixels)|
iPad Launch Images
Specifying the launch images for the iPad is similar, but there are a few
differences listed here:
On the iPad you can optionally supply images for every vertical and horizontal orientation.
The iPad’s launch screen will display the status bar, accounting for
20-pixels at the top of the screen in every orientation.
If multiple images are present, there is an order of precedence that determines which images will be applied.
The following table lists the various launch images for the iPad in ascending order of precedence, with the Retina display versions of each image being double the pixel size and following the [image name]@2x~ipad.png naming convention:
|File Name||Size (in pixels)||Use|
|This is the basic loading image that is used if a more specific image is not available. If no more specific images are supplied, this should be present.|
|This is the generic portrait-loading image. This image is used for right side up (home button on bottom) portrait orientations and takes precedence over Default~ipad.png. Therefore, if you supply this image, Default~ipad.png is not used. Additionally, if Default-PortraitUpsideDown~ipad.png is not supplied, this image is used.|
|This is the generic landscape-loading image. This image takes precedence over Default~ipad.png. Therefore, if you supply this image, Default~ipad.png is not used. Additionally, if Default-LandscapeLeft~ipad.png or Default-LandscapeRight~ipad.png is not supplied, this image is used.|
|This is the portrait upside-down (home button on top) loading image.|
|This is the landscape left (home button on left) loading image.|
|This is the landscape-right (home button on right) loading image.|
Here are pictures of the loading screens for an iPad application in portrait and horizontal orientations, shown on a low resolution iPad:
Unless you want to have different images for each orientation, you only need to supply a Default~ipad.png image, or Default@2x~ipad.png for Retina display, if your application only supports portrait mode. If your app only supports landscape orientation, you only need the Default-Landscape~ipad.png image, or Default-Landscape@2x~ipad.png for Retina display. If you support both landscape and portrait orientation, then you should supply at least these two images. Supporting only the default portrait and landscape orientations significantly reduces the number of images you must create, since supplying one for every orientation is typically overkill.
For more information about loading images, see the Apple documentation on Custom Icon and Image Creation Guidelines.
Setting launch images with Xamarin Studio and Visual Studio
Setting launch images with Xamarin Studio
If you select the placeholders in Xamarin Studio to set the various launch images, you will be presented with the Select launch image dialog. This will give you a different set of choices than the image-selecting dialog we’ve seen so far. Here’s a screenshot of this Xamarin Studio dialog:
Here it is in Visual Studio:
Using this dialog, Xamarin Studio will copy the images into the root of your project and rename them appropriately for you. After they’re imported, they’ll show up in the Info.plist editor (though they’re not actually defined in Info.plist):
Visual Studio will do the exact same thing:
If your application supports loading a particular document type, you can provide icons that the system will use when it encounters that document type, such as when a user holds down an attachment in the Mail Application as shown here:
You can add document type information for a file format your app is capable
of opening by including dictionary entries for the
LSItemContentTypes array in your Info.plist. The icons
for the document type go in the CFBundleTypeIconFiles array. If you don’t
provide a document icon, iOS will derive one from your application icon.
Remember that you can supply icons of several sizes, optimized for the various
device resolutions. Fortunately, Xamarin Studio makes it easy to work with all
To assign these values in Xamarin Studio, use the Document Types section under the Advanced tab on the Info.plist editor. There you can add the document type and assign image icons to it. For example, here is a screenshot showing registration for PDF support:
There is no advanced plist editor in Visual Studio at this time,
so you have to edit document icons manually. Double click on your Info.plist file to open it,
and add the following code under
<key>CFBundleDocumentTypes</key> <array> <dict> <key>CFBundleTypeIconFiles</key> <array> <string>Resources/doc_icon.png</string> <string>Resourcesfirstname.lastname@example.org</string> </array> <key>CFBundleTypeName</key> <string>PDF</string> <key>LSHandlerRank</key> <string>Alternate</string> <key>LSItemContentTypes</key> <array> <string>com.adobe.pdf</string> </array> </dict> </array>
It should end up looking something like this:
Using Images with Controls
We’ve seen how you can use icons and images to support your applications, but iOS also uses images with application control types such as tab bar controls, toolbars, navigation bars, tables, and buttons. A simple way for you to make an image appear on a control is to assign a UIImage instance to the control’s Image property. The UIImage class includes two static methods for loading images, FromBundle and FromFile. Let’s take a closer look at those methods.
FromBundle method call is a synchronous (blocking) call that
has a number of image loading and management features built-in, such as caching
support and automatic handling of image files for various resolutions.
The following code, from the Xamarin.iOS Tabbed Application – Universal template, shows you how to assign a
UIImage to a
this.TabBarItem.Image = UIImage.FromBundle ("Images/first");
This code assumes an image was included in the solution under a folder called Images, with a name of first.png as shown below:
If you use the Add > Add Files… menu option and set the build action to BundleResource, Xamarin Studio will include this image in the application bundle when you build it.
When it runs on a high-resolution (Retina) device, the
FromBundle method uses a convention that causes any file with an
@2x suffix to be loaded automatically, without requiring any special code to
accommodate this. In this case, for example, you would have one image named
first.png and a second named email@example.com. Also, in iOS 4 or later, a naming convention of
[image name]~ipad.png or [image name]~iphone.png will result in the correct
image being loaded for each device. For the iPad Retina display, the convention
is [image name]@2x~ipad.png. If you don’t include a file with this suffix, the
system looks for a file with the original file name, such as first.png in the
preceding example, which may result in a low-resolution image being used.
Your images are cached when you use
FromBundle to load them.
You'll appreciate this in scenarios where you need to repeatedly load the same
image. However, be aware that the images may remain in memory after you are
through using them, and this can cause memory bloat. Unfortunately, there are no
mechanisms available to manage this image cache.
The application template includes an instance of a
UITabBarController class, along with two tabs, each represented
with an instance of a
TabBarItem class. The second.png and firstname.lastname@example.org images
are used to populate the TabBarItem image for the second tab in the
UITabBarController instance. At runtime, each
TabBarItem instance includes the image that was assigned to it, as
In addition to the
FromBundle method, UIImage also has a method
FromFile is a lighter-weight
FromBundle. It doesn’t use caching and so you
don’t have to worry about the positive or negative memory implications of
caching. Additionally, FromFile is asynchronous, so it won’t block the main
thread; it lazy-loads your images as needed for each to be displayed.
FromFile is similar to using
except that you have to pass the entire file path, including file suffix. For
example, the following code loads a tab bar image using
this.TabBarItem.Image = UIImage.FromFile("Images/second.png"):
The following list summarizes the differences between
FromFileis asynchronous; whereas
FromFilecan load images from an external location; whereas
FromBundlecan only load images that you include with your application.
FromFileprovides no built-in caching; whereas
FromBundleautomatically caches an image after it is loaded.
Guidance on Using FromBundle vs. FromFile
Generally, you should use
UIImage.FromFile when loading several
images at one time, since it lazy-loads images asynchronously. You’ll want to
UIImage.FromBundle only when loading the same image
Important Image Considerations
There are a few more points you should be aware of regarding images and iOS:
By default, unless your OS X file system has been formatted with a case-sensitive format, the simulator is not case-sensitive, however the device is. Therefore, code that works in the simulator can result in a crash on the device if you aren’t careful with the case when loading files. For this reason, it’s important to test early and often on an actual device.
Do not name your folder “Resources.” iOS disallows the use of this name and it will cause an application crash.
Set the build action to BundleResource if you want an image to be included in the application bundle. Generally, Xamarin Studio will set this automatically for you, but if you get a runtime error that says the image cannot be found, double-check this.
For more information about icons and images, see the Apple documentation on Custom Icon and Image Creation Guidelines.
In this article we’ve covered how to use Xamarin.iOS and Xamarin Studio to include images in your applications. We’ve seen how to incorporate application support images such as the application icon, settings, and spotlight icons and how to launch images. You’ve also seen how to target images to different devices and resolutions. Finally, we’ve examined how to work with images directly from code.