CategoryBar

Device compatibility

CategoryBar is supported on Nokia Asha software platform devices with Java Runtime for Nokia Asha software platform (1.0) and 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 optimise the use of icons and background image in the new CategoryBar.

   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. 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 (in Series 40 full touch)

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.

Differences between Series 40 full touch and Nokia Asha software platform 1.0

On Nokia Asha software platform devices, it is possible to define the behavior of the CategoryBar’s elements when they receive touch events. When the user taps a CategoryBar element on Series 40 full touch, the element remains selected, meaning that any consecutive taps on the same element, cannot be caught, because the notifyElementSelected call back method is executed only during the transition from the unselected to the selected state. The same behavior is implemented by default on Nokia Asha software platform devices, however it is possible to force an element to remain unselected after being tapped, by defining the CategoryBar’s mode to ELEMENT_MODE_RELEASE_SELECTED. When this happens, the element is briefly highlighted on touch down and then returns back to the unselected mode, on touch release. These are the two possible modes for the CategoryBar supported on Nokia Asha software platform 1.0:

• ELEMENT_MODE_RELEASE_SELECTED

  CategoryBar mode indicating that element should be released after element is selected.

• ELEMENT_MODE_STAY_SELECTED

  CategoryBar mode indicating that element should stay selected after element is selected.

The methods getMode() and setMode() can be used to retrieve and set the behaviour mode of the CategoryBar respectively. This is how the ELEMENT_MODE_RELEASED_SELECTED mode can be enabled:

categoryBar = new CategoryBar(unselectedIcons, selectedIcons, labels, CategoryBar.ELEMENT_MODE_RELEASE_SELECTED);

When the CategoryBar is set to the ELEMENT_MODE_RELEASE_SELECTED mode, the notifyElementSelected call back method is always executed each time the user taps the same or any of the CategoryBar’s elements.

While on Nokia Asha software platform devices, there can only be 4 elements placed in the CategoryBar, on Series 40 full touch devices, there can be more than 4 (typically up to 15). When the CategoryBar on Series 40 full touch devices receives more than 4 elements, the fourth element is replaced with the three-dot expandable element, that nests all the elements that cannot be shown in the CategoryBar’s main view as shown in the Figure below:

Figure: An expandable CateogyrBar with more than 4 elements on Series 40 full touch devices

The implementation automatically handles the expansion or retraction of the CategoryBar in this case, i.e. there is no additional code required by the developer other than the definition of the elements and their addition to the CategoryBar.

More information

For more information about CategoryBar see Series 40 Full Touch Design Guidelines for CategoryBar.