How To - Define a rollover icon for an application

How To - Define a rollover icon for an application
Last Updated: 14 November 2008
Article Number: DB-00467
Summary

This article applies to the following:

* BlackBerry® smartphones based on Java® technology
* BlackBerry® Device Software 4.1 and later
* BlackBerry® Java® Development Environment (BlackBerry JDE) 4.1 and later

Description
BlackBerry JDE4.7 and later

BlackBerry JDE 4.7 and BlackBerry JDE Component Package simplify the creation of a rollover icon. Rollover icons can now be specified in a project's properties.

Specifying a rollover icon in BlackBerry JDE 4.7

Complete the following steps:

1. In BlackBerry JDE, right-click the project.
2. Select Properties.
3. Select the Resources tab.
4. Add the non rollover/unfocused application icon in the Icon Files field and add the rollover/focused icon in the Focus Icon Files field.

Specifying a rollover icon in BlackBerry JDE Plug-in for Eclipse

Note: 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.

Complete the following:

1. In the Eclipse™ Package Explorer, right-click the project.
2. Select Properties.
3. Select BlackBerry Project Properties.
4. Select the Resources tab.
5. Add the non-rollover/unfocused application icon in the Icon Files field and add the rollover/focused icon in the Focus Icon Files field.

Before BlackBerry JDE 4.7

A new application programming interface (API), introduced in the BlackBerry API 4.1 set, grants the ability to add a rollover icon to an application. To leverage this new API correctly, the application must run on startup so the call is executed, and can thus take effect before the BlackBerry smartphone user scrolls to the application. The application itself should not run on startup, but an alternate entry point to the application should be defined to do so. The main entry point should be configured to pass in an argument to the main() method so that the application can identify a startup launch from a BlackBerry smartphone user launching the application from the ribbon.

The rollover icon application’s main() method will now resemble the following:

public static void main(String[] args)
{
if ( args != null && args.length > 0 && args[0].equals("gui") ){
//main entry point
Test theApp = new Test();
theApp.enterEventDispatcher();
} else {
//alternate entry point
Bitmap icon = Bitmap.getBitmapResource("2.png");
HomeScreen.setRolloverIcon(icon);
}
}

Due to an issue in BlackBerry Device Software 4.1, the HomeScreen.setRolloverIcon(Bitmap image)method can throw an IllegalArgumentException. This issue has been resolved in BlackBerry Device Software 4.2. The following code sample shows how to work around this issue:

public class HomeScreenIcon extends UiApplication
{
public static void main(String[] args)
{
//Check for the argument defined in the project properties.
if (args != null && args.length > 0 && args[0].equals("gui"))
{
HomeScreenIcon theApp = new HomeScreenIcon(false);
theApp.enterEventDispatcher();
}
else
{
HomeScreenIcon theApp = new HomeScreenIcon(true);
theApp.enterEventDispatcher();
}
}
public HomeScreenIcon(boolean autoStart)
{
if (autoStart)
{
//The application started using the auto start entry point.
//Setup the rollover icons.
final Bitmap regIcon = Bitmap.getBitmapResource("1.png");
final Bitmap icon = Bitmap.getBitmapResource("2.png");

invokeLater(new Runnable()
{
public void run()
{
ApplicationManager myApp =
ApplicationManager.getApplicationManager();
boolean keepGoing = true;

while (keepGoing)
{
//Check if the BlackBerry has completed its
startup process.
if (myApp.inStartup())
{
//The BlackBerry is still starting up,
sleep for 1 second.
try
{
Thread.sleep(1000);
}
catch (Exception ex)
{
//Couldn't sleep, handle exception.
}
}
else
{
//The BlackBerry has finished its
startup process.
//Set the rollover icons.
HomeScreen.updateIcon(regIcon, 0);
HomeScreen.setRolloverIcon(icon, 0);
keepGoing = false;
}
}
//Exit the application.
System.exit(0);
}
});

}
else
{
//The application was started by the user.
//Start the application and display a GUI.
MainScreen ms = new MainScreen();
ms.setTitle(new LabelField("Hello there."));
pushScreen(ms);
}
}
}

Note: After running on startup to define the rollover icon, the application exits so that it does not run needlessly in the background.
Additional Information

For more information, see DB-00008 regarding alternate entry point applications and DB-00126 on defining an application icon.