Getting Started

Invoking Native Code

Include in Your Project



Real-World Examples

Using Native UI







Styling Native Controls

Working with Images

Native UI Layout



Writing Platform-Specific Code


UI Framework Reference

Layout Panels



Platform Helpers



Troubleshooting Errors

Working with Images

Ace provides a cross-platform Image class that be used to place an image (PNG, JPG, and so on) inside your user interface. This is like using ImageView on Android and UIImageView on iOS. (In fact, that is exactly what happens behind the scenes.)

You can set Image’s Source to an image URL, such as www/images/icon.png.

Image has a few extra smarts, however, that are convenient for tweaking per-platform behavior without having to write per-platform code.

Consolidating Multiple Images Into One URL

There are three features you can take advantage of when specifying an image source:

  • Customizing per-platform
  • Customizing for “on” and “off” states
  • Customizing for device resolutions or screen density

Customizing Per-Platform

If your URL contains the string {platform}, it will be replaced with the platform name at runtime. So icon-{platform}.png becomes icon-ios.png on iOS and icon-android.png on Android. This enables you to supply images that better match the styling of each platform.

Customizing For “On” and “Off” States

In addition, sometimes you might want to supply multiple images representing different states. This currently applies to AppBarButtons inside a TabBar. iOS supports a separate selectedImage in addition to the main image. To make this seamless, Ace will look for two separate images, one with an ios-on platform identifier and another with an ios-off identifier.

Customizing For Device Resolution or Screen Density

On iOS, you can supply multiple sizes of an image and add suffixes to your image files like @2x, @3x, and @4x to tell the operating system which image to use. This happens automatically, so you leave the suffix out of your Image source.


Therefore, you can specify a single icon:

<AppBarButton Icon="www/img/tabs/calendar-{platform}.png" 
              ace:On.Click="onTabClick(this, 0)" />

And supply many separate images:

  • www/img/tabs/calendar-android.png: Used in all cases on Android
  • www/img/tabs/calendar-ios-on@2x.png: Used as the selected image on iOS (2x scale)
  • www/img/tabs/calendar-ios-off@2x.png: Used as the default image on iOS (2x scale)
  • www/img/tabs/calendar-ios-on@3x.png: Used as the selected image on iOS (3x scale)
  • www/img/tabs/calendar-ios-off@3x.png: Used as the default image on iOS (3x scale)
  • www/img/tabs/calendar-ios-on@4x.png: Used as the selected image on iOS (4x scale)
  • www/img/tabs/calendar-ios-off@4x.png: Used as the default image on iOS (4x scale)

You can see this in action in the source code for the PhoneGapDay app.

calendar-ios-on@2x.png calendar-ios-off@2x.png
calendar-ios-on@3x.png calendar-ios-off@3x.png
calendar-ios-on@4x.png calendar-ios-off@4x.png