de.enough.polish.ui
Class Container

java.lang.Object
  de.enough.polish.ui.Item
      de.enough.polish.ui.Container

Direct Known Subclasses:

ChoiceGroup

public class Container
extends Item

Contains a number of items.

Main purpose is to manage all items of a Form or similiar canvases.

Containers support following additional CSS attributes:

• columns: The number of columns. If defined a table will be drawn.
• columns-width: The width of the columns. "equals" for an equal width of each column, "normal" for a column width which depends on the items. One can also specify the used widths directly with a comma separated list of integers, e.g.

                                          columns: 2;
                                          columns-width: 15,5;
                                  

• scroll-mode: Either "smooth" (=default) or "normal".

Copyright Enough Software 2004 - 2007 - 2008

 history
        01-Mar-2004 - rob creation
 

Author:

Robert Virkus, robert@enough.de

Field Summary

boolean	allowCycling specifies whether this container is allowed to cycle to the beginning when the last item has been reached
protected boolean	autoFocusEnabled
protected int	autoFocusIndex
protected int	availableHeight The height available for scrolling, ignore when set to -1
protected ContainerView	containerView
protected boolean	enableScrolling
int	focusedIndex the index of the currently focused item - please use only for reading, not for setting, unless you know what you are doing
protected Item	focusedItem
protected Style	focusedStyleFirst
protected Style	focusedStyleLast
protected boolean	isExpandItems
protected ArrayList	itemsList
protected Style	itemStyle
protected int	lastPointerPressY vertical pointer position when it was pressed the last time
protected Style	plainStyle
static int	SCROLL_DEFAULT constant for normal scrolling (0)
static int	SCROLL_SMOOTH constant for smooth scrolling (1)
protected boolean	scrollSmooth
protected int	targetYOffset
protected int	yOffset

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

Container(boolean focusFirstElement)
Creates a new empty container.

Container(boolean focusFirstElement, Style style)
Creates a new empty container.

Container(java.lang.String label, boolean focusFirstElement, Style style, int height)
Creates a new empty container.

Method Summary

void	add(int index, Item item) Inserts the given item at the defined position.
void	add(int index, javax.microedition.lcdui.Item item)
void	add(Item item) Adds an item to this container.
void	add(javax.microedition.lcdui.Item item)
void	add(Item item, Style itemAddStyle) Adds an item to this container.
void	add(java.lang.String text) Adds an StringItem with the given text to this container.
void	add(java.lang.String text, Style textAddStyle) Adds an StringItem with the given text to this container.
void	animate(long currentTime, ClippingRegion repaintRegion) Animates this item.
void	changeChildStyles(java.lang.String oldChildStyleName, java.lang.String newChildStyleName) Changes the style of all children that are currently using the specified oldChildStyle with the given newChildStyle.
void	changeChildStyles(Style oldChildStyle, Style newChildStyle) Changes the style of all children that are currently using the specified oldChildStyle with the given newChildStyle.
void	clear() Removes all items from this container.
protected java.lang.String	createCssSelector() Retrieves the CSS selector for this item.
void	defocus(Style originalStyle) Removes the focus from this item.
boolean	focus(int index) Focuses the specified item.
void	focus(int index, Item item, int direction) Sets the focus to the given item.
protected Style	focus(Style focusStyle, int direction) Focuses this item.
boolean	focusClosestItem(int index) Focuses the next focussable item starting at the specified index +/- 1.
protected boolean	focusClosestItem(int index, Item[] myItems) Focuses the next focussable item starting at the specified index +/- 1.
boolean	focusClosestItemAbove(int index) Focuses the next focussable item starting at the specified index + 1.
Item	get(int index) Returns the item at the specified position of this container.
int	getFocusedIndex() Retrieves the index of the item which is currently focused.
Item	getFocusedItem() Retrieves the currently focused item.
protected Style	getFocusedStyle(int index, Item item) Retrieves the best matching focus style for the given item
Item	getItemAt(int relX, int relY) Determines if this item or one of it's children is within the specified point.
Item[]	getItems() Retrieves all items which this container holds.
int	getNumberOfInteractiveItems() Calculates the number of interactive items included in this container.
int	getPosition(Item item) Retrieves the position of the specified item.
int	getRelativeScrollHeight() Returns the available height for scrolling eiter from this container or from it's parent container.
int	getRelativeScrollYOffset() Retrieves the vertical scrolling offset of this item relative to the top most container.
int	getScrollHeight() Returns the available height for scrolling eiter from this container or from it's parent container.
int	getScrollYOffset() Retrieves the vertical scrolling offset of this item.
protected boolean	handleCommand(javax.microedition.lcdui.Command cmd) Tries to handle the specified command.
protected boolean	handleKeyPressed(int keyCode, int gameAction) Handles the key-pressed event.
protected boolean	handleKeyReleased(int keyCode, int gameAction) Handles the key-released event.
protected boolean	handleKeyRepeated(int keyCode, int gameAction) Handles the key-repeated event.
protected boolean	handleNavigate(int keyCode, int gameAction) Handles a keyPressed or keyRepeated event for navigating in the container.
protected boolean	handlePointerPressed(int relX, int relY) Handles the event when a pointer has been pressed at the specified position.
protected boolean	handlePointerReleased(int relX, int relY) Handles the event when a pointer has been released at the specified position.
protected boolean	handlePointerScrollReleased(int relX, int relY) Allows subclasses to check if a pointer release event is used for scrolling the container.
protected void	hideNotify() Called by the system to notify the item that it is now completely invisible, when it previously had been at least partially visible.
int	indexOf(Item item) Retrieves the index of the specified item.
protected void	initContent(int firstLineWidth, int lineWidth) Initialises this item.
protected void	paintBackgroundAndBorder(int x, int y, int width, int height, javax.microedition.lcdui.Graphics g) Paints the background and border of this item.
protected void	paintContent(int x, int y, int leftBorder, int rightBorder, javax.microedition.lcdui.Graphics g) Paints the content of this item.
java.lang.String	parseIndexUrl(java.lang.String url, Item item) Parses the given URL and includes the index of the item, when there is an "%INDEX%" within the given url.
void	releaseResources() Releases all (memory intensive) resources such as images or RGB arrays of this background.
Item	remove(int index) Removes the item at the specified position of this container.
boolean	remove(Item item) Removes the given item.
void	requestDefocus(Item item) Moves the focus away from the specified item.
void	requestFullInit() Requests the initialization of this container and all of its children items.
protected boolean	scroll(int direction, int x, int y, int width, int height) Adjusts the yOffset or the targetYOffset so that the given relative values are inside of the visible area.
boolean	scroll(int direction, Item item) Scrolls this container so that the (internal) area of the given item is best seen.
Item	set(int index, Item item) Replaces the item at the specified position in this list with the given item.
Item	set(int index, Item item, Style itemStyle) Replaces the item at the specified position in this list with the given item.
void	setItemsList(ArrayList itemsList) Sets a list of items for this container.
void	setScrollHeight(int height) Sets the height available for scrolling of this item.
void	setScrollYOffset(int offset) Sets the vertical scrolling offset of this item.
void	setScrollYOffset(int offset, boolean smooth) Sets the vertical scrolling offset of this item.
void	setStyle(Style style) Sets the style of this item.
void	setStyle(Style style, boolean ignoreBackground) Sets the style of this container.
void	showCommands() Shows the commands on the screen.
protected void	showNotify() Called by the system to notify the item that it is now at least partially visible, when it previously had been completely invisible.
int	size() Retrieves the number of items stored in this container.
java.lang.String	toString() Generates a String representation of this item.

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

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

Methods inherited from class java.lang.Object

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

Field Detail

SCROLL_DEFAULT

public static final int SCROLL_DEFAULT

constant for normal scrolling (0)

See Also:

Constant Field Values

SCROLL_SMOOTH

public static final int SCROLL_SMOOTH

constant for smooth scrolling (1)

See Also:

Constant Field Values

itemsList

protected ArrayList itemsList

autoFocusEnabled

protected boolean autoFocusEnabled

autoFocusIndex

protected int autoFocusIndex

itemStyle

protected Style itemStyle

focusedItem

protected Item focusedItem

focusedIndex

public int focusedIndex

the index of the currently focused item - please use only for reading, not for setting, unless you know what you are doing

enableScrolling

protected boolean enableScrolling

allowCycling

public boolean allowCycling

specifies whether this container is allowed to cycle to the beginning when the last item has been reached

yOffset

protected int yOffset

targetYOffset

protected int targetYOffset

containerView

protected ContainerView containerView

scrollSmooth

protected boolean scrollSmooth

isExpandItems

protected boolean isExpandItems

lastPointerPressY

protected int lastPointerPressY

vertical pointer position when it was pressed the last time

focusedStyleFirst

protected Style focusedStyleFirst

focusedStyleLast

protected Style focusedStyleLast

availableHeight

protected int availableHeight

The height available for scrolling, ignore when set to -1

plainStyle

protected Style plainStyle

Constructor Detail

Container

public Container(boolean focusFirstElement)

Creates a new empty container.

Parameters:

focusFirstElement - true when the first focussable element should be focused automatically.

Container

public Container(boolean focusFirstElement,
                 Style style)

Creates a new empty container.

Parameters:

focusFirstElement - true when the first focussable element should be focused automatically.

style - the style for this container

Container

public Container(java.lang.String label,
                 boolean focusFirstElement,
                 Style style,
                 int height)

Creates a new empty container.

Parameters:

label - the label of this container

focusFirstElement - true when the first focussable element should be focused automatically.

style - the style for this container

height - the vertical space available for this container, set to -1 when scrolling should not be activated

See Also:

setScrollHeight( int )

Method Detail

setScrollHeight

public void setScrollHeight(int height)

Sets the height available for scrolling of this item.

Parameters:

height - available height for this item including label, padding, margin and border, -1 when scrolling should not be done.

getScrollHeight

public int getScrollHeight()

Returns the available height for scrolling eiter from this container or from it's parent container. Note that the height available for this container might differ from the returned value.

Returns:

the available vertical space or -1 when it is not known.

See Also:

getContentScrollHeight()

getRelativeScrollHeight

public int getRelativeScrollHeight()

Returns the available height for scrolling eiter from this container or from it's parent container.

Returns:

the available vertical space for this container or -1 when it is not known.

See Also:

getContentScrollHeight()

add

public void add(java.lang.String text)

Adds an StringItem with the given text to this container.

Parameters:

text - the text

Throws:

java.lang.IllegalArgumentException - when the given item is null

add

public void add(java.lang.String text,
                Style textAddStyle)

Adds an StringItem with the given text to this container.

Parameters:

text - the text

textAddStyle - the style for the text

Throws:

java.lang.IllegalArgumentException - when the given item is null

add

public void add(Item item)

Adds an item to this container.

Parameters:

item - the item which should be added.

Throws:

java.lang.IllegalArgumentException - when the given item is null

add

public void add(Item item,
                Style itemAddStyle)

Adds an item to this container.

Parameters:

item - the item which should be added.

itemAddStyle - the style for the item

Throws:

java.lang.IllegalArgumentException - when the given item is null

add

public void add(int index,
                Item item)

Inserts the given item at the defined position. Any following elements are shifted one position to the back.

Parameters:

index - the position at which the element should be inserted, use 0 when the element should be inserted in the front of this list.

item - the item which should be inserted

Throws:

java.lang.IllegalArgumentException - when the given item is null

java.lang.IndexOutOfBoundsException - when the index < 0 || index >= size()

add

public void add(javax.microedition.lcdui.Item item)

add

public void add(int index,
                javax.microedition.lcdui.Item item)

set

public Item set(int index,
                Item item)

Replaces the item at the specified position in this list with the given item.

Parameters:

index - the position of the element, the first element has the index 0.

item - the item which should be set

Returns:

the replaced item

Throws:

java.lang.IndexOutOfBoundsException - when the index < 0 || index >= size()

set

public Item set(int index,
                Item item,
                Style itemStyle)

Replaces the item at the specified position in this list with the given item.

Parameters:

index - the position of the element, the first element has the index 0.

item - the item which should be set

itemStyle - the new style for the item

Returns:

the replaced item

Throws:

java.lang.IndexOutOfBoundsException - when the index < 0 || index >= size()

get

public Item get(int index)

Returns the item at the specified position of this container.

Parameters:

index - the position of the desired item.

Returns:

the item stored at the given position

Throws:

java.lang.IndexOutOfBoundsException - when the index < 0 || index >= size()

remove

public Item remove(int index)

Removes the item at the specified position of this container.

Parameters:

index - the position of the desired item.

Returns:

the item stored at the given position

Throws:

java.lang.IndexOutOfBoundsException - when the index < 0 || index >= size()

focusClosestItemAbove

public boolean focusClosestItemAbove(int index)

Focuses the next focussable item starting at the specified index + 1.

Parameters:

index - the index of the item that should be used as a starting point for the search of a new possible focussable item

Returns:

true when the focus could be set, when false is returned autofocus will be enabled instead

focusClosestItem

public boolean focusClosestItem(int index)

Focuses the next focussable item starting at the specified index +/- 1.

Parameters:

index - the index of the item that should be used as a starting point for the search of a new possible focussable item

Returns:

true when the focus could be set, when false is returned autofocus will be enabled instead

focusClosestItem

protected boolean focusClosestItem(int index,
                                   Item[] myItems)

Focuses the next focussable item starting at the specified index +/- 1.

Parameters:

index - the index of the item that should be used as a starting point for the search of a new possible focussable item

myItems - the items that should be used for the search

Returns:

true when the focus could be set, when false is returned autofocus will be enabled instead

remove

public boolean remove(Item item)

Removes the given item.

Parameters:

item - the item which should be removed.

Returns:

true when the item was found in this list.

Throws:

java.lang.IllegalArgumentException - when the given item is null

clear

public void clear()

Removes all items from this container.

size

public int size()

Retrieves the number of items stored in this container.

Returns:

The number of items stored in this container.

getItems

public Item[] getItems()

Retrieves all items which this container holds. The items might not have been intialised.

Returns:

an array of all items, can be empty but not null.

focus

public boolean focus(int index)

Focuses the specified item.

Parameters:

index - the index of the item. The first item has the index 0, when -1 is given, the focus will be removed altogether

Returns:

true when the specified item could be focused. It needs to have an appearanceMode which is not Item.PLAIN to be focusable.

focus

public void focus(int index,
                  Item item,
                  int direction)

Sets the focus to the given item.

Parameters:

index - the position

item - the item which should be focused

direction - the direction, either Canvas.DOWN, Canvas.RIGHT, Canvas.UP, Canvas.LEFT or 0.

getFocusedStyle

protected Style getFocusedStyle(int index,
                                Item item)

Retrieves the best matching focus style for the given item

Parameters:

index - the index of the item

item - the item

Returns:

the matching focus style

scroll

public boolean scroll(int direction,
                      Item item)

Scrolls this container so that the (internal) area of the given item is best seen. This is used when a GUI even has been consumed by the currently focused item. The call is fowarded to scroll( direction, x, y, w, h ).

Parameters:

direction - the direction, is used for adjusting the scrolling when the internal area is to large. Either 0 or Canvas.UP, Canvas.DOWN, Canvas.LEFT or Canvas.RIGHT

item - the item for which the scrolling should be adjusted

Returns:

true when the container was scrolled

scroll

protected boolean scroll(int direction,
                         int x,
                         int y,
                         int width,
                         int height)

Adjusts the yOffset or the targetYOffset so that the given relative values are inside of the visible area. The call is forwarded to a parent container when scrolling is not enabled for this item.

Parameters:

direction - the direction, is used for adjusting the scrolling when the internal area is to large. Either 0 or Canvas.UP, Canvas.DOWN, Canvas.LEFT or Canvas.RIGHT

x - the horizontal position of the area relative to this content's left edge, is ignored in the current version

y - the vertical position of the area relative to this content's top edge

width - the width of the area

height - the height of the area

Returns:

true when the scroll request changed the internal scroll offsets

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

paintContent

protected 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.

paintBackgroundAndBorder

protected void paintBackgroundAndBorder(int x,
                                        int y,
                                        int width,
                                        int height,
                                        javax.microedition.lcdui.Graphics g)

Description copied from class: Item

Paints the background and border of this item. The call is forwarded to paintBackground() and paintBorder().

Overrides:

paintBackgroundAndBorder in class Item

Parameters:

x - the horizontal start position

y - the vertical start position

width - the width

height - the height

g - graphics context

See Also:

Item.paintBackground(int, int, int, int, Graphics), Item.paintBorder(int, int, int, int, Graphics)

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.

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

handleNavigate

protected boolean handleNavigate(int keyCode,
                                 int gameAction)

Handles a keyPressed or keyRepeated event for navigating in the container.

Parameters:

keyCode - the code of the keypress/keyrepeat event

gameAction - the associated game action

Returns:

true when the key was handled

handleKeyReleased

protected boolean handleKeyReleased(int keyCode,
                                    int gameAction)

Description copied from class: Item

Handles the key-released event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation invokes the default command if one is present

Overrides:

handleKeyReleased 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

See Also:

Item.handleKeyPressed(int, int)

handleKeyRepeated

protected boolean handleKeyRepeated(int keyCode,
                                    int gameAction)

Description copied from class: Item

Handles the key-repeated event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation forwards the event to the handleKeyPressed method.

Overrides:

handleKeyRepeated 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

See Also:

Item.handleKeyPressed(int, int)

getFocusedIndex

public int getFocusedIndex()

Retrieves the index of the item which is currently focused.

Returns:

the index of the focused item, -1 when none is focused.

getFocusedItem

public Item getFocusedItem()

Retrieves the currently focused item.

Returns:

the currently focused item, null when there is no focusable item in this container.

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.

setStyle

public void setStyle(Style style,
                     boolean ignoreBackground)

Sets the style of this container.

Parameters:

style - the style

ignoreBackground - when true is given, the background and border-settings will be ignored.

changeChildStyles

public void changeChildStyles(java.lang.String oldChildStyleName,
                              java.lang.String newChildStyleName)

Changes the style of all children that are currently using the specified oldChildStyle with the given newChildStyle.

Parameters:

oldChildStyleName - the name of the style of child items that should be exchanged

newChildStyleName - the name of the new style for child items that were using the specified oldChildStyle before

Throws:

java.lang.IllegalArgumentException - if no corresponding newChildStyle could be found

See Also:

StyleSheet.getStyle(String)

changeChildStyles

public void changeChildStyles(Style oldChildStyle,
                              Style newChildStyle)

Changes the style of all children that are currently using the specified oldChildStyle with the given newChildStyle.

Parameters:

oldChildStyle - the style of child items that should be exchanged

newChildStyle - the new style for child items that were using the specified oldChildStyle before

Throws:

java.lang.IllegalArgumentException - if newChildStyle is null

parseIndexUrl

public java.lang.String parseIndexUrl(java.lang.String url,
                                      Item item)

Parses the given URL and includes the index of the item, when there is an "%INDEX%" within the given url.

Parameters:

url - the resource URL which might include the substring "%INDEX%"

item - the item to which the URL belongs to. The item must be included in this container.

Returns:

the URL in which the %INDEX% is substituted by the index of the item in this container. The url "icon%INDEX%.png" is resolved to "icon1.png" when the item is the second item in this container.

Throws:

java.lang.NullPointerException - when the given url or item is null

getPosition

public int getPosition(Item item)

Retrieves the position of the specified item.

Parameters:

item - the item

Returns:

the position of the item, or -1 when it is not defined

focus

protected Style focus(Style focusStyle,
                      int direction)

Description copied from class: Item

Focuses this item.

Overrides:

focus in class Item

Parameters:

focusStyle - the style which is used to indicate the focused state

direction - the direction from which this item is focused, either Canvas.UP, Canvas.DOWN, Canvas.LEFT, Canvas.RIGHT or 0. When 0 is given, the direction is unknown.

Returns:

the current style of this item

defocus

public void defocus(Style originalStyle)

Description copied from class: Item

Removes the focus from this item.

Overrides:

defocus in class Item

Parameters:

originalStyle - the original style which will be restored.

showCommands

public void showCommands()

Description copied from class: Item

Shows the commands on the screen.

Overrides:

showCommands in class Item

handleCommand

protected boolean handleCommand(javax.microedition.lcdui.Command cmd)

Description copied from class: Item

Tries to handle the specified command. The item checks if the command belongs to this item and if it has an associated ItemCommandListener. Only then it handles the command.

Overrides:

handleCommand in class Item

Parameters:

cmd - the command

Returns:

true when the command has been handled by this item

animate

public void animate(long currentTime,
                    ClippingRegion repaintRegion)

Description copied from class: Item

Animates this item. Subclasses can override this method to create animations. The default implementation animates the background and the item view if present.

Overrides:

animate in class Item

Parameters:

currentTime - the current time in milliseconds

repaintRegion - the repaint area that needs to be updated when this item is animated

See Also:

Item.addRelativeToContentRegion(ClippingRegion, int, int, int, int)

showNotify

protected void showNotify()

Called by the system to notify the item that it is now at least partially visible, when it previously had been completely invisible. The item may receive paint() calls after showNotify() has been called.

The container implementation calls showNotify() on the embedded items.

Overrides:

showNotify in class Item

hideNotify

protected void hideNotify()

Called by the system to notify the item that it is now completely invisible, when it previously had been at least partially visible. No further paint() calls will be made on this item until after a showNotify() has been called again.

The container implementation calls hideNotify() on the embedded items.

Overrides:

hideNotify in class Item

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)

handlePointerScrollReleased

protected boolean handlePointerScrollReleased(int relX,
                                              int relY)

Allows subclasses to check if a pointer release event is used for scrolling the container. This method can only be called when polish.hasPointerEvents is true.

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

handlePointerReleased

protected boolean handlePointerReleased(int relX,
                                        int relY)

Description copied from class: Item

Handles the event when a pointer has been released 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 keyReleased 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:

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

getItemAt

public Item getItemAt(int relX,
                      int relY)

Description copied from class: Item

Determines if this item or one of it's children is within the specified point. The default implementation returns this item or this item's label when the position fits.

Overrides:

getItemAt in class Item

Parameters:

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

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

Returns:

this item or one of it's children, when the position fits, otherwise null is returned

requestDefocus

public void requestDefocus(Item item)

Moves the focus away from the specified item.

Parameters:

item - the item that currently has the focus

requestFullInit

public void requestFullInit()

Requests the initialization of this container and all of its children items.

getScrollYOffset

public int getScrollYOffset()

Retrieves the vertical scrolling offset of this item.

Returns:

either the currently used offset or the targeted offset in case the targeted one is different.

getRelativeScrollYOffset

public int getRelativeScrollYOffset()

Retrieves the vertical scrolling offset of this item relative to the top most container.

Returns:

either the currently used offset or the targeted offset in case the targeted one is different.

setScrollYOffset

public void setScrollYOffset(int offset)

Sets the vertical scrolling offset of this item.

Parameters:

offset - either the new offset

setScrollYOffset

public void setScrollYOffset(int offset,
                             boolean smooth)

Sets the vertical scrolling offset of this item.

Parameters:

offset - either the new offset

smooth - scroll to this new offset smooth if allowed

indexOf

public int indexOf(Item item)

Retrieves the index of the specified item.

Parameters:

item - the item

Returns:

the index of the item; -1 when the item is not part of this container

toString

public java.lang.String toString()

Generates a String representation of this item. This method is only implemented when the logging framework is active or the preprocessing variable "polish.keepToString" is set to true.

Overrides:

toString in class Item

Returns:

a String representation of this item.

setItemsList

public void setItemsList(ArrayList itemsList)

Sets a list of items for this container. Use this direct access only when you know what you are doing.

Parameters:

itemsList - the list of items to set

getNumberOfInteractiveItems

public int getNumberOfInteractiveItems()

Calculates the number of interactive items included in this container.

Returns:

the number between 0 and size()

releaseResources

public void releaseResources()

Releases all (memory intensive) resources such as images or RGB arrays of this background.

Overrides:

releaseResources in class Item