icon element

Syntax

<icon src="string" />

Description

The <icon> element specifies a custom icon for a BlackBerry WebWorks app. The icon that you specify in the src attribute is the app's icon that appears on the Home screen of the BlackBerry device. The icon must meet the requirements for custom or default icons.

This element is optional.

Parent elements

<widget>

Child elements

None

Occurrences

Zero or more

Attributes

You can use the following attributes in this element:

Attribute Description
src

Specifies the path for an image file in the app archive.

This attribute is required.

BlackBerry 10 icons

Your icon image should be 24-bit PNG format with an alpha channel. For information about designing icons for BlackBerry 10, see the UI Guidelines.

If you do not specify an icon for your BlackBerry 10 app, the BlackBerry WebWorks Packager uses the default app icon.

Targeting multiple screen sizes

To target multiple screen sizes of BlackBerry 10, you can specify image files with different resolutions. At runtime, the BlackBerry 10 OS selects the appropriate image to display.

<icon src="icon-86.png" />
<icon src="icon-150.png" />

Using localized icons

You can also use localized icons for BlackBerry 10 apps. To use localized icons, the image files must be :

  • Named the same as the non-localized image file name that you specified in the <icon> element.
  • Stored in the appropriate locale subfolder that corresponds with the localized language.

When you use localized images, the files must be stored in individual locale folders (for example, "/locales/en-US", "/locales/fr") which are direct descendants of the root locales folder. The locales folder must be located in the root of your app folder so that the BlackBerry WebWorks Packager can build your app. The locale strings specified in the folder name must use the naming conventions that are specified in the Internet Engineering Task Force (IEFT) Best Current Practice (BCP) 47 specification. For example, you can use the Language-Region naming convention as in the following examples: en-US (United States English), de-DE (German for Germany), and fr-CA (Canadian French).

The file names for the localized images must be named exactly as the non-localized image files that you specified in the <icon> element. You can store the non-localized images in subfolders but the locale folder must use the same subfolder structure for the localized images. When the BlackBerry 10 OS is set to one of the locales (for example, German or French) and localized images are present for that locale, the BlackBerry 10 OS selects the images from the respective locale subfolder. If no localized images are available for the specified locale, the BlackBerry 10 OS selects the non-localized icon image located in the root.

Example: Using localized icons

In this example, if the French locale is set on the device, even if the optimum icon resolution is 150x150, the BlackBerry 10 OS uses the locales/fr/icon-86.png file because it's the only icon image available for this locale.

Using <icon> elements in the config.xml file:

<icon src="icon-86.png" />
<icon src="icon-150.png" />

File and folder structure:

locales/de/icon-86.png
locales/de/icon-150.png
locales/fr/icon-86.png
icon-86.png
icon-150.png

Last modified: 2014-03-10



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus