de.enough.polish.ui
Class ImageItem

java.lang.Object
  de.enough.polish.ui.Item
      de.enough.polish.ui.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

Author:

Robert Virkus, robert@enough.de

Field Summary

Fields inherited from class de.enough.polish.ui.Item

_bbField, _bbFieldAdded, appearanceMode, background, backgroundHeight, backgroundWidth, backgroundYOffset, border, borderWidth, BUTTON, colSpan, commands, completeBackground, completeBackgroundPadding, completeBorder, contentHeight, contentWidth, contentX, contentY, cssSelector, defaultCommand, focusedStyle, HORIZONTAL, HYPERLINK, includeLabel, INTERACTIVE, internalHeight, internalWidth, internalX, internalY, isFocused, isInitialized, isInvisible, isLayoutCenter, isLayoutExpand, isLayoutRight, isPressed, isShown, isStyleInitialised, itemCommandListener, itemHeight, itemWidth, label, labelStyle, layout, LAYOUT_2, LAYOUT_BOTTOM, LAYOUT_CENTER, LAYOUT_DEFAULT, LAYOUT_EXPAND, LAYOUT_LEFT, LAYOUT_NEWLINE_AFTER, LAYOUT_NEWLINE_BEFORE, LAYOUT_RIGHT, LAYOUT_SHRINK, LAYOUT_TOP, LAYOUT_VCENTER, LAYOUT_VEXPAND, LAYOUT_VSHRINK, marginBottom, marginLeft, marginRight, marginTop, maximumHeight, maximumWidth, minimumHeight, minimumWidth, NO_POSITION_SET, opacity, opacityPaintNormally, opacityRgbData, paddingBottom, paddingHorizontal, paddingLeft, paddingRight, paddingTop, paddingVertical, parent, PLAIN, preferredHeight, preferredWidth, preserveViewType, relativeX, relativeY, rowSpan, screen, style, TRANSPARENT, useSingleRow, VERTICAL, view

Constructor Summary

ImageItem(java.lang.String label, javax.microedition.lcdui.Image image, int layout, java.lang.String altText)
Creates a new ImageItem with the given label, image, layout directive, and alternate text string.

ImageItem(java.lang.String label, javax.microedition.lcdui.Image image, int layout, java.lang.String altText, int appearanceMode)
Creates a new ImageItem object with the given label, image, layout directive, alternate text string, and appearance mode.

ImageItem(java.lang.String label, javax.microedition.lcdui.Image image, int layout, java.lang.String altText, int appearanceMode, Style style)
Creates a new ImageItem object with the given label, image, layout directive, alternate text string, and appearance mode.

ImageItem(java.lang.String label, javax.microedition.lcdui.Image image, int layout, java.lang.String altText, Style style)
Creates a new ImageItem with the given label, image, layout directive, and alternate text string.

Method Summary

protected java.lang.String	createCssSelector() Retrieves the CSS selector for this item.
java.lang.String	getAltText() Gets the text string to be used if the image exceeds the device's capacity to display it.
javax.microedition.lcdui.Image	getImage() Gets the image contained within the ImageItem, or null if there is no contained image.
protected boolean	handleKeyPressed(int keyCode, int gameAction) Handles the key-pressed event.
protected boolean	handlePointerPressed(int relX, int relY) Handles the event when a pointer has been pressed at the specified position.
protected void	initContent(int firstLineWidth, int lineWidth) Initialises this item.
void	paintContent(int x, int y, int leftBorder, int rightBorder, javax.microedition.lcdui.Graphics g) Paints the content of this item.
void	setAltText(java.lang.String text) Sets the alternate text of the ImageItem, or null if no alternate text is provided.
void	setImage(javax.microedition.lcdui.Image image) Sets the Image object contained within the ImageItem.
void	setStyle(Style style) Sets the style of this item.

Methods inherited from class de.enough.polish.ui.Item

addCommand, addCommand, addCommands, addRelativeToBackgroundRegion, addRelativeToBackgroundRegion, addRelativeToContentRegion, animate, animate, containsCommand, defocus, focus, getAbsoluteX, getAbsoluteY, getAppearanceMode, getAttribute, getAttributes, getBackgroundHeight, getBackgroundWidth, getBackgroundX, getBackgroundY, getContentHeight, getContentWidth, getContentX, getContentY, getDefaultCommand, getFocusedStyle, getItemAt, getItemCommandListener, getItemCommands, getItemHeight, getItemStateListener, getItemWidth, getLabel, getLabelItem, getLayout, getMinimumHeight, getMinimumWidth, getParent, getPreferredHeight, getPreferredWidth, getScreen, getStyle, handleCommand, handleKeyReleased, handleKeyRepeated, handlePointerReleased, hideNotify, init, initStyle, isInContentArea, isInItemArea, isInItemArea, isInitialized, isVisible, notifyItemPressedEnd, notifyItemPressedStart, notifyStateChanged, paint, paintBackground, paintBackgroundAndBorder, paintBorder, releaseResources, removeCommand, repaint, repaint, repaintFully, requestInit, setAppearanceMode, setAttribute, setDefaultCommand, setItemCommandListener, setItemCommandListener, setItemStateListener, setLabel, setLayout, setParent, setParent, setPreferredSize, setVisible, show, showCommands, showNotify, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ImageItem

public ImageItem(java.lang.String label,
                 javax.microedition.lcdui.Image image,
                 int layout,
                 java.lang.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, null );     
 

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

Throws:

java.lang.IllegalArgumentException - - if the layout value is not a legal combination of directives

See Also:

ImageItem(String, Image, int, String, int)

ImageItem

public ImageItem(java.lang.String label,
                 javax.microedition.lcdui.Image image,
                 int layout,
                 java.lang.String altText,
                 Style style)

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

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

style - the style of this image item.

Throws:

java.lang.IllegalArgumentException - - if the layout value is not a legal combination of directives

See Also:

ImageItem(String, Image, int, String, int)

ImageItem

public ImageItem(java.lang.String label,
                 javax.microedition.lcdui.Image image,
                 int layout,
                 java.lang.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:

java.lang.IllegalArgumentException - - if the layout value is not a legal combination of directives or if appearanceMode invalid

Since:

MIDP 2.0

ImageItem

public ImageItem(java.lang.String label,
                 javax.microedition.lcdui.Image image,
                 int layout,
                 java.lang.String altText,
                 int appearanceMode,
                 Style style)

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

style - the style of this image item.

Throws:

java.lang.IllegalArgumentException - - if the layout value is not a legal combination of directives or if appearanceMode invalid

Method Detail

getImage

public javax.microedition.lcdui.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(Image)

setImage

public void setImage(javax.microedition.lcdui.Image image)

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:

image - the Image for this ImageItem, or null if none

See Also:

getImage()

getAltText

public java.lang.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(java.lang.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()

paintContent

public void paintContent(int x,
                         int y,
                         int leftBorder,
                         int rightBorder,
                         javax.microedition.lcdui.Graphics g)

Description copied from class: Item

Paints the content of this item. The background has already been painted and the border will be added after this method returns.

Specified by:

paintContent in class Item

Parameters:

x - the left start position

y - the upper start position

leftBorder - the left border, nothing must be painted left of this position

rightBorder - the right border, nothing must be painted right of this position

g - the Graphics on which this item should be painted.

initContent

protected void initContent(int firstLineWidth,
                           int lineWidth)

Description copied from class: Item

Initialises this item. The implementation needs to calculate and set the contentWidth and contentHeight fields. The implementation should take the fields preferredWidth and preferredHeight into account.

Specified by:

initContent in class Item

Parameters:

firstLineWidth - the maximum width of the first line

lineWidth - the maximum width of any following lines

See Also:

Item.contentWidth, Item.contentHeight, Item.preferredWidth, Item.preferredHeight

createCssSelector

protected java.lang.String createCssSelector()

Description copied from class: Item

Retrieves the CSS selector for this item. The CSS selector is used for the dynamic assignment of styles - that is the styles are assigned by the usage of the item and not by a predefined style-name. With the #style preprocessing command styles are set fix, this method yields in a faster GUI and is recommended. When in a style-sheet dynamic styles are used, e.g. "Form>p", than the selector of the item is needed.
This abstract method needs only be implemented, when dynamic styles are used: #ifdef polish.useDynamicStyles
The returned selector needs to be in lower case.

Specified by:

createCssSelector in class Item

Returns:

the appropriate CSS selector for this item. The selector needs to be in lower case.

setStyle

public void setStyle(Style style)

Description copied from class: Item

Sets the style of this item.

Overrides:

setStyle in class Item

Parameters:

style - the new style for this item.

handleKeyPressed

protected boolean handleKeyPressed(int keyCode,
                                   int gameAction)

Description copied from class: Item

Handles the key-pressed event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation just handles the FIRE game-action when a default-command and an item-command-listener have been registered.

Overrides:

handleKeyPressed in class Item

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

handlePointerPressed

protected boolean handlePointerPressed(int relX,
                                       int relY)

Description copied from class: Item

Handles the event when a pointer has been pressed at the specified position. The default method discards this event when relX/relY is outside of the item's area. When the event took place inside of the content area, the pointer-event is translated into an artificial FIRE game-action keyPressed event, which is subsequently handled bu the handleKeyPressed(-1, Canvas.FIRE) method. This method needs should be overwritten only when the "polish.hasPointerEvents" preprocessing symbol is defined: "//#ifdef polish.hasPointerEvents".

Overrides:

handlePointerPressed in class Item

Parameters:

relX - the x position of the pointer pressing relative to this item's left position

relY - the y position of the pointer pressing relative to this item's top position

Returns:

true when the pressing of the pointer was actually handled by this item.

See Also:

this method is used for determining whether the event belongs to this item, for a helper method for determining whether the event took place into the actual content area, Item.handleKeyPressed(int, int), for calculating the horizontal position relative to the content (relX - contentX), for calculating the vertical position relative to the content (relY - contentY)