FileDocCategorySizeDatePackage
ImageItem.javaAPI DocJ2ME MIDP 2.025341Thu Nov 07 12:02:28 GMT 2002javax.microedition.lcdui

ImageItem

public class ImageItem extends Item
An item that can contain an image.

Each ImageItem object contains a reference to an {@link Image} object. This Image may be mutable or immutable. If the Image is mutable, the effect is as if snapshot of its contents is taken at the time the ImageItem is constructed with this Image and when setImage is called with an Image. The snapshot is used whenever the contents of the ImageItem are to be displayed. Even if the application subsequently draws into the Image, the snapshot is not modified until the next call to setImage. The snapshot is not updated when the container of the ImageItem becomes current or becomes visible on the display. (This is because the application does not have control over exactly when Displayables and Items appear and disappear from the display.)

The value null may be specified for the image contents of an ImageItem. If this occurs (and if the label is also null) the ImageItem will occupy no space on the screen.

ImageItem contains layout directives that were originally defined in MIDP 1.0. These layout directives have been moved to the {@link Item} class and now apply to all items. The declarations are left in ImageItem for source compatibility purposes.

The altText parameter specifies a string to be displayed in place of the image if the image exceeds the capacity of the display. The altText parameter may be null.

since
MIDP 1.0

Fields Summary
public static final int
LAYOUT_DEFAULT
See {@link Item#LAYOUT_DEFAULT}.

Value 0 is assigned to LAYOUT_DEFAULT.

public static final int
LAYOUT_LEFT
See {@link Item#LAYOUT_LEFT}.

Value 1 is assigned to LAYOUT_LEFT.

public static final int
LAYOUT_RIGHT
See {@link Item#LAYOUT_RIGHT}.

Value 2 is assigned to LAYOUT_RIGHT.

public static final int
LAYOUT_CENTER
See {@link Item#LAYOUT_CENTER}.

Value 3 is assigned to LAYOUT_CENTER.

public static final int
LAYOUT_NEWLINE_BEFORE
See {@link Item#LAYOUT_NEWLINE_BEFORE}.

Value 0x100 is assigned to LAYOUT_NEWLINE_BEFORE.

public static final int
LAYOUT_NEWLINE_AFTER
See {@link Item#LAYOUT_NEWLINE_AFTER}.

Value 0x200 is assigned to LAYOUT_NEWLINE_AFTER.

private Image
img
The snapshot of the Image of this ImageItem; If the Image of this ImageItem was set to a mutable Image this variable is updated with a new snapshot each time setImage() is called.
private Image
mutImg
If the ImageItem was created with a mutable image or its Image was set to a mutable image, that mutable image is stored in the mutImg variable so that ImageItem.getImage() could return it.
private String
altText
The alternate text of this ImageItem
private int
vertPad
Vertical padding used for this ImageItem so that it is padded to occupy whole number of lines.
private int
appearanceMode
The appearance hint
private int
originalAppearanceMode
The original appearance hint before switching
private static final int
HYPERLINK_PAD
The hyperlink pad used between Hyperlink Border and ImageItem
private static final Image
HYPERLINK_IMG
The hyperlink Image to display with the Hyperlink
private static final Image
VERTICAL_HYPERLINK_IMG
The Vertical hyperlink Image to display with the Hyperlink
Constructors Summary
public ImageItem(String label, Image img, int layout, String altText)
Creates a new ImageItem with the given label, image, layout directive, and alternate text string. Calling this constructor is equivalent to calling 

ImageItem(label, image, layout, altText, PLAIN);

param
label the label string
param
img the image, can be mutable or immutable
param
layout a combination of layout directives
param
altText the text that may be used in place of the image
throws
IllegalArgumentException if the layout value is not a legal combination of directives
see
#ImageItem(String, Image, int, String, int)

  
                                                                                                                 
             
        super(label);

        synchronized (Display.LCDUILock) {
            setImageImpl(img);
            setLayoutImpl(layout);
            this.altText = altText;
        }
public ImageItem(String label, Image image, int layout, String altText, int appearanceMode)
Creates a new ImageItem object with the given label, image, layout directive, alternate text string, and appearance mode. Either label or alternative 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 ImageItem. To provide hyperlink- or button-like behavior, the application should associate a default Command with this ImageItem and add an ItemCommandListener to this ImageItem.

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


ImageItem imgItem =
new ImageItem("Default: ", img,
Item.LAYOUT_CENTER, null,
Item.BUTTON);
imgItem.setDefaultCommand(
new Command("Set", Command.ITEM, 1);
// icl is ItemCommandListener
imgItem.setItemCommandListener(icl);

param
label the label string
param
image the image, can be mutable or immutable
param
layout a combination of layout directives
param
altText the text that may be used in place of the image
throws
IllegalArgumentException if the layout value is not a legal combination of directives
param
appearanceMode the appearance mode of the ImageItem, one of {@link #PLAIN}, {@link #HYPERLINK}, or {@link #BUTTON}
throws
IllegalArgumentException if appearanceMode invalid
since
MIDP 2.0


        this(label, image, layout, altText);

        synchronized (Display.LCDUILock) {
            switch (appearanceMode) {
            case Item.PLAIN:
            case Item.HYPERLINK:
            case Item.BUTTON:
                this.appearanceMode = appearanceMode;
                break;
            default:
                throw new IllegalArgumentException();
            }
        }
Methods Summary
voidaddCommandImpl(Command cmd)
Adds a context sensitive Command to the image item.

param
cmd the command to be removed

        synchronized (Display.LCDUILock) {
            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 a hyperlink
                this.appearanceMode =
                    originalAppearanceMode == Item.BUTTON ?
                    Item.BUTTON : Item.HYPERLINK;

                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;
        }

        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

        return callPreferredHeight(-1);
intcallMinimumWidth()
Get the minimum width of this Item

return
the minimum width

        return callPreferredWidth(-1);
voidcallPaint(Graphics g, int width, int height)
Paint this ImageItem

param
g the Graphics context to paint to
param
width the width of this ImageItem
param
height the height of this ImageItem


        int labelHeight = super.paintLabel(g, width);

        if (img == null) {
            return;
        }

        int x = 0;
        int y = labelHeight;
        int l = getLayout() & ImageItem.LAYOUT_CENTER;

        if (l == ImageItem.LAYOUT_CENTER) {
            x = width / 2;
            if ((numCommands >= 1) &&
               (this.appearanceMode == Item.BUTTON)) {
                x += BUTTON_BORDER + BUTTON_PAD;
                y += BUTTON_BORDER + BUTTON_PAD;
            } else if ((numCommands >= 1) &&
                (this.appearanceMode == Item.HYPERLINK)) {
                x += VERTICAL_HYPERLINK_IMG.getWidth() + HYPERLINK_PAD;
                y += HYPERLINK_IMG.getHeight() + HYPERLINK_PAD;
            }

            g.drawImage(img, x, y,
                        Graphics.TOP | Graphics.HCENTER);

        } else if (l == ImageItem.LAYOUT_RIGHT) {
            x = width;
            if ((numCommands >= 1) &&
               (this.appearanceMode == Item.BUTTON)) {
                x -= (BUTTON_BORDER + BUTTON_PAD);
                y += BUTTON_BORDER + BUTTON_PAD;
            } else if ((numCommands >= 1) &&
                (this.appearanceMode == Item.HYPERLINK)) {
                x -= VERTICAL_HYPERLINK_IMG.getWidth() + HYPERLINK_PAD;
                y += HYPERLINK_IMG.getHeight() + HYPERLINK_PAD;
            }

            g.drawImage(img, x, y,
                        Graphics.TOP | Graphics.RIGHT);

        } else {
            // use x = 0;
            if ((numCommands >= 1) &&
               (this.appearanceMode == Item.BUTTON)) {
                x += BUTTON_BORDER + BUTTON_PAD;
                y += BUTTON_BORDER + BUTTON_PAD;
            } else if ((numCommands >= 1) &&
                (this.appearanceMode == Item.HYPERLINK)) {
                x += VERTICAL_HYPERLINK_IMG.getWidth() + HYPERLINK_PAD;
                y += HYPERLINK_IMG.getHeight() + HYPERLINK_PAD;
            }

            g.drawImage(img, x, y,
                        Graphics.TOP | Graphics.LEFT);
        }

        // draw the button border or hyperlink image

        if ((numCommands >= 1) &&
            (this.appearanceMode == Item.BUTTON)) {
            int w = img.getWidth();
            int h = img.getHeight();
            // y = labelHeight + vertPad/2;
            y = labelHeight;

            if (l == ImageItem.LAYOUT_CENTER) {
                x = (width / 2) - (w / 2);
            } else if (l == ImageItem.LAYOUT_RIGHT) {
                x = width - w - 2 * (BUTTON_BORDER + BUTTON_PAD);
            } else {
                x = 0;
            }

            w += 2 * (BUTTON_BORDER + BUTTON_PAD);
            h += 2 * (BUTTON_BORDER + BUTTON_PAD);
            drawButtonBorder(g, x, y, w, h, hasFocus);

        } else if ((numCommands >= 1) &&
            (this.appearanceMode == Item.HYPERLINK)) {
            // NOTE: We test to see if the width of the Image
            // in the ImageItem is
            // wider than the width of the hyperlink image,
            // if so, we re-draw
            // the image offset to the right as many times as necessary
            // to fill the width of the Image in the ImageItem.

            int imageItemWidth = img.getWidth();
            int imageItemHeight = img.getHeight();
            y = labelHeight;

            if (l == ImageItem.LAYOUT_CENTER) {
                drawTop_BottomBorder(g,
                    width / 2 - imageItemWidth / 2
                    - HYPERLINK_PAD - VERTICAL_HYPERLINK_IMG.getWidth(),
                    width / 2 + imageItemWidth / 2 + 2 * HYPERLINK_PAD,
                    y, y + HYPERLINK_IMG.getHeight()
                    + imageItemHeight + 2 * HYPERLINK_PAD);
                drawLeft_RightBorder(g, y,
                    y + imageItemHeight + (2 * HYPERLINK_PAD),
                    width / 2 - imageItemWidth / 2
                    - VERTICAL_HYPERLINK_IMG.getHeight(),
                    width / 2 + imageItemWidth / 2 + 2 * HYPERLINK_PAD);
            } else if (l == ImageItem.LAYOUT_RIGHT) {
                drawTop_BottomBorder(g,
                    width - imageItemWidth
                    - 2 * HYPERLINK_PAD - VERTICAL_HYPERLINK_IMG.getWidth(),
                    width - VERTICAL_HYPERLINK_IMG.getWidth(),
                    y, y + HYPERLINK_IMG.getHeight()
                    + imageItemHeight + 2 * HYPERLINK_PAD);
                drawLeft_RightBorder(g, y,
                    y + imageItemHeight + 2 * HYPERLINK_PAD,
                    width - imageItemWidth
                    - HYPERLINK_PAD - VERTICAL_HYPERLINK_IMG.getHeight(),
                    width - VERTICAL_HYPERLINK_IMG.getWidth());
            } else {
                drawTop_BottomBorder(g, 0,
                    imageItemWidth + 2 * HYPERLINK_PAD,
                    y, y + HYPERLINK_IMG.getHeight()
                    + imageItemHeight + 2 * HYPERLINK_PAD);
                drawLeft_RightBorder(g, y,
                    y + imageItemHeight + 2 * HYPERLINK_PAD,
                    0,  HYPERLINK_IMG.getHeight()
                    + imageItemWidth + 2 * HYPERLINK_PAD);
            }
        }// end if HYPERLINK
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 (img == null) {
            return getLabelHeight(w);
        }

        if (numCommands >= 1) {
            if (this.appearanceMode == Item.BUTTON) {
                return img.getHeight() + getLabelHeight(w) +
                       (BUTTON_BORDER + BUTTON_PAD) * 2;
            } else if (this.appearanceMode == Item.HYPERLINK) {
                return img.getHeight() + getLabelHeight(w) +
                       (HYPERLINK_IMG.getHeight() + HYPERLINK_PAD) * 2;
            }
        }

        return img.getHeight() + getLabelHeight(w);
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

        if (img == null) {
            return getLabelWidth();
        }

        if (numCommands >= 1) {
            if (this.appearanceMode == Item.BUTTON) {
                return img.getWidth() + (BUTTON_BORDER + BUTTON_PAD) * 2;
            } else if (this.appearanceMode == Item.HYPERLINK) {
                return img.getWidth() + 
                    (VERTICAL_HYPERLINK_IMG.getWidth() + HYPERLINK_PAD) * 2;
            }
        }

        int labelWidth = getLabelWidth();
        int imageW = img.getWidth();
        return (labelWidth > imageW ? labelWidth : imageW);
private voiddrawLeft_RightBorder(Graphics g, int start, int end, int x1, int x2)
Draw Left and Right Border for showing Hyperlink ImageItem

param
g The Graphics context to paint to
param
start start y co-ordinate of ImageItem
param
end end y co-ordinate of ImageItem
param
x1 x co-ordinate of Left ImageItem
param
x2 x co-ordinate of Right ImageItem


        for (int y = start; y < end; y += VERTICAL_HYPERLINK_IMG.getHeight()) {
            // draw the left border
            g.drawImage(VERTICAL_HYPERLINK_IMG, x1,        y,
                        Graphics.TOP | Graphics.LEFT);
            // draw the right border
            g.drawImage(VERTICAL_HYPERLINK_IMG, x2, y,
                        Graphics.TOP | Graphics.LEFT);
        }
private voiddrawTop_BottomBorder(Graphics g, int start, int end, int y1, int y2)
Draw Top and Bottom Border for showing Hyperlink ImageItem

param
g The Graphics context to paint to
param
start start x co-ordinate of ImageItem
param
end end x co-ordinate of ImageItem
param
y1 y co-ordinate of Top ImageItem
param
y2 y co-ordinate of Bottom ImageItem


        for (int x = start; x < end; x += HYPERLINK_IMG.getWidth()) {
            // draw the top  border
            g.drawImage(HYPERLINK_IMG, x, y1,
                        Graphics.TOP | Graphics.LEFT);
            // draw the bottom border
            g.drawImage(HYPERLINK_IMG, x, y2,
                        Graphics.TOP | Graphics.LEFT);
        }
public java.lang.StringgetAltText()
Gets the text string to be used if the image exceeds the device's capacity to display it.

return
the alternate text value, or null if none
see
#setAltText

 
        // SYNC NOTE: return of atomic value, no locking necessary
        return altText;
public intgetAppearanceMode()
Returns the appearance mode of the ImageItem. See Appearance Modes.

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

        return appearanceMode;
public ImagegetImage()
Gets the image contained within the ImageItem, or null if there is no contained image.

return
image used by the ImageItem
see
#setImage

        synchronized (Display.LCDUILock) {
            return mutImg == null ? img : mutImg;
        }
public intgetLayout()
Gets the layout directives used for placing the image.

return
a combination of layout directive values
see
#setLayout

        // NOTE: looks odd, but this method is required for 1.0 compatiblitiy
        return super.getLayout();
voidremoveCommandImpl(Command cmd)
Removes the context sensitive command from item.

param
cmd the command to be removed

        synchronized (Display.LCDUILock) {
            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;

                // size or appearance changed
                invalidate();
            } 
        } // synchronized
public voidsetAltText(java.lang.String text)
Sets the alternate text of the ImageItem, or null if no alternate text is provided.

param
text the new alternate text
see
#getAltText

        // SYNC NOTE: atomic, no locking necessary
        this.altText = text;
private voidsetAltTextImpl(java.lang.String text)
Set the alternate text for this ImageItem

param
text The alternate text for this ImageItem

        this.altText = text;
public voidsetImage(Image img)
Sets the Image object contained within the ImageItem. The image may be mutable or immutable. If img is null, the ImageItem is set to be empty. If img is mutable, the effect is as if a snapshot is taken of img's contents immediately prior to the call to setImage. This snapshot is used whenever the contents of the ImageItem are to be displayed. If img is already the Image of this ImageItem, the effect is as if a new snapshot of img's contents is taken. Thus, after painting into a mutable image contained by an ImageItem, the application can call 

imageItem.setImage(imageItem.getImage());

to refresh the ImageItem's snapshot of its Image.

If the ImageItem is visible on the display when the snapshot is updated through a call to setImage, the display is updated with the new snapshot as soon as it is feasible for the implementation to so do.

param
img the Image for this ImageItem, or null if none
see
#getImage

        synchronized (Display.LCDUILock) {
            setImageImpl(img);
            invalidate();
        }
private voidsetImageImpl(Image img)
Set the Image for this ImageItem

param
img The image to use for this ImageItem

        if (img != null && img.isMutable()) {
            this.mutImg = img;
            this.img = Image.createImage(img); // use immutable copy of img
        } else { 
            this.mutImg = null;
            this.img = img;
        }
public voidsetLayout(int layout)
Sets the layout directives.

param
layout a combination of layout directive values
throws
IllegalArgumentException if the value of layout is not a valid combination of layout directives
see
#getLayout

        // NOTE: looks odd, but this method is required for 1.0 compatiblitiy
        super.setLayout(layout);
booleanshouldSkipTraverse()
Determine if Form should not traverse to this ImageItem

return
true if Form should not traverse to this ImageItem

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

        return false;