CategoryBar

Device compatibility

CategoryBar is supported on Series 40 full touch devices with Java Runtime 2.0.0 for Series 40 or newer.

Creating a CategoryBar

To create a new CategoryBar:

1. Check the most suitable dimensions for an icon and, if you are using one, a background image using the static CategoryBar.getBestImageHeight and CategoryBar.getBestImageWidth methods. These methods return the most suitable dimensions for the current device. Use the returned values to optimize the use of icons and background image in the new CategoryBar.

   Note: Setting a background image for a CategoryBar is only available to a MIDlet running in the manufacturer or operator domain.

   The following code snippet retrieves the most suitable dimensions for a CategoryBar icon.

   int bestWidth;
   int bestHeight;
   
   try {
       bestWidth = CategoryBar.getBestImageWidth(CategoryBar.IMAGE_TYPE_ICON);
       bestHeight = CategoryBar.getBestImageHeight(CategoryBar.IMAGE_TYPE_ICON);
   } catch (IllegalArgumentException iae) {
       // Handle IllegalArgumentException from CategoryBar.getBestImageWidth() or
       // CategoryBar.getBestImageHeight()
   }

2. Check the maximum number of elements allowed in a CategoryBar using the static CategoryBar.getMaxElements method. This method returns the maximum number of elements that can be displayed in a CategoryBar on the current device. Make sure your MIDlet can dynamically adjust the number of elements in the new CategoryBar to comply with the maximum value if necessary. If you try to add more elements than the maximum number, the excess elements are not displayed. (No Exception is thrown in this case.)

   The following code snippet retrieves the maximum number of CategoryBar elements allowed on the device.

   int maxElements = CategoryBar.getMaxElements();

3. Create a new CategoryBar object. Use the constructor parameters to define the icons and labels for the elements with which to populate the CategoryBar. You can either define the icons and labels separately or use an IconCommand array to provide the icon and label data. For more information about the IconCommand class, see section IconCommand. Defining separate icons for selected elements is optional.

   The following code snippet creates a new CategoryBar with three elements using separately defined icons and labels.

   CategoryBar categoryBar;
   
   try {
       // Define the icons and labels for the CategoryBar elements
       Image[] unselectedIcons = {
                                   Image.createImage("Element_1_Unselected.png"),
                                   Image.createImage("Element_2_Unselected.png"),
                                   Image.createImage("Element_3_Unselected.png")
                                 };
       Image[] selectedIcons = {
                                 Image.createImage("Element_1_Selected.png"),
                                 Image.createImage("Element_2_Selected.png"),
                                 Image.createImage("Element_3_Selected.png")
                               };
       String[] labels = { "Label 1", "Label 2", "Label 3" };
   
       // Create the CategoryBar
       categoryBar = new CategoryBar(unselectedIcons, selectedIcons, labels);
   } catch (NullPointerException npe) {
       // Handle NullPointerException from Image.createImage()
   } catch (IOException ioe) {
       // Handle IOException from Image.createImage()
   } catch (IllegalArgumentException iae) {
       // Handle IllegalArgumentException from CategoryBar()
   }

4. Configure the CategoryBar using the appropriate CategoryBar methods. You can set the following additional properties not set by the constructor:

   • Background color (only available in the manufacturer and operator domains)

     Tip: To remove the background color and thus restore the default background image, use the CategoryBar.DEFAULT_BACKGROUND constant as the method parameter.

   • Background image (only available in the manufacturer and operator domains)

   • Highlight color for selected elements

     Tip: To set the default highlight color, use the CategoryBar.DEFAULT_HIGHLIGHT_COLOUR constant as the method parameter.

   • Index of the selected element

   • Whether to apply transition effects when showing or hiding the CategoryBar

   You can set the above properties at any point during the lifetime of the CategoryBar, not just when you first create it.

   The following code snippet sets a background image for the new CategoryBar and sets the second element (at index 1) as the selected element.

   try {
       categoryBar.setBackgroundImage(Image.createImage("Background.png"));
       categoryBar.setSelectedIndex(1);
   } catch (NullPointerException npe) {
       // Handle NullPointerException from Image.createImage()
   } catch (IOException ioe) {
       // Handle IOException from Image.createImage()
   } catch (SecurityException se) {
       // Handle SecurityException from categoryBar.setBackgroundImage()
   } catch (IllegalArgumentException iae) {
       /// Handle IllegalArgumentException from categoryBar.setSelectedIndex()
   }

5. Register an ElementListener for the CategoryBar. The ElementListener is notified whenever an element is selected. Only one ElementListener can be associated with a given CategoryBar at a time.

   The following code snippet registers the current class as an ElementListener for the new CategoryBar.

   categoryBar.setElementListener(this);

6. Implement the ElementListener registered for the CategoryBar. The ElementListener.notifyElementSelected method is called every time the user selects an element from the CategoryBar. Use this method to handle the selection action for each element, for example a switch to the corresponding MIDlet view.

   The following code snippet implements a notifyElementSelected method that triggers the correct action for each element in the new CategoryBar. (The implementation of the switchToView and toggleVisibility methods is not part of this example.)

   public void notifyElementSelected(CategoryBar bar, int selectedIndex) {
   
       // Switch to the MIDlet view corresponding to the selected element
       // or hide the CategoryBar if the Back button was selected
       switch (selectedIndex) {
           case 0: switchToView(bar, 0);
           case 1: switchToView(bar, 1);
           case 2: switchToView(bar, 2);
           case ElementListener.BACK: toggleVisibility(bar, false);
       }
   
   }

7. After you have created and configured the CategoryBar and set up an ElementListener for it, show the CategoryBar in the MIDlet UI so that the user can access it. Use the setVisibility method as follows:

   categoryBar.setVisibility(true);

You have now created the CategoryBar.

Retrieving the properties of a CategoryBar

You can retrieve the following properties from an existing CategoryBar:

• Default bounding box, that is, the smallest inclusive rectangle that encompasses all of the pixels of the visible CategoryBar

• Index of the selected element

• Whether the CategoryBar is currently visible

Setting the properties of a CategoryBar element

You can set the following properties for an element of an existing CategoryBar:

• Unselected icon

• Selected icon

• Label

Typically, you set the above properties before displaying the CategoryBar for the first time, but you can also set the properties at any time.

You can either define the icons and labels separately or use an IconCommand object to provide the icon and label data.

Hiding and showing a CategoryBar

If you need to hide the CategoryBar at some point in the MIDlet UI flow, call categoryBar.setVisibility(false). This removes the CategoryBar from the MIDlet UI, making it inaccessible to the user. When you want to show it again, call categoryBar.setVisibility(true) and the CategoryBar is again displayed in the MIDlet UI.