VISUAL STUDIO   Windows Mac

Displaying an Image

Using an Image in a Xamarin.iOS Application UI.

PDF for offline use
Sample Code:
Related Articles:
Related SDKs:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2017-03

This article covers deprecated methods used for including an image asset in a Xamarin.iOS app and displaying that image either by using C# code or by assigning it to a control in the iOS Designer.

Overview

This article covers several deprecated image technologies and technique that might be required to maintain an older Xamarin.iOS app:

Adding and Organizing Images in a Xamarin.iOS App

When adding an image for use in a Xamarin.iOS app, there are several places and ways that the developer can include image file to the Project's source:

  • Main Project Tree [Deprecated] - Images can be added directly to the Projects tree. When calling images stored in the Main Project Tree from code, no folder location is specified. For example: UIImage.FromFile("Image.png").
  • Resources Folder [Deprecated] - The special Resources folder is for any file that will become part of the Application's Bundle such as Icon, Launch Screen or iTunes artwork Images (or any other image or file the developer wishes to add). When calling images stored in the Resources folder from code, just like images stored in the Main Project Tree, no folder location is specified. For example: UIImage.FromFile("Image.png").
  • Custom Folder or Subfolder [Deprecated] - The developer can add a custom folder to the Projects Source Tree and store the images there. The location where the file is added can be nested in a subfolder to further help organize the project. For example, if the Developer added a Card folder to the project and a sub folder of Hearts to that folder, then store an image Jack.png in the Hearts folder, UIImage.FromFile("Card/Hearts/Jack.png") would load the image at runtime.

Adding Images to a Folder

⚠️

NOTE: This method of working with images in an iOS app has been deprecated by Apple. The developer should use Asset Catalog Image Sets to manage an app's images instead.

Do the following:

  1. To help organize the image files in the Project Source Tree, the developer can optionally create a set of folders and/or nested sub folders by simply selecting the location for the folder in the Solution Explorer, right-clicking, then selecting Add > New Folder:

  2. Name the new folder and repeat the process to create any required sub folders, as in the following screenshot where an Images directory houses a subdirectory to hold the different color variations of a given image asset:

  3. Whether adding images to an existing project folder (such as the default Resources folder), or creating a custom set of folders and subfolders and storing the images there, the process is the same. Highlight the desired folder in the Solution Explorer, right-click and select Add > Add Files...:

  4. Select one or more files in the Add Files dialog box and click the Open button and the image asset will be included in the project:

  5. At the bottom of the Add Files dialog box, the Override build action dropdown list should be left on the default value of (Default). It can optionally be set to BundleResource or Content as well, since that value is required for image assets in iOS, but the default behavior is usually correct.

To modify the Build Action of an image asset once it has been included in an application, select the image asset in the Solution Explorer, right-click and select Build Action:

  1. To help organize the image files in the Project Source Tree, the developer can optionally create a set of folders and/or nested sub folders by simply selecting the location for the folder in the Solution Explorer, right-clicking, then selecting Add > New Folder:

  2. Name the new folder and repeat the process to create any required sub folders, as in the following screenshot where an Images directory houses a subdirectory to hold the different color variations of a given image asset:

  3. Whether adding images to an existing project folder (such as the default Resources folder), or creating a custom set of folders and subfolders and storing the images there, the process is the same. Highlight the desired folder in the Solution Explorer, right-click and select Add > Existing Item...:

  4. Select one or more files in the Add Files dialog box and click the Add button and the image asset will be included in the project:

To modify the Build Action of an image asset once it has been included in an application, select the image asset in the Solution Explorer. In the Property Explorer select the new build action from the Build Action dropdown:

Using Images with Controls

⚠️

NOTE: This method of working with images in an iOS app has been deprecated by Apple. The developer should use Asset Catalog Image Sets to manage an app's images instead.

Images can be used to support an app, but iOS also uses images with app control types such as tab bars, toolbars, navigation bars, tables, and buttons. A simple way 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.

FromBundle

The 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, shows how to assign a UIImage to a Tab Bar Item’s Image property:

TabBarItem.Image = UIImage.FromBundle ("Images/SunSet.JPG");

This code assumes an image was included in the solution under a folder called Images, with a name of SunSet.JPG as shown below:

When using the Add > Add Files… menu option and setting the build action to BundleResource, Xamarin will include this image in the application bundle when it is built.

As stated in the Image Sizes and Filenames document, if the developer includes high resolution version of an image decorated with the @2x or @3x identifiers and the users are running on a high resolution Retina device, the FromBundle method will automatically use the high resolution version of the image if it exists. In addition, the developer can add the ~iphone and ~ipad identifiers to specify that a specific image file is to be used on a specific device.

For example, if the following files were included in the iOS project:

  • Image.png
  • Image@2x.png
  • Image@3x.png
  • Image2~iphone.png
  • Image2~ipad.png
  • Image2@2x~ipad.png

Calling FromBundle("Image") would do the following on the following devices:

  • iPhone 3 - would load the Image.png file.
  • iPhone 5 - would load the Image@2x.png file.
  • iPhone 6 Plus - would load the Image@3x.png file.

Calling FromBundle("Image2") would do the following on the following devices:

  • iPhone 6 - would load the Image2~iphone.png file.
  • iPad 1 - would load the Image2~ipad.png file.
  • iPad Air - would load the Image2@2x~ipad.png file.

The images are cached when using FromBundle to load them. This works best in scenarios where images need to repeatedly loaded. However, be aware that the images may remain in memory after the app is through using them, and this can cause memory bloat. Unfortunately, there are no mechanisms available to manage this image cache.

FromFile

UIImage also contains the FromFile method, which is a lighter-weight alternative to FromBundle. It doesn’t use caching and so the developer doesn'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 the images as needed for each to be displayed.

Using FromFile is similar to using FromBundle, except that the developer has to pass the entire file path, including file extension. For example, the following code loads a tab bar image using FromFile:

this.TabBarItem.Image = UIImage.FromFile("Images/second.png"):

Just like the FromBundle method, the FromFile method will automatically select a high resolution version of the image (@2x, @3x) if it exists and will take into consideration images named with the ~iphone and ~ipad identifiers as well.

The following list summarizes the differences between FromBundle and FromFile:

  • FromFile is asynchronous; whereas FromBundle is synchronous.
  • FromFile lazy-loads images.
  • FromFile can load images from an external location; whereas FromBundle can only load images that you include with the app at compile time.
  • FromFile provides no built-in caching; whereas FromBundle automatically caches an image after it is loaded.

Guidance on Using FromBundle vs. FromFile

Generally, the developer should use UIImage.FromFile when loading several images at one time, since it lazy-loads images asynchronously. Use UIImage.FromBundle only when loading the same image repeatedly.

Important Image Considerations

There are a few more points the developer should be aware of regarding images and iOS:

  • By default macOS (formerly known as OS X) uses a case-insensitive file system, which means that the iOS Simulator is also case-insensitive. An iOS device however, uses a case-sensitive file system. So code that runs on the simulator may fail to run correctly on device.
  • The developer cannot name a custom folder Resources, as it is reserved in iOS and the app will crash.
  • Set the build action to BundleResource for an image to be included in the application bundle. Generally, Visual Studio for Mac will set this automatically, but if there is 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.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.