In this post I will explain the different methods you can use to set the rollover icon that your BlackBerry application will display on the device’s Home Screen.
Accompanying sample code: BB_Rollover_Icon_Sample
First, get the right icon size and resolution for your device and theme
You have probably observed that the size of the application’s icon is not the same across device models and themes. This is a consequence of the different screen sizes and evolving graphic capabilities of the smartphones.
The following table lists the different device models and common icon sizes (An up-to-date version of this information can be obtained from the BlackBerry developers Developers Knowledge Base).
|BlackBerry® 6200 Series and BlackBerry® 6500 Series||28 x 28|
|BlackBerry® 7100 Series and BlackBerry® Pearl™ 8100 Series||Icon theme: 60 x 55|
|Today and Zen theme: 48 x 36|
|BlackBerry® 7200 Series and BlackBerry® 7700 Series||32 x 32|
|BlackBerry® 7290 smartphone||36 x 36|
|BlackBerry® Curve™ 8300 Series, BlackBerry® 8700 Series, and BlackBerry® 8800 Series||Icon theme: 53 x 48|
|Zen theme: 48 X 36|
|BlackBerry® Bold™ 9000 smartphone||Precision theme: 80 X 80|
If you intend to use the same icon on multiple BlackBerry smartphone models, you need to understand how this icon will be displayed. These are the scenarios you will encounter.
- On smartphones running BlackBerry Device Software prior to version 4.2, icon images that are larger than the maximum dimensions are cropped.
- On smartphones running BlackBerry Device Software version 4.2 to 4.5, if you use an icon with dimensions larger than those displayed on the smartphone, the icon will be scaled down to the device’s maximum icon size. If scaling occurs on an image that is not square and the result is an image that is square (or vice versa), the image may appear distorted.
- On smartphones running BlackBerry Device Software version 4.5 or earlier, if you use an icon of the smallest dimensions, it will not be scaled up on the smartphone with a higher resolution. The actual image size will be the same and the remainder of the icon area will be transparent, so the icon will appear smaller than the standard icons.
- On devices with Device Software 4.6, icons are scaled in the application grid menu to match the icons of the current theme. If your icon is larger than the current theme icon, the icon is scaled down to match. If it is just marginally smaller, it will be left un-scaled. If it is 25% (or more) smaller, it will be scaled up to match the current theme icon.
Specifying rollover icons in versions of the BlackBerry JDE prior to 4.7
The ability to add a rollover icon to an application was introduced in the BlackBerry API 4.1 set through the function HomeScreen.setRolloverIcon(…). This function sets the icon to use when the application icon is in focus.
Since you need the icon in place before the device user scrolls to your application, the function must be called at startup time. You can achieve this by defining an alternate entry point to the application. This entry point will run on startup and will produce the call to HomeScreen.setRolloverIcon(…).
In order to allow the application to identify when it was launched by the user from the ribbon and when it was started from the alternate entry point, you will configure the alternate entry to pass in an argument to the main() method. If main() encounters this argument, it will proceed to set the rollover icon and exit the application afterwards. In the absence of the argument, the assumption is that the user launched the application from the ribbon and the application should start normally.
The main() method would look like this
Now, there’s an issue in BlackBerry Device Software 4.1 where the HomeScreen.setRolloverIcon(…) method can throw an IllegalArgumentException. This issue has been resolved in BlackBerry Device Software 4.2. You can work around this issue by allowing the application to finish its startup before setting the rollover icon. In code, it would look like this
Specifying rollover icons in the BlackBerry JDE 4.7
As opposed to previous versions, the BlackBerry JDE 4.7 allows you to specify a rollover icon via the project’s properties. These are the steps you need to follow.
- In BlackBerry JDE, right-click the project.
- Select Properties.
- Select the Resources tab.
- Add the non rollover/unfocused application icon in the Icon Files field and add the rollover/focused icon in the Focus Icon Files field.
Setting rollover icons in the BlackBerry JDE Plug-in for Eclipse™
While this option is always present in the BlackBerry® JDE Plug-in for Eclipse™ it will only take effect when the application is built using the BlackBerry JDE Component Package 4.7.0 or later.
- In the Eclipse™ Package Explorer, right-click the project.
- Select Properties.
- Select BlackBerry Project Properties.
- Select the Resources tab.
- Add the non-rollover/unfocused application icon in the Icon Files field and add the rollover/focused icon in the Focus Icon Files field.