FileDocCategorySizeDatePackage
StringItem.javaAPI DocJ2ME MIDP 2.019441Thu Nov 07 12:02:28 GMT 2002javax.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.

Fields Summary
private String
str
The text of this StringItem
private Font
font
The Font to render this StringItem's text in
private int
appearanceMode
The appearance hint
private int
originalAppearanceMode
The original appearance hint before switching
private int
minimumLineHeight
Minimum height for one line
private boolean
skipTraverse
An internal flag. True if Form should not traverse to this StringItem
Constructors Summary
public StringItem(String label, String text)
Creates a new StringItem object. Calling this constructor is equivalent to calling 

StringItem(label, text, PLAIN);

param
label the Item label
param
text the text contents
see
#StringItem(String, String, int)

        this(label, text, Item.PLAIN);
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);

param
label the StringItem's label, or null if no label
param
text the StringItem's text contents, or null if the contents are initially empty
param
appearanceMode the appearance mode of the StringItem, one of {@link #PLAIN}, {@link #HYPERLINK}, or {@link #BUTTON}
throws
IllegalArgumentException if appearanceMode invalid
since
MIDP 2.0

        super(label);

        synchronized (Display.LCDUILock) {
            switch (appearanceMode) {
                case Item.PLAIN:
                case Item.HYPERLINK:
                case Item.BUTTON:
                    this.appearanceMode = appearanceMode;
                    break;
                default:
                    throw new IllegalArgumentException();
            }

            this.str = text;
            this.font = Screen.CONTENT_FONT;

            int labelFontHeight = LABEL_FONT.getHeight();
            minimumLineHeight = Screen.CONTENT_HEIGHT;

            if (minimumLineHeight < labelFontHeight) {
                minimumLineHeight = labelFontHeight;
            }

            checkTraverse();
        }
Methods Summary
voidaddCommandImpl(Command cmd)
Adds a context sensitive Command to the item.

param
cmd the command to be removed

        synchronized (Display.LCDUILock) {
            // The super class will update the command set of the Form
            super.addCommandImpl(cmd);

            if ((numCommands >= 1) && (appearanceMode == Item.PLAIN)) {
                // restore the value of the original appearanceMode
                // if it is a button
                // otherwise simple change the appearanceMode
                // to hyperlink
                this.appearanceMode =
                    originalAppearanceMode == Item.BUTTON ?
                    Item.BUTTON : Item.HYPERLINK;
            }

            checkTraverse();
            invalidate();
        } // synchronized
voidcallKeyPressed(int keyCode)
Called by the system to signal a key press

param
keyCode the key code of the key that has been pressed
see
#getInteractionModes

        if (keyCode != Display.KEYCODE_SELECT) {
            return;
        }

        // StringItem takes focus only if there are one or more Item Commands
        // attached to it
        if (!(getCommandCount() > 0) || commandListener == null) {
            return;
        }

        ItemCommandListener cl = null;
        Command defaultCmd = null;

        synchronized (Display.LCDUILock) {
            cl = commandListener;
            defaultCmd = defaultCommand;
        } // synchronized

        // SYNC NOTE: The call to the listener must occur outside
        // of the lock
        if (cl != null) {
            try {
                // SYNC NOTE: We lock on calloutLock around any calls
                // into application code
                synchronized (Display.calloutLock) {
                    if (defaultCmd != null) {
                        cl.commandAction(defaultCmd, this);
                    } else {
                        // REMINDER : Needs HI decision
                        // either call the first command
                        // from  the command list or
                        // invoke the menu
                    }
                }
            } catch (Throwable thr) {
                Display.handleThrowable(thr);
            }
        }
intcallMinimumHeight()
Get the minimum height of this Item

return
the minimum height

        // IF we decide to have minHeight as one line
        // we need to change the way painting is done 
        // (to divide allocated space between label and string)
        return callPreferredHeight(-1);
intcallMinimumWidth()
Get the minimum width of this Item

return
the minimum width

        int pW = callPreferredWidth(-1);

        // FIX ME: paint() does not know to paint in a width which is less
        // than preferred
        int w = font.charWidth('W") * 8 + 6 * font.charWidth('.");
        if (w > pW) {
            w = pW;
        }

        if (isButton()) {
            w += 2 * (BUTTON_BORDER + BUTTON_PAD);
        }
        return w;
voidcallPaint(Graphics g, int width, int height)
Paint this StringItem

param
g the Graphics object to paint to
param
width the width of this item
param
height the height of this item


        int w = width;
        int h = height;
        
        int translateY = 0;
        int translateX = 0;

        if (isButton()) {
            translateX = translateY = BUTTON_BORDER + BUTTON_PAD;
            w -= 2*translateX;
            h -= 2*translateY;
            g.translate(translateX, translateY);
        }

        Font lFont = (LABEL_BOLD_ON_TRAVERSE && !hasFocus) ?
                     Screen.CONTENT_FONT : LABEL_FONT;

        int labelHeight = getLabelHeight(w);

        int offset = Text.paint(label, lFont, 
                                g, w, labelHeight, 0, Text.NORMAL, null);
        if (offset > 0) {
            offset += LABEL_PAD;
        }

        int mode = Text.NORMAL;
        if (numCommands > 0 && appearanceMode == Item.HYPERLINK) { 
            mode = hasFocus ? (Text.INVERT | Text.HYPERLINK) :
                              (Text.NORMAL | Text.HYPERLINK);
        }

        int yOffset = labelHeight;
        if (labelHeight > 0) {
            yOffset -= (lFont.getHeight() < font.getHeight() ?
                        lFont.getHeight() : font.getHeight());
        }

        g.translate(0, yOffset);
        translateY += yOffset;

        Text.paint(str, font, g, w, h - yOffset, offset, mode, null);

        g.translate(-translateX, -translateY);

        if (isButton()) {
            drawButtonBorder(g, 0, 0, width, height, hasFocus);
        }
intcallPreferredHeight(int w)
Get the preferred height of this Item

param
w the tentative content width in pixels, or -1 if a tentative width has not been computed
return
the preferred height

        if (w == -1) {
            w = DEFAULT_WIDTH;
        }

        if (isButton()) {
            int buttonPad = 2 * (BUTTON_BORDER + BUTTON_PAD);
            int prefH     = Text.getTwoStringsHeight(label, str, 
                                                     LABEL_FONT, font,
                                                     w - buttonPad, 
                                                     LABEL_PAD);
            return (prefH > 0 ? prefH + buttonPad : 0);
        }

        return Text.getTwoStringsHeight(label, str, LABEL_FONT, font,
                                        w, LABEL_PAD);
intcallPreferredWidth(int h)
Get the preferred width of this Item

param
h the tentative content height in pixels, or -1 if a tentative height has not been computed
return
the preferred width


        // FIX ME: we ignore the 'h' value and just return
        // a basic width based on our contents. That is, this
        // StringItem's preferred width is always based on
        // being one line high
        
        if (isButton()) {
            int buttonPad = 2 * (BUTTON_BORDER + BUTTON_PAD);
            int prefW     = Text.getTwoStringsWidth(label, str, LABEL_FONT, 
                                                    font, 
                                                    DEFAULT_WIDTH - buttonPad,
                                                    LABEL_PAD);
            return (prefW > 0 ? prefW + buttonPad : 0);
        }

        return Text.getTwoStringsWidth(label, str, LABEL_FONT, font, 
                                       DEFAULT_WIDTH, LABEL_PAD);
private voidcheckTraverse()
Check that given the label, text, and commands, Form should traverse this StringItem. Updates the internal 'skipTraverse' variable.

        if (str == null && label == null) {
            skipTraverse = true;
        } else if (str == null && label.trim().equals("")) {
            skipTraverse = true;
        } else if (label == null && str.trim().equals("")) {
            skipTraverse = true;
        } else {
            skipTraverse = false;
        }
booleanequateNLA()
Determine if this Item should have a newline after it

return
true if it should have a newline after


        // If content ends with a \n,
        // there is a newline after this StringItem no matter what
        if (str != null && str.length() > 0) {
            if (str.charAt(str.length() - 1) == '\n") {
                return true;
            }
        } else if (label != null && label.length() > 0) {
            // If there is no content and our label ends with a \n, 
            // there is a newline after this StringItem
            if (label.charAt(label.length() - 1) == '\n") {
                return true;
            }
        } else {
            // empty StringItem
            return false;
        }

        if ((layout & Item.LAYOUT_2) == Item.LAYOUT_2) {
            return ((layout & Item.LAYOUT_NEWLINE_AFTER)
                            == Item.LAYOUT_NEWLINE_AFTER);
        }
        return false;
booleanequateNLB()
Determine if this Item should have a newline before it

return
true if it should have a newline before


        // If label starts with a\n,
        // put this StringItem on a newline no matter what
        if (label != null && label.length() > 0) {
            if (label.charAt(0) == '\n") {
                return true;
            }
        } else if (str != null && str.length() > 0) {
            // If there is no label and our content starts with a \n,
            // this StringItem starts on a newline
            if (str.charAt(0) == '\n") {
                return true;
            }
        } else {
            // empty StringItem
            return false;
        }

        if ((layout & Item.LAYOUT_2) == Item.LAYOUT_2) {
            return ((layout & Item.LAYOUT_NEWLINE_BEFORE)
                            == Item.LAYOUT_NEWLINE_BEFORE);
        }
            
        // in MIDP1.0 new any StringItem with a non-null label would
        // go on a new line
        return label != null && label.length() > 0;
public intgetAppearanceMode()
Returns the appearance mode of the StringItem. See Appearance Modes.

return
the appearance mode value, one of {@link #PLAIN}, {@link #HYPERLINK}, or {@link #BUTTON}
since
MIDP 2.0

        // SYNC NOTE: return of atomic value, no locking necessary
        return appearanceMode;
public FontgetFont()
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.

return
the preferred font to use to render this StringItem
see
#setFont
since
MIDP 2.0

        // SYNC NOTE: return of atomic value, no locking necessary
            return font;
public java.lang.StringgetText()
Gets the text contents of the StringItem, or null if the StringItem is empty.

return
a string with the content of the item
see
#setText

        // SYNC NOTE: return of atomic value, no locking necessary
        return str;
private booleanisButton()
Determines if this StringItem should be rendered with the button border.

return
true if the StringItem should be rendered with the button border, false - otherwise

        return (numCommands > 0 && appearanceMode == Item.BUTTON);
voidremoveCommandImpl(Command cmd)
Removes the context sensitive command from item.

param
cmd the command to be removed

        synchronized (Display.LCDUILock) {
            // The super class will update the command set of the Form
            super.removeCommandImpl(cmd);

            if ((numCommands < 1) && (appearanceMode != Item.PLAIN)) {
                // store value of the original appearanceMode
                originalAppearanceMode = this.appearanceMode;
                // change the appearanceMode to plain
                this.appearanceMode = Item.PLAIN;
            }

            checkTraverse();
            invalidate();
        } // synchronized
public voidsetFont(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.

param
font the preferred font to use to render this StringItem
see
#getFont
since
MIDP 2.0

        this.font = font;
public voidsetPreferredSize(int width, int height)
Sets the preferred width and height for this Item. Values for width and height less than -1 are illegal. If the width is between zero and the minimum width, inclusive, the minimum width is used instead. If the height is between zero and the minimum height, inclusive, the minimum height is used instead.

Supplying a width or height value greater than the minimum width or height locks that dimension to the supplied value. The implementation may silently enforce a maximum dimension for an Item based on factors such as the screen size. Supplying a value of -1 for the width or height unlocks that dimension. See Item Sizes for a complete discussion.

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

param
width the value to which the width should be locked, or -1 to unlock
param
height the value to which the height should be locked, or -1 to unlock
throws
IllegalArgumentException if width or height is less than -1
throws
IllegalStateException if this Item is contained within an Alert
see
#getPreferredHeight
see
#getPreferredWidth
since
MIDP 2.0

        super.setPreferredSize(width, height);
public voidsetText(java.lang.String text)
Sets the text contents of the StringItem. If text is null, the StringItem is set to be empty.

param
text the new content
see
#getText

        synchronized (Display.LCDUILock) {
            this.str = text;
            checkTraverse();
            invalidate();
        }
booleanshouldSkipTraverse()
Determine if Form should not traverse to this StringItem

return
true if Form should not traverse to this StringItem

        if ((label == null || label.length() == 0) && 
            (str == null || str.length() == 0)) {
            return true;
        }

        return skipTraverse;