MID Profile

javax.microedition.lcdui
Class ImageItem

java.lang.Object
  |
  +--javax.microedition.lcdui.Item
        |
        +--javax.microedition.lcdui.ImageItem

public class ImageItem
extends Item

An item that can contain an image.

Each ImageItem object contains a reference to an 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 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

Field Summary
static int LAYOUT_CENTER
          See Item.LAYOUT_CENTER.
static int LAYOUT_DEFAULT
          See Item.LAYOUT_DEFAULT.
static int LAYOUT_LEFT
          See Item.LAYOUT_LEFT.
static int LAYOUT_NEWLINE_AFTER
          See Item.LAYOUT_NEWLINE_AFTER.
static int LAYOUT_NEWLINE_BEFORE
          See Item.LAYOUT_NEWLINE_BEFORE.
static int LAYOUT_RIGHT
          See Item.LAYOUT_RIGHT.
 
Fields inherited from class javax.microedition.lcdui.Item
BUTTON, HYPERLINK, LAYOUT_2, LAYOUT_BOTTOM, LAYOUT_EXPAND, LAYOUT_SHRINK, LAYOUT_TOP, LAYOUT_VCENTER, LAYOUT_VEXPAND, LAYOUT_VSHRINK, PLAIN
 
Constructor Summary
ImageItem(String label, Image img, int layout, String altText)
          Creates a new ImageItem with the given label, image, layout directive, and alternate text string.
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.
 
Method Summary
 String getAltText()
          Gets the text string to be used if the image exceeds the device's capacity to display it.
 int getAppearanceMode()
          Returns the appearance mode of the ImageItem.
 Image getImage()
          Gets the image contained within the ImageItem, or null if there is no contained image.
 int getLayout()
          Gets the layout directives used for placing the image.
 void setAltText(String text)
          Sets the alternate text of the ImageItem, or null if no alternate text is provided.
 void setImage(Image img)
          Sets the Image object contained within the ImageItem.
 void setLayout(int layout)
          Sets the layout directives.
 
Methods inherited from class javax.microedition.lcdui.Item
addCommand, getLabel, getMinimumHeight, getMinimumWidth, getPreferredHeight, getPreferredWidth, notifyStateChanged, removeCommand, setDefaultCommand, setItemCommandListener, setLabel, setPreferredSize
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LAYOUT_DEFAULT

public static final int LAYOUT_DEFAULT
See Item.LAYOUT_DEFAULT.

Value 0 is assigned to LAYOUT_DEFAULT.


LAYOUT_LEFT

public static final int LAYOUT_LEFT
See Item.LAYOUT_LEFT.

Value 1 is assigned to LAYOUT_LEFT.


LAYOUT_RIGHT

public static final int LAYOUT_RIGHT
See Item.LAYOUT_RIGHT.

Value 2 is assigned to LAYOUT_RIGHT.


LAYOUT_CENTER

public static final int LAYOUT_CENTER
See Item.LAYOUT_CENTER.

Value 3 is assigned to LAYOUT_CENTER.


LAYOUT_NEWLINE_BEFORE

public static final int LAYOUT_NEWLINE_BEFORE
See Item.LAYOUT_NEWLINE_BEFORE.

Value 0x100 is assigned to LAYOUT_NEWLINE_BEFORE.


LAYOUT_NEWLINE_AFTER

public static final int LAYOUT_NEWLINE_AFTER
See Item.LAYOUT_NEWLINE_AFTER.

Value 0x200 is assigned to LAYOUT_NEWLINE_AFTER.

Constructor Detail

ImageItem

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);     
Parameters:
label - the label string
img - the image, can be mutable or immutable
layout - a combination of layout directives
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 Also:
ImageItem(String, Image, int, String, int)

ImageItem

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

Parameters:
label - the label string
image - the image, can be mutable or immutable
layout - a combination of layout directives
altText - the text that may be used in place of the image
appearanceMode - the appearance mode of the ImageItem, one of Item.PLAIN, Item.HYPERLINK, or Item.BUTTON
Throws:
IllegalArgumentException - if the layout value is not a legal combination of directives
IllegalArgumentException - if appearanceMode invalid
Since:
MIDP 2.0
Method Detail

getImage

public Image getImage()
Gets the image contained within the ImageItem, or null if there is no contained image.
Returns:
image used by the ImageItem
See Also:
setImage(javax.microedition.lcdui.Image)

setImage

public void setImage(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.

Parameters:
img - the Image for this ImageItem, or null if none
See Also:
getImage()

getAltText

public String getAltText()
Gets the text string to be used if the image exceeds the device's capacity to display it.
Returns:
the alternate text value, or null if none
See Also:
setAltText(java.lang.String)

setAltText

public void setAltText(String text)
Sets the alternate text of the ImageItem, or null if no alternate text is provided.
Parameters:
text - the new alternate text
See Also:
getAltText()

getLayout

public int getLayout()
Gets the layout directives used for placing the image.
Overrides:
getLayout in class Item
Returns:
a combination of layout directive values
See Also:
setLayout(int)

setLayout

public void setLayout(int layout)
Sets the layout directives.
Overrides:
setLayout in class Item
Parameters:
layout - a combination of layout directive values
Throws:
IllegalArgumentException - if the value of layout is not a valid combination of layout directives
See Also:
getLayout()

getAppearanceMode

public int getAppearanceMode()
Returns the appearance mode of the ImageItem. See Appearance Modes.
Returns:
the appearance mode value, one of Item.PLAIN, Item.HYPERLINK, or Item.BUTTON
Since:
MIDP 2.0

MID Profile

Submit a comment or suggestion Version 2.0 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.