de.enough.polish.ui
Class ContainerView

java.lang.Object
  de.enough.polish.ui.ItemView
      de.enough.polish.ui.ContainerView

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AnimationContainerView, CenterNavigationContainerView, CoverFlowContainerView, DroppingView, ExclusiveSingleLineView, FishEyeContainerView, HorizontalChoiceView, HorizontalContainerView, HorizontalGrayOutContainerView, MIDP2LayoutView, NumberedContainerView, RelativeLayoutView, RemoveTextContainerView, ShuffleView, SlideContainerView, SpringContainerView, VerticalFixedContainerView

public class ContainerView
extends ItemView

Is responsible for visual representation and interpretation of user-input.

Copyright Enough Software 2004 - 2007 - 2008

 history
        Oct 27, 2004 - rob creation
 

Author:

Robert Virkus, robert@enough.de

Field Summary

protected boolean	allowCycling
protected boolean	allowsAutoTraversal indicates whether the parent Container is allowed to change the currently focused item when the user traverses around a form and enters the container from different sides
protected boolean	allowsDirectSelectionByPointerEvent indicates whether elements in this container view can be selected directly by pointer events
protected int	appearanceMode
protected int	columnsSetting
protected int[]	columnsWidths
protected static int	EQUAL_WIDTH_COLUMNS
protected int	focusedIndex
protected Item	focusedItem
protected boolean	focusFirstElement
protected boolean	isExpandItems
protected boolean	isHorizontal
protected boolean	isSequentialTraversal
protected boolean	isVertical
protected int	leftXOffset
protected static int	NO_COLUMNS
protected static int	NORMAL_WIDTH_COLUMNS
protected int	numberOfColumns
protected int	numberOfRows
protected Container	parentContainer this field is set automatically, so that subclasses can use it for referencing the parent-container
protected boolean	restartAnimation determines whether any animation of this view should be (re) started at the next possibility.
protected int	rightXOffset
protected int[]	rowsHeights
protected static int	STATIC_WIDTH_COLUMNS
protected int	topYOffset
protected int	yOffset

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

contentHeight, contentWidth, isFocused, isLayoutCenter, isLayoutRight, layout, paddingHorizontal, paddingVertical, parentItem

Constructor Summary

protected

ContainerView() Creates a new view

Method Summary

protected void	focusItem(int index, Item item) Focuses the item with the given index.
protected void	focusItem(int index, Item item, int direction) Focuses the item with the given index.
Style	focusItem(int index, Item item, int direction, Style focusedStyle) Focuses the given item and retrieves the previous style of that item.
protected int	getItemRelativeY(Item item)
protected Item	getNextFocusableItem(Item[] items, boolean forward, int steps, boolean allowCircle) Retrieves the next focusable item.
protected Item	getNextItem(int keyCode, int gameAction) Interpretes the given user-input and retrieves the nexte item which should be focused.
protected int	getParentRelativeY()
protected Screen	getScreen() Retrieves the screen to which this view belongs to.
boolean	handleKeyPressed(int keyCode, int gameAction) Handles the given keyPressed event when the currently focused item was not able to handle it.
protected void	initContent(Item parentContainerItem, int firstLineWidth, int lineWidth) Initialises this item.
protected boolean	isInBottomRow(int index) Detects if the specified item index is within the last row of this view.
protected boolean	isLayoutExpand() Determines whether this view should be expanded horizontally
protected boolean	isValid(Item parent, Style style) Implementation that are valid only for specific item classes can override this method so that they cannot be accidently attached to unsupported classes.
protected void	paintContent(Container container, Item[] myItems, int x, int y, int leftBorder, int rightBorder, int clipX, int clipY, int clipWidth, int clipHeight, javax.microedition.lcdui.Graphics g) Paints the content of this container view.
protected void	paintContent(Item parent, int x, int y, int leftBorder, int rightBorder, javax.microedition.lcdui.Graphics g) Paints the content of this container view.
protected void	paintItem(Item item, int index, int x, int y, int leftBorder, int rightBorder, int clipX, int clipY, int clipWidth, int clipHeight, javax.microedition.lcdui.Graphics g) Paints this item at the specified position.
protected void	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.
protected void	setStyle(Style style) Sets the style for this view.
protected Item	shiftFocus(boolean forwardFocus, int steps, Item[] items) Shifts the focus to the next or the previous item.
void	showNotify() Notifies this view that it is about to be shown (again).

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

addFullRepaintRegion, animate, animate, defocus, focus, handleKeyReleased, handlePointerPressed, handlePointerReleased, hideNotify, initContentByParent, notifyItemPressedEnd, notifyItemPressedStart, paintBackground, paintBorder, paintContentByParent, releaseResources, removeItemBackground, removeItemBorder, removeParentBackground, removeParentBorder, removeViewFromParent, requestInit

Methods inherited from class java.lang.Object

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

Field Detail

NO_COLUMNS

protected static final int NO_COLUMNS

See Also:

Constant Field Values

EQUAL_WIDTH_COLUMNS

protected static final int EQUAL_WIDTH_COLUMNS

See Also:

Constant Field Values

NORMAL_WIDTH_COLUMNS

protected static final int NORMAL_WIDTH_COLUMNS

See Also:

Constant Field Values

STATIC_WIDTH_COLUMNS

protected static final int STATIC_WIDTH_COLUMNS

See Also:

Constant Field Values

yOffset

protected int yOffset

focusedIndex

protected int focusedIndex

parentContainer

protected transient Container parentContainer

this field is set automatically, so that subclasses can use it for referencing the parent-container

restartAnimation

protected boolean restartAnimation

determines whether any animation of this view should be (re) started at the next possibility. this is set to "true" in each showNotify() method.

focusFirstElement

protected boolean focusFirstElement

appearanceMode

protected int appearanceMode

focusedItem

protected transient Item focusedItem

columnsSetting

protected int columnsSetting

numberOfColumns

protected int numberOfColumns

columnsWidths

protected int[] columnsWidths

rowsHeights

protected int[] rowsHeights

numberOfRows

protected int numberOfRows

allowCycling

protected boolean allowCycling

leftXOffset

protected int leftXOffset

rightXOffset

protected int rightXOffset

topYOffset

protected int topYOffset

isSequentialTraversal

protected boolean isSequentialTraversal

isExpandItems

protected boolean isExpandItems

allowsAutoTraversal

protected boolean allowsAutoTraversal

indicates whether the parent Container is allowed to change the currently focused item when the user traverses around a form and enters the container from different sides

isHorizontal

protected boolean isHorizontal

isVertical

protected boolean isVertical

allowsDirectSelectionByPointerEvent

protected boolean allowsDirectSelectionByPointerEvent

indicates whether elements in this container view can be selected directly by pointer events

Constructor Detail

ContainerView

protected ContainerView()

Creates a new view

Method Detail

initContent

protected void initContent(Item parentContainerItem,
                           int firstLineWidth,
                           int lineWidth)

Initialises this item. The implementation needs to calculate and set the contentWidth and contentHeight fields. The style of the focused item has already been set.

Specified by:

initContent in class ItemView

Parameters:

parentContainerItem - the Container which uses this view, use parent.getItems() for retrieving all items.

firstLineWidth - the maximum width of the first line

lineWidth - the maximum width of any following lines

See Also:

ItemView.contentWidth, ItemView.contentHeight

isLayoutExpand

protected boolean isLayoutExpand()

Determines whether this view should be expanded horizontally

Returns:

true when this view should be expanded horizontally

See Also:

ItemView.layout, Item.LAYOUT_EXPAND

paintContent

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

Paints the content of this container view. This method adjusts the x and y offsets and forwards the call to paintContent(Container, Item[], int, int, int, int, int, int, int, int, Graphics)

Specified by:

paintContent in class ItemView

Parameters:

parent - the parent item

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.

See Also:

paintContent(Container, Item[], int, int, int, int, int, int, int, int, Graphics)

paintContent

protected void paintContent(Container container,
                            Item[] myItems,
                            int x,
                            int y,
                            int leftBorder,
                            int rightBorder,
                            int clipX,
                            int clipY,
                            int clipWidth,
                            int clipHeight,
                            javax.microedition.lcdui.Graphics g)

Paints the content of this container view. This method calls

Parameters:

container - the parent container

myItems - the items that should be painted

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

clipX - absolute horizontal clipping start

clipY - absolute verical clipping start

clipWidth - clipping width

clipHeight - clipping height

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

paintItem

protected void paintItem(Item item,
                         int index,
                         int x,
                         int y,
                         int leftBorder,
                         int rightBorder,
                         int clipX,
                         int clipY,
                         int clipWidth,
                         int clipHeight,
                         javax.microedition.lcdui.Graphics g)

Paints this item at the specified position. Subclasses can override this method for taking advantage of the table support of the basic ContainerView class. When the item is outside of the given clipping area, it will not be painted.

Parameters:

item - the item that needs to be painted

index - the index of the item

x - the horizontal position of the item

y - the vertical position of the item

leftBorder - the left border

rightBorder - the right border

clipX - absolute horizontal clipping start

clipY - absolute verical clipping start

clipWidth - clipping width

clipHeight - clipping height

g - the graphics context

getNextItem

protected Item getNextItem(int keyCode,
                           int gameAction)

Interpretes the given user-input and retrieves the nexte item which should be focused. Please not that the focusItem()-method is not called as well. The view is responsible for updating its internal configuration here as well.

Parameters:

keyCode - the code of the keyPressed-events

gameAction - the associated game-action to the given keyCode

Returns:

the next item which will be focused, null when there is no such element.

shiftFocus

protected Item shiftFocus(boolean forwardFocus,
                          int steps,
                          Item[] items)

Shifts the focus to the next or the previous item.

Parameters:

forwardFocus - true when the next item should be focused, false when the previous item should be focused.

steps - how many steps forward or backward the search for the next focusable item should be started, 0 for the current item, negative values go backwards.

items - the items of this view

Returns:

the item that has been focused or null, when no item has been focused.

isInBottomRow

protected boolean isInBottomRow(int index)

Detects if the specified item index is within the last row of this view.

Parameters:

index - the item's index

Returns:

true when the item is in the last row of this view. When no columns are used, this will be only true for the last item.

focusItem

protected void focusItem(int index,
                         Item item)

Focuses the item with the given index. The container will then set the style of the retrieved item. The default implementation just sets the internal focusedIndex field along with focusedItem. When this method is overwritten, please do call super.focusItem first or set the fields "focusedIndex" and "focusedItem" yourself. This method figures out the direction and calls focusItem( index, item, direction )

Parameters:

index - the index of the item

item - the item which should be focused

See Also:

focusItem(int, Item, int)

focusItem

protected void focusItem(int index,
                         Item item,
                         int direction)

Focuses the item with the given index. The container will then set the style of the retrieved item. The default implementation just sets the internal focusedIndex field along with focusedItem. When this method is overwritten, please do call super.focusItem first or set the fields "focusedIndex" and "focusedItem" yourself.

Parameters:

index - the index of the item

item - the item which should be focused

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

setStyle

protected void setStyle(Style style)

Sets the style for this view. The style can include additional parameters for the view. Subclasses should call super.setStyle(style) first.

Overrides:

setStyle in class ItemView

Parameters:

style - the style

getNextFocusableItem

protected Item getNextFocusableItem(Item[] items,
                                    boolean forward,
                                    int steps,
                                    boolean allowCircle)

Retrieves the next focusable item. This helper method can be called by view-implementations. The index of the currently focused item can be retrieved with the focusedIndex-field.

Parameters:

items - the available items

forward - true when a following item should be looked for, false if a previous item should be looked for.

steps - the number of steps which should be used (e.g. 2 in a table with two columns)

allowCircle - true when either the first focusable or the last focusable element should be returned when there is no focusable item in the given direction.

Returns:

either the next focusable item or null when there is no such element

See Also:

focusItem(int, Item)

showNotify

public void showNotify()

Notifies this view that it is about to be shown (again). The default implementation just sets the restartAnimation-field to true.

Overrides:

showNotify in class ItemView

getScreen

protected Screen getScreen()

Retrieves the screen to which this view belongs to. This is necessary since the getScreen()-method of item has only protected access. The screen can be useful for setting the title for example.

Overrides:

getScreen in class ItemView

Returns:

the screen in which this view is embedded.

handleKeyPressed

public boolean handleKeyPressed(int keyCode,
                                int gameAction)

Handles the given keyPressed event when the currently focused item was not able to handle it. The default implementation just calls getNextItem() and focuses the returned item.

Overrides:

handleKeyPressed in class ItemView

Parameters:

keyCode - the key code

gameAction - the game action like Canvas.UP etc

Returns:

true when the key was handled.

scroll

protected void 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 ignored 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

getParentRelativeY

protected int getParentRelativeY()

getItemRelativeY

protected int getItemRelativeY(Item item)

isValid

protected boolean isValid(Item parent,
                          Style style)

Description copied from class: ItemView

Implementation that are valid only for specific item classes can override this method so that they cannot be accidently attached to unsupported classes. This allows casting without checking the parent item with instanceof in each method, for example. The default implementation just returns true for any case.

Overrides:

isValid in class ItemView

Parameters:

parent - the parent item

style - the style

Returns:

true when the view can be used for the parent item.

focusItem

public Style focusItem(int index,
                       Item item,
                       int direction,
                       Style focusedStyle)

Focuses the given item and retrieves the previous style of that item. The default implementation sets the focusedIndex and focusedItem fields and returns the result of item.focus( focusStyle, direction ). This is a method that is usually called from within the parent Container (in contrast to the other focusItem() methods which forward the call to the parentContainer).

Parameters:

index - the index of the item

item - the item which should be focused

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

focusedStyle - the new style for the focused item

Returns:

the previous style of the focussed item