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.

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 Use the default formatting of the "container" of the image.
static int	LAYOUT_LEFT See Item.LAYOUT_DEFAULT.
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.
String	getLabel() Gets the label of this Item object.
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, getLayout, 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.

See Also:

Constant Field Values

LAYOUT_LEFT

public static final int LAYOUT_LEFT

See Item.LAYOUT_DEFAULT.

Value 1 is assigned to LAYOUT_LEFT.

See Also:

Constant Field Values

LAYOUT_RIGHT

public static final int LAYOUT_RIGHT

See Item.LAYOUT_RIGHT.

Value 2 is assigned to LAYOUT_RIGHT.

See Also:

Constant Field Values

LAYOUT_CENTER

public static final int LAYOUT_CENTER

See Item.LAYOUT_CENTER.

Value 3 is assigned to LAYOUT_CENTER.

See Also:

Constant Field Values

LAYOUT_NEWLINE_BEFORE

public static final int LAYOUT_NEWLINE_BEFORE

See Item.LAYOUT_NEWLINE_BEFORE.

Value 0x100 is assigned to LAYOUT_NEWLINE_BEFORE.

See Also:

Constant Field Values

LAYOUT_NEWLINE_AFTER

public static final int LAYOUT_NEWLINE_AFTER

See Item.LAYOUT_NEWLINE_AFTER.

Value 0x200 is assigned to LAYOUT_NEWLINE_AFTER.

See Also:

Constant Field Values

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, 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:

BlackBerry API 4.0.0, 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 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 new image

Throws:

IllegalArgumentException - if the image is mutable

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

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

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:

Item.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:

BlackBerry API 4.0.0, MIDP 2.0