javax.microedition.lcdui
Class ImageItem

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

public class ImageItem
extends Item

A class that provides layout control when Image objects are added to a Form or to an Alert.

Each ImageItem object contains a reference to an Image object. This image must be immutable. (If the image object were not required to be immutable, the application could paint into it at any time, potentially requiring the containing Form or Alert to be updated on every graphics call.) See the definition of the Image object for further details on image mutability how to create immutable images.

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.

Each ImageItem object contains a layout field that is combined from the following values: LAYOUT_LEFT, LAYOUT_RIGHT, LAYOUT_CENTER, LAYOUT_NEWLINE_BEFORE, and LAYOUT_NEWLINE_AFTER. LAYOUT_LEFT + LAYOUT_RIGHT is equal to LAYOUT_CENTER. LAYOUT_DEFAULT may be specified, which indicates that the system should use its default layout policy for this ImageItem. The value of the layout field is merely a hint. Because of device constraints, such as limited screen size, the implementation may choose to ignore layout directions.

There are some implicit rules on how the layout directives can be combined:

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.


Field Summary
static int LAYOUT_CENTER
          Image should be horizontally centered.
static int LAYOUT_DEFAULT
          Use the default formatting of the "container" of the image.
static int LAYOUT_LEFT
          Image should be close to left-edge of the drawing area.
static int LAYOUT_NEWLINE_AFTER
          A new line should be started after the image is drawn.
static int LAYOUT_NEWLINE_BEFORE
          A new line should be started before the image is drawn.
static int LAYOUT_RIGHT
          Image should be close to right-edge of the drawing area.
 
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.
 String getLabel()
          Gets the label of this Item object.
 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 setLabel(String label)
          Sets the label of the Item.
 void setLayout(int layout)
          Sets the layout directives.
 
Methods inherited from class javax.microedition.lcdui.Item
addCommand, getMinimumHeight, getMinimumWidth, getPreferredHeight, getPreferredWidth, notifyStateChanged, removeCommand, setDefaultCommand, setItemCommandListener, 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

Use the default formatting of the "container" of the image.

Value 0 is assigned to LAYOUT_DEFAULT.


LAYOUT_LEFT

public static final int LAYOUT_LEFT

Image should be close to left-edge of the drawing area.

Value 1 is assigned to LAYOUT_LEFT.


LAYOUT_RIGHT

public static final int LAYOUT_RIGHT
Image should be close to right-edge of the drawing area.

Value 2 is assigned to LAYOUT_RIGHT.


LAYOUT_CENTER

public static final int LAYOUT_CENTER
Image should be horizontally centered.

Value 3 is assigned to LAYOUT_CENTER.


LAYOUT_NEWLINE_BEFORE

public static final int LAYOUT_NEWLINE_BEFORE
A new line should be started before the image is drawn.

Value 0x100 is assigned to LAYOUT_NEWLINE_BEFORE.


LAYOUT_NEWLINE_AFTER

public static final int LAYOUT_NEWLINE_AFTER
A new line should be started after the image is drawn.

Value 0x200 is assigned to LAYOUT_DEFAULT.

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.
Parameters:
label - the label string
img - the image, must be immutable
layout - a combination of layout directives
altText - the text that may be used in place of the image
Throws:
IllegalArgumentException - if the image is mutable
IllegalArgumentException - if the layout value is not a legal combination of directives

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

setImage

public void setImage(Image img)
Sets the image object contained within the ImageItem. The image must be immutable. If img is null, the ImageItem is set to be empty.
Parameters:
img - the new image
Throws:
IllegalArgumentException - if the image is mutable
Since:
JDE 4.0.2

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
Since:
JDE 4.0.2

getLabel

public String getLabel()
Description copied from class: Item
Gets the label of this Item object.
Overrides:
getLabel in class Item
Following copied from class: javax.microedition.lcdui.Item
Returns:
the label string

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

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
Since:
JDE 4.0.2

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

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
Since:
JDE 4.0.2

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


Copyright 1999-2004 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.