javax.microedition.lcdui
Class StringItem

java.lang.Object
  javax.microedition.lcdui.Item
      javax.microedition.lcdui.StringItem

public class StringItem
extends Item

An item that can contain a string. A StringItem is display-only; the user cannot edit the contents. Both the label and the textual content of a StringItem may be modified by the application. The visual representation of the label may differ from that of the textual contents.

Field Summary

Fields inherited from class javax.microedition.lcdui.Item

BUTTON, HYPERLINK, LAYOUT_2, LAYOUT_BOTTOM, LAYOUT_CENTER, LAYOUT_DEFAULT, LAYOUT_EXPAND, LAYOUT_LEFT, LAYOUT_NEWLINE_AFTER, LAYOUT_NEWLINE_BEFORE, LAYOUT_RIGHT, LAYOUT_SHRINK, LAYOUT_TOP, LAYOUT_VCENTER, LAYOUT_VEXPAND, LAYOUT_VSHRINK, PLAIN

Constructor Summary

StringItem(String label, String text)
Creates a new StringItem object with the given label and textual content.

StringItem(String label, String text, int appearanceMode)
Creates a new StringItem object with the given label, textual content, and appearance mode.

Method Summary
void	addCommand(Command cmd) Adds a context sensitive Command to the item.
int	getAppearanceMode() Returns the appearance mode of the StringItem.
Font	getFont() Gets the application's preferred font for rendering this StringItem.
String	getLabel() Gets the label of this Item object.
int	getMinimumHeight() Gets the minimum height for this Item.
int	getMinimumWidth() Gets the minimum width for this Item.
String	getText() Gets the text contents of the StringItem, or null if the StringItem is empty.
void	removeCommand(Command cmd) Removes the context sensitive command from item.
void	setDefaultCommand(Command cmd) Sets default Command for this Item.
void	setFont(Font font) Sets the application's preferred font for rendering this StringItem.
void	setLabel(String label) Sets the label of the Item.
void	setText(String text) Sets the text contents of the StringItem.

Methods inherited from class javax.microedition.lcdui.Item

getLayout, getPreferredHeight, getPreferredWidth, notifyStateChanged, setItemCommandListener, setLayout, setPreferredSize

Methods inherited from class java.lang.Object

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

Constructor Detail

StringItem

public StringItem(String label,
                  String text)

Creates a new StringItem object with the given label and textual content. Calling this constructor is equivalent to calling
StringItem(label, text, PLAIN);

RIM Implementation Note

Either label or text may be present or null.

Parameters:

label - the Item label

text - the text contents

StringItem

public StringItem(String label,
                  String text,
                  int appearanceMode)

Creates a new StringItem object with the given label, textual content, and appearance mode. Either label or text may be present or null.

The appearanceMode parameter (see Appearance Modes) is a hint to the platform of the application's intended use for this StringItem. To provide hyperlink- or button-like behavior, the application should associate a default Command with this StringItem and add an ItemCommandListener to this StringItem.

Here is an example showing the use of a StringItem as a button:

     StringItem strItem = 
         new StringItem("Default: ", "Set",     
                        Item.BUTTON);    
     strItem.setDefaultCommand(
         new Command("Set", Command.ITEM, 1);    
     // icl is ItemCommandListener 
     strItem.setItemCommandListener(icl);     

Parameters:

label - the StringItem's label, or null if no label

text - the StringItem's text contents, or null if the contents are initially empty

appearanceMode - the appearance mode of the StringItem, one of Item.PLAIN, Item.HYPERLINK, or Item.BUTTON

Throws:

IllegalArgumentException - if appearanceMode invalid

Since:

BlackBerry API 4.0.0, MIDP 2.0

Method Detail

getText

public String getText()

Gets the text contents of the StringItem, or null if the StringItem is empty.

Returns:

a string with the content of the item

setText

public void setText(String text)

Sets the text contents of the StringItem. If text is null, the StringItem is set to be empty.

Parameters:

text - the new content

setLabel

public void setLabel(String label)

Description copied from class: Item

Sets the label of the Item. If label is null, specifies that this item has no label.

Overrides:

setLabel in class Item

Parameters:

label - the label string

getLabel

public String getLabel()

Description copied from class: Item

Gets the label of this Item object.

Overrides:

getLabel in class Item

Returns:

the label string

See Also:

Item.getLabel()

addCommand

public void addCommand(Command cmd)

Description copied from class: Item

Adds a context sensitive Command to the item. The semantic type of Command should be ITEM. The implementation will present the command only when the item is active, for example, highlighted.

If the added command is already in the item (tested by comparing the object references), the method has no effect. If the item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

addCommand in class Item

Parameters:

cmd - the command to be added

See Also:

Item.addCommand(Command)

Since:

BlackBerry API 5.0.0

removeCommand

public void removeCommand(Command cmd)

Description copied from class: Item

Removes the context sensitive command from item. If the command is not in the Item (tested by comparing the object references), the method has no effect. If the Item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so. If the command to be removed happens to be the default command, the command is removed and the default command on this Item is set to null. The following code:

     // Command c is the default command on Item item
     item.removeCommand(c);
 

is equivalent to the following code:

     // Command c is the default command on Item item
     item.setDefaultCommand(null);
     item.removeCommand(c);
 

Overrides:

removeCommand in class Item

Parameters:

cmd - the command to be removed

See Also:

Item.removeCommand(Command)

Since:

BlackBerry API 5.0.0

setDefaultCommand

public void setDefaultCommand(Command cmd)

Description copied from class: Item

Sets default Command for this Item. If the Item previously had a default Command, that Command is no longer the default, but it remains present on the Item.

If not null, the Command object passed becomes the default Command for this Item. If the Command object passed is not currently present on this Item, it is added as if Item.addCommand(javax.microedition.lcdui.Command) had been called before it is made the default Command.

If null is passed, the Item is set to have no default Command. The previous default Command, if any, remains present on the Item.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

setDefaultCommand in class Item

Parameters:

cmd - the command to be used as this Item's default Command, or null if there is to be no default command

See Also:

Item.setDefaultCommand(Command)

Since:

BlackBerry API 5.0.0

getMinimumWidth

public int getMinimumWidth()

Description copied from class: Item

Gets the minimum width for this Item. This is a width at which the item can function and display its contents, though perhaps not optimally. See Item Sizes for a complete discussion.

Overrides:

getMinimumWidth in class Item

Returns:

the minimum width of the item

See Also:

Item.getMinimumWidth()

Since:

BlackBerry API 5.0.0

getMinimumHeight

public int getMinimumHeight()

Description copied from class: Item

Gets the minimum height for this Item. This is a height at which the item can function and display its contents, though perhaps not optimally. See Item Sizes for a complete discussion.

Overrides:

getMinimumHeight in class Item

Returns:

the minimum height of the item

See Also:

Item.getMinimumHeight()

Since:

BlackBerry API 5.0.0

getAppearanceMode

public int getAppearanceMode()

Returns the appearance mode of the StringItem. See Appearance Modes.

Returns:

the appearance mode value, one of Item.PLAIN, Item.HYPERLINK, or Item.BUTTON

Since:

BlackBerry API 4.0.0, MIDP 2.0

setFont

public void setFont(Font font)

Sets the application's preferred font for rendering this StringItem. The font is a hint, and the implementation may disregard the application's preferred font.

The font parameter must be a valid Font object or null. If the font parameter is null, the implementation must use its default font to render the StringItem.

Parameters:

font - the preferred font to use to render this StringItem

See Also:

StringItem.getFont()

Since:

BlackBerry API 4.0.0, MIDP 2.0

getFont

public Font getFont()

Gets the application's preferred font for rendering this StringItem. The value returned is the font that had been set by the application, even if that value had been disregarded by the implementation. If no font had been set by the application, or if the application explicitly set the font to null, the value is the default font chosen by the implementation.

Returns:

the preferred font to use to render this StringItem

See Also:

StringItem.setFont(javax.microedition.lcdui.Font)

Since:

BlackBerry API 4.0.0, MIDP 2.0