<icon>

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 used to identify your app on the Home screen of the BlackBerry device.

The icon must meet the requirements for custom or default 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.

This element is optional. If you do not specify an icon for your app, the BlackBerry 10 WebWorks SDK uses the default application icon.

Occurrences:

Zero or more.

Parent elements:

<platform>

Although it is permitted to include the <icon> element as a child of <widget>, for future cross-platform compatibility, you should add all <icon> elements as children of a <platform> element.

Child elements:

None.

Content:

None.

Attributes:

You can define the following attributes for this element:

Attribute Description
src

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

This attribute is required.

rim:hover

A Boolean value that specifies whether the icon is used as a hover icon. The first hover icon in the configuration document is used as the hover icon for the application.

By default, if you do not specify a value for the rim:hover attribute, the value is set to false.

This attribute is optional.

Examples:

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. For example:

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

Using localized icons

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

  • Named the same as the nonlocalized 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 application folder so that the BlackBerry WebWorks Packager can build your application. 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 nonlocalized image files that you specified in the icon element. You can store the nonlocalized 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 nonlocalized icon image located in the root.

For example, assume that our WebWorks project includes the following files:

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

In our config.xml file, we include the following entries:

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

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.

Last modified: 2015-04-16



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

comments powered by Disqus