How to Set a Rollover Icon for Your BlackBerry Application

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).

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

public static void main(String[] args)

{

   if ( args != null && args.length > 0 && args[0].equals("alternate") ){

      //  Alternate entry point 

      Bitmap icon = Bitmap.getBitmapResource("rollover_icon.png");

      HomeScreen.setRolloverIcon(icon);

   } else {

      //  Main entry point 

      Test theApp = new Test();

      theApp.enterEventDispatcher();

   }

}

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

public class RolloverIconApp extends UiApplication

{

    public RolloverIconApp(boolean autoStart)

    {

        if (autoStart)

        {

        // If the application started using the auto start 

        // entry point, we setup the our icons.

        final Bitmap regularIcon = Bitmap.getBitmapResource("unfocused_icon.png");

        final Bitmap rolloverIcon = Bitmap.getBitmapResource("rollover_icon.png");

        invokeLater(new Runnable()

        {

            public void run()

            {

                ApplicationManager myApp =

                  ApplicationManager.getApplicationManager();

                boolean inStartup = true;

                while (inStartup)

                {

                    if (myApp.inStartup())

                    {

                        // Wait for the device to finish the startup process.

                        try

                        {

                            Thread.sleep(1000);

                        }

                        catch (Exception ex)

                        {

                          // TODO: handle exception.

                        }

                    }

                    else

                    {

                        HomeScreen.updateIcon(regularIcon, 0);

                        HomeScreen.setRolloverIcon(rolloverIcon, 0);

                        inStartup = false;

                    }

                 }

                 // We're done setting up the icons. Exit the app.

                 System.exit(0);

            }

        });

    }

    else

    {

         // The application was started by the user, display the UI.

         MainScreen ms = new MainScreen();

         ms.setTitle("Did you see the rollover icon?");

         pushScreen(ms);

    }

  }

    public static void main(String[] args)

    {

        RolloverIconApp theApp;

        //Check for the argument defined in the project properties.

        if (args != null && args.length > 0 && args[0].equals("autostart"))

        {

            theApp = new RolloverIconApp(true);

        }

         else

        {

            theApp = new RolloverIconApp(false);

        }

        theApp.enterEventDispatcher();

    }

}

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.

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.

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.

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.

Conclusion

This pretty much covers the information available on the rollover icons topic as of the date of this post. Remember to check the sample project: BB_Rollover_Icon_Sample