javax.microedition.lcdui
Class StringItem

java.lang.Object
  extended by javax.microedition.lcdui.Item
      extended by 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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.