javax.microedition.lcdui
Class TabbedPane

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Screen
          javax.microedition.lcdui.TabbedPane

public class TabbedPane
extends Screen

TabbedPane is a Screen subclass that presents a series of Screens to the users and allows them to navigate between screens by selecting the corresponding tab.

Each tab has a Screen object that is its contents. Only Form and List objects can be added as the contents for a tab. Another TabbedPane cannot be used as the contents for a tab. A Screen MUST only be placed on one tab at a time.

Each tab must include an icon Image object or text to indicate its content. Therefore, the TabbedPane class has two modes to represent the contents of the tabs.

1) String mode In String mode, Strings are used to represent each tab's contents. The tab's name is the title of the tab content, which can be null. In this mode, TabbedPane's title area always displays TabbedPane's title to avoid redundancy.

2) Image mode In Image mode, icons represent each tab's contents. The Image may be mutable or immutable; if the Image is mutable, the effect is as if a snapshot of the Image is taken at the time the TabbedPane is constructed or the tab is added to the TabbedPane. Subsequent drawing operations performed on the Image will not automatically appear in the tab. Explicitly calling #setTabIcon with the same Image will cause the icon to be refreshed with the Image's current contents.

Implementations may truncate or scale the icon image if it is larger than the size supported by device. Applications can query the implementation's tab icon size by calling Display.getBestImageWidth(int) and Display.getBestImageHeight(int) methods using the Display.TAB image type. The style and appearance of tabs are platform-dependent.

The number of tabs is not limited and may exceed the number that can be shown on the screen at one time. In that case, implementations must indicate to users that more tabs are available and provide a mechanism for accessing them. An application can be notified of tab navigation events on a given TabbedPane using the TabListener interface.

In Image mode, the title shown for the TabbedPane depends on the suppressTitle parameter. In String mode, TabbedPane's title is always shown to avoid redundancy.

Similarly, the TabbedPane's Ticker (if present) takes precedence over the Ticker belonging to the selected tab's contents.

Commands and Menus may be added to the TabbedPane and to the contents of its tabs. The Commands and Menus shown to the user include those belonging to the TabbedPane and those belonging to the selected tab's contents. A Command or Menu is shown only once even if it belongs to both objects. If such a Command is invoked, both objects' CommandListeners are notified; the listener for the tab's content is notified first, followed by that of the TabbedPane.

A tab is removed from the tabbed pane using removeTab(index) . If a tab at index n is removed, then the implementation must select the tab at index n-1. If tab at index n-1 does not exist, then tab at index n+1 must be selected. Therefore, getSelectedIndex() after a removeTab() will return the next selected tab. If the removeTab(index) removes the last tab in the tabbedpane, then no tabs are selected and the getSelectedIndex() will return -1.

Calling setCurrent on the TabbedPane content MUST set the focus on the content. Calling setCurrent on the TabbedPane MUST set the focus on the first tab element, not the content. Calling setFocus MUST set the focus on the tab element indicated by the given index parameter. By default the focus MUST be on the first tab element.

The mechanism used by the user to navigate between tabs is implementation dependent. However, it must allow for the user to navigate within the contents of each tab and between tabs.

TabbedPane implementations on keypad-based devices SHOULD support vertical and horizontal traversals in the follow manner.

Initial State	Down Key press	Up key press	Left/Right key press
Focus on tab (tab icon)	Focus is set into the tab content (screen object)	None or platform specific implementation.	Change tab focus to next/prior tab. The set of commands shown to the user changes to those belonging to the TabbedPane and those belonging to the newly selected tab's contents. A TabListener.tabChangeEvent is generated.
Focus into the tab content (Screen object)	Default traversal already implemented on both Form and List classes.	Focus is set on tab (tab icon). This behavior supposes that the topmost focusable item is selected on tabbed pane content. If TabbedPane content has items that cannot get the focus, the traversal with hardware keys SHOULD be implemented so that if up key is pressed then the focus SHOULD move to the tab even if there are unfocusable items in-between.	Default traversal already implemented on either Form and List classes or specific device implementation. If there is no horizontal traversal in the tab content, the left and right keys SHOULD be reserved for traversing between tabs, and up and down keys for traversing inside the tab content.

Since:

MIDP 3.0

Constructor Summary

TabbedPane(java.lang.String title, boolean stringTab, boolean suppressTitle)
Creates a new, empty TabbedPane, specifying its title.

Method Summary

void	addTab(Screen tab, Image icon) Adds a tab element to the TabbedPane as the last element.
void	addTabListener(TabListener tabListener) Sets a listener for focus change to this TabbedPane, replacing any previous TabListener.
int	getCount() Gets the number of tab elements in the TabbedPane.
int	getHeight() Returns the height in pixels of the area available for Displayables added to the TabbedPane.
Screen	getScreen(int index) Gets the content for the tab references by the given index.
int	getSelectedIndex() Returns the index number of a tab element (current tab) in the TabbedPane.
Image	getTabIcon(int index) Gets the Image for the tab referenced by the given index.
int	getWidth() Returns the width in pixels of the area available for Displayables added to the TabbedPane.
void	insertTab(int index, Screen tab, Image icon) Inserts a tab element into the TabbedPane just prior to the element specified.
void	removeTab(int index) Removes a tab element from TabbedPane.
void	setFocus(int index) Sets the focus on a tab element.
void	setTabIcon(int index, Image icon) Sets the Image part of the tab element referenced by index, replacing the previous image of the tab.

Methods inherited from class javax.microedition.lcdui.Displayable

addCommand, getCommand, getCommandLayoutPolicy, getCommands, getCurrentDisplay, getMenu, getTicker, getTitle, invalidateCommandLayout, isShown, removeCommand, removeCommandOrMenu, setCommand, setCommandLayoutPolicy, setCommandListener, setMenu, setTicker, setTitle, sizeChanged

Methods inherited from class java.lang.Object

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

Constructor Detail

TabbedPane

public TabbedPane(java.lang.String title,
                  boolean stringTab,
                  boolean suppressTitle)

Creates a new, empty TabbedPane, specifying its title. If the TabbedPane is in "String mode", the suppressTitle argument is ignored.

Parameters:

title - the screen's title (see Displayable).

stringTab - a boolean value representing the mode of the TabbedPane
true - indicates that the TabbedPane is in "String mode"
false - indicates that the TabbedPane is in "Image mode"

suppressTitle - a boolean value representing the state of the screen's title.
true - indicates that title will be set according to tab element's
title (current tab), ignoring any title set on the TabbedPane object.
false - indicates that title will be fixed, set on the TabbedPane object.

Since:

MIDP 3.0

Method Detail

addTab

public void addTab(Screen tab,
                   Image icon)

Adds a tab element to the TabbedPane as the last element. If the TabbedPane is in "String mode", the icon argument is ignored.

Parameters:

tab - screen object (tab element) to be added.

icon - image part of the tab element.

Throws:

java.lang.NullPointerException - if the icon is null and the TabbedPane is in "Image mode", or if the tab is null in any mode

java.lang.IllegalArgumentException - if the screen is not an instance of Form, or List

java.lang.IllegalStateException - if the tab has already been placed on this or another TabbedPane

java.lang.IllegalStateException - if the tab is current on another Display

Since:

MIDP 3.0

addTabListener

public void addTabListener(TabListener tabListener)

Sets a listener for focus change to this TabbedPane, replacing any previous TabListener. A null reference is allowed and has the effect of removing any existing listener.

Parameters:

tabListener - The new listener or null.

Since:

MIDP 3.0

insertTab

public void insertTab(int index,
                      Screen tab,
                      Image icon)

Inserts a tab element into the TabbedPane just prior to the element specified. The size of the TabbedPane grows by one. If the TabbedPane is in "String mode", the icon argument is ignored. The index parameter must be within the range [0..getCount()], inclusive. If the value of getCount() is used for the index, the new element is inserted immediately after the last element. In this case, the effect is identical to addTab().

Parameters:

index - the index of the tab where insertion is to occur, starting from zero.

tab - the tab object (Screen) to be inserted.

icon - the image part of the tab element.

Throws:

java.lang.IndexOutOfBoundsException - if index is not within the range [0..getCount()], inclusive.

java.lang.NullPointerException - if either tab or icon is null while the TabbedPane is in "Image mode"

java.lang.IllegalArgumentException - if the screen is not an instance of Form, or List

java.lang.IllegalStateException - if the tab has already been placed on this or another TabbedPane

java.lang.IllegalStateException - if the tab is current on another Display

Since:

MIDP 3.0

setFocus

public void setFocus(int index)

Sets the focus on a tab element. The index parameter must be within the range [0..getCount()-1], inclusive.

Parameters:

index - the index of the tab element to receive the focus.

Throws:

java.lang.IndexOutOfBoundsException - if index is not within the range [0..getCount()-1], inclusive.

Since:

MIDP 3.0

setTabIcon

public void setTabIcon(int index,
                       Image icon)

Sets the Image part of the tab element referenced by index, replacing the previous image of the tab. This method may also be used to update a tab that was created using a mutable Image; this method should be called with the same Image after its contents have been changed to update the appearance of the tab. If the TabbedPane is in "String mode", then the icon argument is ignored. The index parameter must be within the range [0..getCount()-1], inclusive.

Parameters:

index - the index of the tab element to be set.

icon - the new image of the tab element.

Throws:

java.lang.IndexOutOfBoundsException - if index is not within the range [0..getCount()-1], inclusive.

java.lang.NullPointerException - if icon is null while the TabbedPane is in "Image mode"

Since:

MIDP 3.0

removeTab

public void removeTab(int index)

Removes a tab element from TabbedPane. If the tab element is being shown on the display, the implementation should update the display as soon as it is feasible to do so. The index parameter must be within the range [0..getCount()-1], inclusive.

Parameters:

index - the index number of the tab to be removed.

Throws:

java.lang.IndexOutOfBoundsException - if index is not within the range [0..getCount()-1], inclusive.

Since:

MIDP 3.0

getCount

public int getCount()

Gets the number of tab elements in the TabbedPane.

Returns:

the number of tab elements in the TabbedPane.

Since:

MIDP 3.0

getSelectedIndex

public int getSelectedIndex()

Returns the index number of a tab element (current tab) in the TabbedPane.

Returns:

index of selected tab, or -1 if none.

Since:

MIDP 3.0

getScreen

public Screen getScreen(int index)

Gets the content for the tab references by the given index. The index parameter must be within the range [0..getCount()-1], inclusive.

Parameters:

index - the index number of the tab to be returned, starting from zero.

Returns:

a Screen object (tab element) in the TabbedPane referenced by index, or null if index is invalid.

Throws:

java.lang.IndexOutOfBoundsException - if index is not within the range [0..getCount()-1], inclusive.

Since:

MIDP 3.0

getTabIcon

public Image getTabIcon(int index)

Gets the Image for the tab referenced by the given index. If the TabbedPane is in "String mode", this always returns null. The index parameter must be within the range [0..getCount()-1], inclusive.

Parameters:

index - the index number of the tab to be queried.

Returns:

the image part of the tab referenced by index, or null if index is invalid or if the TabbedPane is in the "String mode".

Throws:

java.lang.IndexOutOfBoundsException - if index is not within the range [0..getCount()-1], inclusive.

Since:

MIDP 3.0

getWidth

public int getWidth()

Returns the width in pixels of the area available for Displayables added to the TabbedPane. This area excludes the tabs themselves and any borders that are drawn around the added Displayables. The width returned is the maximum width that getWidth and getWidth can return if the Form or List is in focus within the TabbedPane.

Specified by:

getWidth in class Displayable

Returns:

the width in pixels available to display a Form or a List

Since:

MIDP 3.0

getHeight

public int getHeight()

Returns the height in pixels of the area available for Displayables added to the TabbedPane. This area excludes the tabs themselves and any borders that are drawn around the added Displayables. The height returned is the maximum height that getHeight and getHeight can return if the Form or List is in focus within the TabbedPane.

Specified by:

getHeight in class Displayable

Returns:

the height in pixels available to display a Form or a List

Since:

MIDP 3.0