com.nokia.mid.ui
Class CategoryBar

java.lang.Object
  com.nokia.mid.ui.CategoryBar

public class CategoryBar
extends java.lang.Object

CategoryBar is a UI component designed for use in switching between application views.

A CategoryBar is visualised as a set of user-selectable elements. Each element may represent a view within the current application, although the application is free to use the elements for whatever purpose it desires. Typically though, a CategoryBar is designed to allow the user to switch from one view (or category) to another within the same application.

MIDlets are responsible for creating and populating the CategoryBar with elements, as well as controlling the CategoryBar and responding to events when elements are selected. The order in which elements are displayed is guaranteed to match the order in which the elements given by the MIDlet are indexed (i.e. the element with index zero will always be displayed first).

Every element is visually represented by an icon image and, depending on device, by a text label. In ELEMENT_MODE_STAY_SELECTED -mode there is always one element with a selected appearance, indicating to the user which application or view is active. In ELEMENT_MODE_RELEASE_SELECTED -mode elements are stateless and selected appearance is only shown during element selection. MIDlets may provide an additional icon image per element to allow the visual appearance of a selected element to be defined. If the MIDlet does not provide the additional image then the implementation will provide a default visual appearance for the selected element.

In order to detect when the user has selected a CategoryBar element, MIDlets must register a ElementListener. MIDlets are entirely responsible for any action triggered when the user selects a CategoryBar element.

Only one CategoryBar may be active at any time. The active CategoryBar is defined as the CategoryBar whose visible state was last set to true via the method setVisibility(boolean). Setting a CategoryBar visible therefore causes it to become the active CategoryBar, replacing and hiding any existing active CategoryBar.

Field Summary

static int	DEFAULT_BACKGROUND Default image for background
static int	DEFAULT_HIGHLIGHT_COLOUR Default colour for highlight
static int	ELEMENT_MODE_RELEASE_SELECTED CategoryBar mode indicating that element should be released after element is selected
static int	ELEMENT_MODE_STAY_SELECTED CategoryBar mode indicating that element should stay selected after element is selected
static int	IMAGE_TYPE_BACKGROUND Image type representing background images.
static int	IMAGE_TYPE_ICON Image type representing icon images.

Constructor Summary

CategoryBar(IconCommand[] elements, boolean useLongLabel)
Creates a new CategoryBar from a given IconCommand array.

CategoryBar(IconCommand[] elements, boolean useLongLabel, int mode)
Creates a new CategoryBar from a given IconCommand array.

CategoryBar(javax.microedition.lcdui.Image[] unselectedIcons, javax.microedition.lcdui.Image[] selectedIcons, java.lang.String[] labels)
Creates a new CategoryBar.

CategoryBar(javax.microedition.lcdui.Image[] unselectedIcons, javax.microedition.lcdui.Image[] selectedIcons, java.lang.String[] labels, int mode)
Creates a new CategoryBar.

Method Summary

static int	getBestImageHeight(int imageType) Gets the most suitable height for the given image type.
static int	getBestImageWidth(int imageType) Gets the most suitable width for the given image type.
static int[]	getDefaultBoundingBox() Gets the getDefaultBoundingBox.
static int	getMaxElements() Gets the maximum number of elements that can be displayed on a CategoryBar.
int	getMode() Gets the behaviour mode of the CategoryBar.
int	getSelectedIndex() Gets the index of the element that appears visually selected when the CategoryBar is displayed.
boolean	getVisibility() Gets the CategoryBar's visible state.
void	setBackgroundColour(int colour) Sets category bar background colour.
void	setBackgroundImage(javax.microedition.lcdui.Image image) Sets the CategoryBar's background image. Only applications signed to the manufacturer and operator domain are permitted to use this method.
void	setElementListener(ElementListener listener) Associates an ElementListener with the CategoryBar.
void	setElementProperties(int index, IconCommand element, boolean useLongLabel) Sets the icon and label properties of the specified element to match those of a given IconCommand, replacing the existing values.
void	setElementProperties(int index, javax.microedition.lcdui.Image unselectedIcon, javax.microedition.lcdui.Image selectedIcon, java.lang.String label) Sets the icon and label properties of the specified element, replacing the existing values.
void	setHighlightColour(int colour) Sets category bar highlight colour.
void	setMode(int mode) Sets the behaviour mode of the CategoryBar.
void	setSelectedIndex(int index) Sets the CategoryBar's selected element, which is element zero by default.
void	setTransitionSupport(boolean transitionSupport) Sets whether transition effects are enabled on the CategoryBar, which otherwise follow the default device settings.
void	setVisibility(boolean visibility) Sets the CategoryBar's visibility, which is hidden by default.
static void	suppressSizeChanged(boolean suppressSizeChange) Suppresses sizeChanged(int,int) events when category bar visibility changes.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_BACKGROUND

public static final int DEFAULT_BACKGROUND

Default image for background

See Also:

Constant Field Values

DEFAULT_HIGHLIGHT_COLOUR

public static final int DEFAULT_HIGHLIGHT_COLOUR

Default colour for highlight

See Also:

Constant Field Values

IMAGE_TYPE_BACKGROUND

public static final int IMAGE_TYPE_BACKGROUND

Image type representing background images.

See Also:

Constant Field Values

IMAGE_TYPE_ICON

public static final int IMAGE_TYPE_ICON

Image type representing icon images.

See Also:

Constant Field Values

ELEMENT_MODE_STAY_SELECTED

public static final int ELEMENT_MODE_STAY_SELECTED

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

See Also:

Constant Field Values

ELEMENT_MODE_RELEASE_SELECTED

public static final int ELEMENT_MODE_RELEASE_SELECTED

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

See Also:

Constant Field Values

Constructor Detail

CategoryBar

public CategoryBar(IconCommand[] elements,
                   boolean useLongLabel,
                   int mode)

Creates a new CategoryBar from a given IconCommand array.

The IconCommand array parameter given by the MIDlet is used to populate the CategoryBar with elements. Only the label and icon images of each IconCommand are used. If the parameter useLongLabel is true then each IconCommand's longLabel is used, otherwise its shortLabel is used. Note that CategoryBar takes a snapshot of the data and therefore any subsequent changes to the given IconCommands will not be reflected to the user.

The parameters given by the MIDlet are sufficient only to define a legal CategoryBar instance. To further customise the CategoryBar (e.g. to set the CategoryBar's background image), MIDlets must call appropriate additional methods on the CategoryBar instance returned.

Every element is required to have an icon as well as a label. IconCommands that contain MIDlet-defined icon images must contain an unselected version of the icon. The selected version is optional however, and if it is not provided then the platform will provide its own highlighting when an element is selected. CategoryBar does not support IconCommand.ICON_BACK and IconCommand.ICON_OPTIONS icons.

The CategoryBar elements can have either stateful or stateless behaviour. Difference between these modes is that in stateful (ie. ELEMENT_MODE_STAY_SELECTED) mode the CategoryBar element stays active when selected. In stateless mode ( ELEMENT_MODE_RELEASE_SELECTED), the active state is released as soon as element selection has been performed.

The implementation may place a limit (N) on the maximum number of elements on a CategoryBar and therefore only the first N elements will be displayed, with the remainder ignored. The method getMaxElements() may be used to query the limit.

Note that the implementation will take a copy of any mutable image data provided.

Parameters:

elements - an array of IconCommands whose labels and icons will be used to populate the CategoryBar.

useLongLabel - flag indicating whether the caller wants the long label of each IconCommand to be used as the label for each element in the CategoryBar. If true, the long label will be used if it exists, otherwise the short label will be used.

mode - ELEMENT_MODE_STAY_SELECTED or ELEMENT_MODE_RELEASE_SELECTED setting indicating whether CategoryBar elements should stay selected or be released after element has been selected

Throws:

java.lang.IllegalArgumentException - if element is null, zero length or contains null elements.

java.lang.IllegalArgumentException - if elements contains elements with iconId IconCommand.ICON_BACK or IconCommand.ICON_OPTIONS

java.lang.IllegalArgumentException - if the mode is neither ELEMENT_MODE_STAY_SELECTED nor ELEMENT_MODE_RELEASE_SELECTED.

CategoryBar

public CategoryBar(IconCommand[] elements,
                   boolean useLongLabel)

Creates a new CategoryBar from a given IconCommand array.

The IconCommand array parameter given by the MIDlet is used to populate the CategoryBar with elements. Only the label and icon images of each IconCommand are used. If the parameter useLongLabel is true then each IconCommand's longLabel is used, otherwise its shortLabel is used. Note that CategoryBar takes a snapshot of the data and therefore any subsequent changes to the given IconCommands will not be reflected to the user.

The parameters given by the MIDlet are sufficient only to define a legal CategoryBar instance. To further customise the CategoryBar (e.g. to set the CategoryBar's background image), MIDlets must call appropriate additional methods on the CategoryBar instance returned.

Every element is required to have an icon as well as a label. IconCommands that contain MIDlet-defined icon images must contain an unselected version of the icon. The selected version is optional however, and if it is not provided then the platform will provide its own highlighting when an element is selected. CategoryBar does not support IconCommand.ICON_BACK and IconCommand.ICON_OPTIONS icons.

The implementation may place a limit (N) on the maximum number of elements on a CategoryBar and therefore only the first N elements will be displayed, with the remainder ignored. The method getMaxElements() may be used to query the limit.

Note that the implementation will take a copy of any mutable image data provided.

Parameters:

elements - an array of IconCommands whose labels and icons will be used to populate the CategoryBar.

useLongLabel - flag indicating whether the caller wants the long label of each IconCommand to be used as the label for each element in the CategoryBar. If true, the long label will be used if it exists, otherwise the short label will be used.

Throws:

java.lang.IllegalArgumentException - if elements is null, zero length or contains null elements.

java.lang.IllegalArgumentException - if elements contains elements with iconId IconCommand.ICON_BACK or IconCommand.ICON_OPTIONS

CategoryBar

public CategoryBar(javax.microedition.lcdui.Image[] unselectedIcons,
                   javax.microedition.lcdui.Image[] selectedIcons,
                   java.lang.String[] labels,
                   int mode)

Creates a new CategoryBar.

The parameters given by the MIDlet are used to populate the CategoryBar with elements. These parameters are sufficient only to define a legal CategoryBar instance. To further customise the CategoryBar (e.g. to set the CategoryBar's background image), MIDlets must call appropriate additional methods on the CategoryBar instance returned.

Every element is required to have an unselected version of its icon as well as a label. The selected version of an icon is optional and therefore it is legal to set the selectedIcons parameter or its elements to null. In such cases, the platform will provide its own highlighting when an element is selected.

The implementation may place a limit (N) on the maximum number of elements on a CategoryBar and therefore only the first N elements will be displayed, with the remainder ignored. The method getMaxElements() may be used to query the limit.

The CategoryBar elements can have either stateful or stateless behaviour. Difference between these modes is that in stateful (ie. ELEMENT_MODE_STAY_SELECTED) mode the CategoryBar element stays active when selected. In stateless mode ( ELEMENT_MODE_RELEASE_SELECTED), the active state is released as soon as element selection has been performed.

Note that the implementation will take a copy of any mutable image data provided.

Parameters:

unselectedIcons - an array of Images - one per element - used to define the visual representation of the element when unselected.

selectedIcons - an array of Images - one per element - used to define the visual representation of the element when selected.

labels - an array of Strings - one per element - used to define the textual representation of the element.

mode - ELEMENT_MODE_STAY_SELECTED or ELEMENT_MODE_RELEASE_SELECTED depending on desired CategoryBar element behavior.

Throws:

java.lang.IllegalArgumentException - if either unselectedIcons or labels is null, zero length or contains null elements.

java.lang.IllegalArgumentException - if the length of unselectedIcons does not equal that of labels.

java.lang.IllegalArgumentException - if selectedIcons is non-null and its length does not equal that of unselectedIcons.

java.lang.IllegalArgumentException - if the mode is neither ELEMENT_MODE_STAY_SELECTED nor ELEMENT_MODE_RELEASE_SELECTED.

CategoryBar

public CategoryBar(javax.microedition.lcdui.Image[] unselectedIcons,
                   javax.microedition.lcdui.Image[] selectedIcons,
                   java.lang.String[] labels)

Creates a new CategoryBar.

The parameters given by the MIDlet are used to populate the CategoryBar with elements. These parameters are sufficient only to define a legal CategoryBar instance. To further customise the CategoryBar (e.g. to set the CategoryBar's background image), MIDlets must call appropriate additional methods on the CategoryBar instance returned.

Every element is required to have an unselected version of its icon as well as a label. The selected version of an icon is optional and therefore it is legal to set the selectedIcons parameter or its elements to null. In such cases, the platform will provide its own highlighting when an element is selected.

The implementation may place a limit (N) on the maximum number of elements on a CategoryBar and therefore only the first N elements will be displayed, with the remainder ignored. The method getMaxElements() may be used to query the limit.

Note that the implementation will take a copy of any mutable image data provided.

Parameters:

unselectedIcons - an array of Images - one per element - used to define the visual representation of the element when unselected.

selectedIcons - an array of Images - one per element - used to define the visual representation of the element when selected.

labels - an array of Strings - one per element - used to define the textual representation of the element.

Throws:

java.lang.IllegalArgumentException - if either unselectedIcons or labels is null, zero length or contains null elements.

java.lang.IllegalArgumentException - if the length of unselectedIcons does not equal that of labels.

java.lang.IllegalArgumentException - if selectedIcons is non-null and its length does not equal that of unselectedIcons.

Method Detail

getBestImageWidth

public static int getBestImageWidth(int imageType)

Gets the most suitable width for the given image type.

Allows MIDlets to optimise their use of image data to the device in use.

Parameters:

imageType - type of image that the MIDlet is interested in.

Returns:

the optimal width of the specified image type, in pixels.

Throws:

java.lang.IllegalArgumentException - if the given image type is neither IMAGE_TYPE_BACKGROUND nor IMAGE_TYPE_ICON.

getBestImageHeight

public static int getBestImageHeight(int imageType)

Gets the most suitable height for the given image type.

Allows MIDlets to optimise their use of image data to the device in use.

Parameters:

imageType - type of image that the MIDlet is interested in.

Returns:

the optimal height of the specified image type, in pixels.

Throws:

java.lang.IllegalArgumentException - if the given image type is neither IMAGE_TYPE_BACKGROUND nor IMAGE_TYPE_ICON.

getMaxElements

public static int getMaxElements()

Gets the maximum number of elements that can be displayed on a CategoryBar.

Returns:

The maximum number of elements that can be displayed, excluding the predefined ElementListener.BACK element.

getDefaultBoundingBox

public static int[] getDefaultBoundingBox()

Gets the getDefaultBoundingBox.

Allows MIDlets to optimise their use of image data to the device in use.

Returns:

Boundry x,y,width, height.

getSelectedIndex

public int getSelectedIndex()

Gets the index of the element that appears visually selected when the CategoryBar is displayed.

Returns:

the index of the currently-selected element.

getMode

public int getMode()

Gets the behaviour mode of the CategoryBar.

Returns:

ELEMENT_MODE_STAY_SELECTED or ELEMENT_MODE_RELEASE_SELECTED depending on current CategoryBar element behavior.

getVisibility

public boolean getVisibility()

Gets the CategoryBar's visible state.

By default, an instance of CategoryBar is hidden.

Returns:

true if visible otherwise false.

setBackgroundImage

public void setBackgroundImage(javax.microedition.lcdui.Image image)

Sets the CategoryBar's background image.
Only applications signed to the manufacturer and operator domain are permitted to use this method.

By default, the CategoryBar has its own default background image. This method provides a way to replace it with a custom background image, or to restore the default background image if a custom background image has previously been set.

Note that the implementation will take a copy of any mutable image data provided.

Parameters:

image - the background image to be used, or null to restore the default background image.

Throws:

java.lang.SecurityException - if the MIDlet does not have permission to set the background image.

setElementListener

public void setElementListener(ElementListener listener)

Associates an ElementListener with the CategoryBar. The listener will subsequently be notified whenever a CategoryBar element is selected. Setting a listener replaces any existing listener (i.e. only one listener can be registered to each CategoryBar instance). To remove the currently active listener, a null parameter must be given.

Parameters:

listener - an instance of ElementListener, or null to remove the currently-active listener.

setElementProperties

public void setElementProperties(int index,
                                 javax.microedition.lcdui.Image unselectedIcon,
                                 javax.microedition.lcdui.Image selectedIcon,
                                 java.lang.String label)

Sets the icon and label properties of the specified element, replacing the existing values.

Note that the implementation will take a copy of any mutable image data provided.

Parameters:

index - the index of the element whose properties will be replaced.

unselectedIcon - an Image providing the visual representation of the element when unselected.

selectedIcon - an Image providing the visual representation of the element when selected. This parameter may be null if no selected icon is required.

label - a String defining the textual representation of the element.

Throws:

java.lang.IllegalArgumentException - if either unselectedIcon or label is null.

java.lang.IllegalArgumentException - if index is less than zero or greater than or equal to the number of elements in the CategoryBar.

setMode

public void setMode(int mode)

Sets the behaviour mode of the CategoryBar. Default mode is ELEMENT_MODE_STAY_SELECTED.

Parameters:

mode - ELEMENT_MODE_STAY_SELECTED or ELEMENT_MODE_RELEASE_SELECTED depending on desired CategoryBar element behavior.

Throws:

java.lang.IllegalArgumentException - if the mode is neither ELEMENT_MODE_STAY_SELECTED nor ELEMENT_MODE_RELEASE_SELECTED.

setElementProperties

public void setElementProperties(int index,
                                 IconCommand element,
                                 boolean useLongLabel)

Sets the icon and label properties of the specified element to match those of a given IconCommand, replacing the existing values.

Note that CategoryBar does not support IconCommand.ICON_BACK and IconCommand.ICON_OPTIONS icons.

Note that the implementation will take a copy of any mutable image data provided.

Parameters:

index - the index of the element whose properties will be replaced.

element - an IconCommand whose label and icon will be used in place of the element's existing values.

useLongLabel - flag indicating whether the caller wants the long label of the IconCommand to be used as the element's label. If true, the long label will be used if it exists, otherwise the short label will be used.

Throws:

java.lang.IllegalArgumentException - if element is null.

java.lang.IllegalArgumentException - if index is less than zero or greater than or equal to the number of elements in the CategoryBar.

java.lang.IllegalArgumentException - if element has an iconId IconCommand.ICON_BACK or IconCommand.ICON_OPTIONS

setSelectedIndex

public void setSelectedIndex(int index)

Sets the CategoryBar's selected element, which is element zero by default.

As a result of calling this method, the given element will be redrawn to highlight to the user that it is now selected. If the MIDlet has provided a selected version of the element's icon then it will be used for this purpose, otherwise an implementation-specific method of highlighting will be employed.

Parameters:

index - the index of the currently-selected element.

Throws:

java.lang.IllegalArgumentException - if index is less than zero or greater than or equal to the number of elements in the CategoryBar.

setTransitionSupport

public void setTransitionSupport(boolean transitionSupport)

Sets whether transition effects are enabled on the CategoryBar, which otherwise follow the default device settings.

Parameters:

transitionSupport - true if transition effects should be enabled otherwise false.

setVisibility

public void setVisibility(boolean visibility)

Sets the CategoryBar's visibility, which is hidden by default. Only one CategoryBar may be visible at a time and therefore making a CategoryBar visible will automatically hide any other CategoryBar that is currently visible.

Parameters:

visibility - the requested visible state of this CategoryBar (true for visible or false for hidden).

setHighlightColour

public void setHighlightColour(int colour)

Sets category bar highlight colour.

Parameters:

colour - Highlight colour as RGB integer value. MIDlet can restore highlight to use default colour by using constant DEFAULT_HIGHLIGHT_COLOUR.

setBackgroundColour

public void setBackgroundColour(int colour)

Sets category bar background colour. This method allows client to set category bar background to use solid colour instead of an image. Only applications signed to the manufacturer and operator domain are permitted to use this method.

By default, the CategoryBar has its own default background image. This method provides a way to replace it with a custom background colour, or to restore the default background image if a custom background image or colour has previously been set.

Parameters:

colour - Background colour as RGB integer value. MIDlet can restore background to use default image by using constant DEFAULT_BACKGROUND.

Throws:

java.lang.SecurityException - if the MIDlet does not have permission to set the background image

suppressSizeChanged

public static void suppressSizeChanged(boolean suppressSizeChange)

Suppresses sizeChanged(int,int) events when category bar visibility changes. The suppression is valid only for Canvas class, and will not suppress sizeChanged events for high-level user interface class Screen subclasses such as Form

Parameters:

suppressSizeChange - If true, Category bar visibility change will not cause sizeChanged event.