de.enough.polish.ui
Class ItemView

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

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

BinaryTextClockView, ContainerView, CyclingIconsGaugeView, CyclingSpheresGaugeView, ExplodingParticlesItemView, FadeInItemView, FadeOutItemView, HorizontalIconsGaugeView, HorizontalSpheresGaugeView, PieChartView, RecLineGaugeView, RotatingArcsGaugeView, SizeDecreaseItemView, SizeIncreaseItemView, TachometerGaugeView, VerticalBarChartView

public abstract class ItemView
extends java.lang.Object
implements Serializable

An item view can take over the rendering of an item.

Copyright Enough Software 2006 - 2008

 history
        Nov 27, 2006 - rob creation
 

Author:

Robert Virkus, j2mepolish@enough.de

Field Summary

protected int	contentHeight
protected int	contentWidth
protected boolean	isFocused
protected boolean	isLayoutCenter
protected boolean	isLayoutRight
protected int	layout
protected int	paddingHorizontal
protected int	paddingVertical
protected Item	parentItem

Constructor Summary

ItemView()

Method Summary

protected void	addFullRepaintRegion(Item item, ClippingRegion repaintRegion) Adds the complete item's dimensions to the repaint region.
boolean	animate() Animates this view - please use animate(long, ClippingRegion) instead, if possible
void	animate(long currentTime, ClippingRegion repaintRegion) Animates this item.
protected void	defocus(Style originalStyle) Notifies this view that the parent container is not focused anymore.
void	focus(Style focusstyle, int direction) Sets the focus to this container view.
protected Screen	getScreen() Retrieves the screen to which this view belongs to.
boolean	handleKeyPressed(int keyCode, int gameAction) Handles the given keyPressed event.
boolean	handleKeyReleased(int keyCode, int gameAction) Handles the given keyReleased event when the currently focused item was not able to handle it.
boolean	handlePointerPressed(int x, int y) Handles pointer pressed events.
protected boolean	handlePointerReleased(int x, int y) Handles the event when a pointer has been released at the specified position.
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.
protected abstract void	initContent(Item parent, int firstLineWidth, int lineWidth) Initialises this item view.
protected void	initContentByParent(Item parent, int firstLineWidth, int lineWidth) Calls the original initContent method on the parent.
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	notifyItemPressedEnd() Is called when pressing an item is finished, usually when the FIRE key is released The default implementation fowards this to the parent item.
protected boolean	notifyItemPressedStart() Is called when an item is pressed using the FIRE game action.
void	paintBackground(Background background, int x, int y, int width, int height, javax.microedition.lcdui.Graphics g)
void	paintBorder(Border border, int x, int y, int width, int height, javax.microedition.lcdui.Graphics g)
protected abstract void	paintContent(Item parent, int x, int y, int leftBorder, int rightBorder, javax.microedition.lcdui.Graphics g) Paints this item view.
protected void	paintContentByParent(Item parent, int x, int y, int leftBorder, int rightBorder, javax.microedition.lcdui.Graphics g) Paints this item view by the parent.
void	releaseResources() Releases all resources that are not required to keep the state of this view.
protected Background	removeItemBackground(Item item) Removes the set background from an item.
protected Border	removeItemBorder(Item item) Removes the set border from an item.
Background	removeParentBackground() Removes the background from the parent container so that the view implementation can paint it itself.
Border	removeParentBorder() Removes the border from the parent container so that the view implementation can paint it itself.
protected void	removeViewFromParent() Removes this view from the parent item.
void	requestInit() Requests the re-initialization of this item view.
protected void	setStyle(Style style) Sets the style for this view.
void	showNotify() Notifies this view that it is about to be shown (again).

Methods inherited from class java.lang.Object

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

Field Detail

contentWidth

protected int contentWidth

contentHeight

protected int contentHeight

paddingVertical

protected int paddingVertical

paddingHorizontal

protected int paddingHorizontal

layout

protected int layout

isLayoutCenter

protected boolean isLayoutCenter

isLayoutRight

protected boolean isLayoutRight

parentItem

protected transient Item parentItem

isFocused

protected boolean isFocused

Constructor Detail

ItemView

public ItemView()

Method Detail

initContent

protected abstract void initContent(Item parent,
                                    int firstLineWidth,
                                    int lineWidth)

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

Parameters:

parent - the parent item

firstLineWidth - the maximum width of the first line

lineWidth - the maximum width of any following lines

See Also:

contentWidth, contentHeight

paintContent

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

Paints this item view.

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.

initContentByParent

protected void initContentByParent(Item parent,
                                   int firstLineWidth,
                                   int lineWidth)

Calls the original initContent method on the parent. This is only useful when the parent should later onward paint (parts) of the item's interface. contentWidth and contentHeight fields are set according to the parent results.

Parameters:

parent - the parent item

firstLineWidth - the maximum width of the first line

lineWidth - the maximum width of any following lines

paintContentByParent

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

Paints this item view by the parent. This could make sense if a specific view is only useful for a special case of the parent item.

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.

focus

public void focus(Style focusstyle,
                  int direction)

Sets the focus to this container view. The default implementation sets the style and the field "isFocused" to true.

Parameters:

focusstyle - the appropriate style.

direction - the direction from the which the focus is gained, either Canvas.UP, Canvas.DOWN, Canvas.LEFT, Canvas.RIGHT or 0. When 0 is given, the direction is unknown.1

defocus

protected void defocus(Style originalStyle)

Notifies this view that the parent container is not focused anymore. Please call super.defocus() when overriding this method. The default implementation calls setStyle( originalStyle ) and sets the field "isFocused" to false.

Parameters:

originalStyle - the previous used style, may be null.

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.

Parameters:

style - the style

requestInit

public void requestInit()

Requests the re-initialization of this item view. This should be called when this view type changes its size.

removeParentBackground

public Background removeParentBackground()

Removes the background from the parent container so that the view implementation can paint it itself.

Returns:

the background of the parent, can be null

removeParentBorder

public Border removeParentBorder()

Removes the border from the parent container so that the view implementation can paint it itself.

Returns:

the border of the parent, can be null

removeItemBorder

protected Border removeItemBorder(Item item)

Removes the set border from an item.

Parameters:

item - the item to remove the border from

Returns:

the formerly set border

removeItemBackground

protected Background removeItemBackground(Item item)

Removes the set background from an item.

Parameters:

item - the item to remove the background from

Returns:

the formerly set background

animate

public void animate(long currentTime,
                    ClippingRegion repaintRegion)

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

Parameters:

currentTime - the current time in milliseconds

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

See Also:

Item.getAbsoluteX(), Item.getAbsoluteY()

addFullRepaintRegion

protected void addFullRepaintRegion(Item item,
                                    ClippingRegion repaintRegion)

Adds the complete item's dimensions to the repaint region. This is usually used within the animate method.

Parameters:

item - the item

repaintRegion - the region to which the item's positions are added

animate

public boolean animate()

Animates this view - please use animate(long, ClippingRegion) instead, if possible

Returns:

true when the view was actually animated.

See Also:

animate(long, ClippingRegion)

showNotify

public void showNotify()

Notifies this view that it is about to be shown (again). The default implementation does nothing.

hideNotify

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

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.

Returns:

the screen in which this view is embedded.

handleKeyPressed

public boolean handleKeyPressed(int keyCode,
                                int gameAction)

Handles the given keyPressed event. The default implementation just calls getNextItem() and focuses the returned item.

Parameters:

keyCode - the key code

gameAction - the game action like Canvas.UP etc

Returns:

true when the key was handled.

handleKeyReleased

public boolean handleKeyReleased(int keyCode,
                                 int gameAction)

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

Parameters:

keyCode - the key code

gameAction - the game action like Canvas.UP etc

Returns:

true when the key was handled.

handlePointerPressed

public boolean handlePointerPressed(int x,
                                    int y)

Handles pointer pressed events. This is an optional feature that doesn't need to be implemented by subclasses, since the parent container already forwards the event to the appropriate item (when this method returns false). The default implementation just returns false. You only need to implement this method when there are pointer events:

 //#if polish.hasPointerEvents
 

Parameters:

x - the x position of the event relative to the item's horizontal left edge

y - the y position of the event relative to the item's vertical top edge

Returns:

true when the event has been handled. When false is returned the parent container will forward the event to the affected item.

handlePointerReleased

protected boolean handlePointerReleased(int x,
                                        int y)

Handles the event when a pointer has been released at the specified position. The default implementation just returns false. You only need to implement this method when there are pointer events:

 //#if polish.hasPointerEvents
 

Parameters:

x - the x position of the event relative to the item's horizontal left edge

y - the y position of the event relative to the item's vertical top edge

Returns:

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

isValid

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. This allows casting without checking the parent item with instanceof in each method, for example. The default implementation just returns true for any case.

Parameters:

parent - the parent item

style - the style

Returns:

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

removeViewFromParent

protected void removeViewFromParent()

Removes this view from the parent item.

notifyItemPressedStart

protected boolean notifyItemPressedStart()

Is called when an item is pressed using the FIRE game action. The default implementation fowards this to the parent item.

Returns:

true when the item contains an action associated with FIRE

notifyItemPressedEnd

protected void notifyItemPressedEnd()

Is called when pressing an item is finished, usually when the FIRE key is released The default implementation fowards this to the parent item.

paintBackground

public void paintBackground(Background background,
                            int x,
                            int y,
                            int width,
                            int height,
                            javax.microedition.lcdui.Graphics g)

Parameters:

background -

x -

y -

width -

height -

g -

paintBorder

public void paintBorder(Border border,
                        int x,
                        int y,
                        int width,
                        int height,
                        javax.microedition.lcdui.Graphics g)

Parameters:

border -

x -

y -

width -

height -

g -

releaseResources

public void releaseResources()

Releases all resources that are not required to keep the state of this view. The default implementation does free nothing and only sets the "isInitialized" flag if the parent item.