de.enough.polish.ui
Class ItemView

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

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

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

public abstract class ItemView
extends Object
implements Serializable

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

Copyright Enough Software 2006 - 2009

 history
        Nov 27, 2006 - rob creation
 

Author:

Robert Virkus, j2mepolish@enough.de

Field Summary

protected int	availableHeight
protected int	availableWidth
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.
protected void	addItemBackground(Item item, Background background) Adds a background to an item again
protected void	addItemBackgroundBorder(Item item, Background background, Border border) Adds a background and a border to an item again
protected void	addItemBorder(Item item, Border border) Adds a border to an item again
protected Point	adjustToContentArea(int x, int y) Adjusts the given position to the content area of this view
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	destroy() Destroys the containerview by removing references to the parent item
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	handlePointerDragged(int x, int y) Handles the event when a pointer has been dragged to the specified position.
boolean	handlePointerDragged(int x, int y, ClippingRegion repaintRegion) Handles the event when a pointer has been dragged to the specified position.
boolean	handlePointerPressed(int x, int y) Handles pointer pressed events.
boolean	handlePointerReleased(int x, int y) Handles the event when a pointer has been released at the specified position.
boolean	handlePointerTouchDown(int x, int y) Handles a touch down/press event.
boolean	handlePointerTouchUp(int x, int y) Handles a touch up/release event.
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 void	init(Item parent, int firstLineWidth, int availWidth, int availHeight) Initializes this item view.
protected abstract void	initContent(Item parent, int firstLineWidth, int availWidth, int availHeight) Initialises this item view.
protected void	initContentByParent(Item parent, int firstLineWidth, int availWidth, int availHeight) Calls the original initContent method on the parent.
protected void	initMargin(Style style, int availWidth) Initializes the margin of the parent item Subclasses can override this (e.g.
protected void	initPadding(Style style, int availWidth) Initializes the padding of the parent item Subclasses can override this (e.g.
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 void	notifyItemPressedEnd(Item item) Call this to notify an item that it is not being pressed anymore after a FIRE game action or similar
protected boolean	notifyItemPressedStart() Is called when an item is pressed using the FIRE game action.
protected boolean	notifyItemPressedStart(Item item) Call this to notify an item that it is being pressed using a FIRE game action or similar
protected void	onScreenSizeChanged(int screenWidth, int screenHeight) Notifies this item about a new screen size.
void	paintBackground(Background background, int x, int y, int width, int height, Graphics g)
void	paintBorder(Border border, int x, int y, int width, int height, Graphics g)
protected abstract void	paintContent(Item parent, int x, int y, int leftBorder, int rightBorder, Graphics g) Paints this item view.
protected void	paintContentByParent(Item parent, int x, int y, int leftBorder, int rightBorder, 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	setContentHeight(int height) Sets the content height of this item.
protected void	setContentWidth(int width) Sets the content width of this view.
protected void	setStyle(Style style) Sets the style for this view.
protected void	setStyle(Style style, boolean resetStyle) Sets the style for this view and is used to specify animatable CSS attribute.
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

availableWidth

protected int availableWidth

availableHeight

protected int availableHeight

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

initMargin

protected void initMargin(Style style,
                          int availWidth)

Initializes the margin of the parent item Subclasses can override this (e.g. the container embedded in a screen)

Parameters:

style - the style

availWidth - the available width

initPadding

protected void initPadding(Style style,
                           int availWidth)

Initializes the padding of the parent item Subclasses can override this (e.g. the container embedded in a screen)

Parameters:

style - the style

availWidth - the available width

init

protected void init(Item parent,
                    int firstLineWidth,
                    int availWidth,
                    int availHeight)

Initializes this item view. This method saves the available width and height and then calls initContent(int, int, int). Please always call the super.init(..) method when overriding this method.

Parameters:

parent - the parent item

firstLineWidth - the maximum width of the first line

availWidth - the maximum width of the view

availHeight - the maximum height of the view

See Also:

initContent(Item, int, int, int), availableWidth, availableHeight

initContent

protected abstract void initContent(Item parent,
                                    int firstLineWidth,
                                    int availWidth,
                                    int availHeight)

Initialises this item view. The implementation needs to calculate and set the contentWidth and contentHeight fields.

Parameters:

parent - the parent item

firstLineWidth - the maximum width of the first line

availWidth - the maximum width of the view

availHeight - the maximum height of the view

See Also:

contentWidth, contentHeight

paintContent

protected abstract void paintContent(Item parent,
                                     int x,
                                     int y,
                                     int leftBorder,
                                     int rightBorder,
                                     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 availWidth,
                                   int availHeight)

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

availWidth - the maximum width of any following lines

availHeight - TODO

paintContentByParent

protected void paintContentByParent(Item parent,
                                    int x,
                                    int y,
                                    int leftBorder,
                                    int rightBorder,
                                    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

setStyle

protected void setStyle(Style style,
                        boolean resetStyle)

Sets the style for this view and is used to specify animatable CSS attribute. The style can include additional parameters for the view. Subclasses should call super.setStyle(style, resetStyle) first.

Parameters:

style - the style

resetStyle - true when default style settings should be applied when nothing is set

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

See Also:

removeItemBackground(Item), addItemBorder(Item, 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

See Also:

removeItemBorder(Item), addItemBackground(Item, Background)

addItemBackground

protected void addItemBackground(Item item,
                                 Background background)

Adds a background to an item again

Parameters:

item - to which the background should be added

background - the background

See Also:

removeItemBackground(Item), addItemBackgroundBorder(Item, Background, Border)

addItemBorder

protected void addItemBorder(Item item,
                             Border border)

Adds a border to an item again

Parameters:

item - to which the border should be added

border - the border

See Also:

removeItemBorder(Item), addItemBackgroundBorder(Item, Background, Border)

addItemBackgroundBorder

protected void addItemBackgroundBorder(Item item,
                                       Background background,
                                       Border border)

Adds a background and a border to an item again

Parameters:

item - to which the border should be added

background - the background

border - the border

See Also:

removeItemBackground(Item), removeItemBorder(Item)

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.

adjustToContentArea

protected Point adjustToContentArea(int x,
                                    int y)

Adjusts the given position to the content area of this view

Parameters:

x - the horizontal position relative to the parent item's outer left border

y - the vertical position relative to the parent item's outer top border

Returns:

the adjusted position relative to this view's content area

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

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

handlePointerDragged

public boolean handlePointerDragged(int x,
                                    int y,
                                    ClippingRegion repaintRegion)

Handles the event when a pointer has been dragged to the specified position. The default implementation adds a repaint region when handlePointerDragged(x,y) returned true. 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

repaintRegion - the repaint region into which the repaint area is marked when the event is handled

Returns:

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

See Also:

handlePointerDragged(int, int), Item.addRepaintArea(ClippingRegion)

handlePointerDragged

public boolean handlePointerDragged(int x,
                                    int y)

Handles the event when a pointer has been dragged to 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.

handlePointerTouchDown

public boolean handlePointerTouchDown(int x,
                                      int y)

Handles a touch down/press event. This is similar to a pointerPressed event, however it is only available on devices with screens that differentiate between press and touch events (read: BlackBerry Storm).

Parameters:

x - the horizontal pixel position of the touch event relative to the parent item's left position

y - the vertical pixel position of the touch event relative to the parent item's top position

Returns:

true when the event was handled

handlePointerTouchUp

public boolean handlePointerTouchUp(int x,
                                    int y)

Handles a touch up/release event. This is similar to a pointerReleased event, however it is only available on devices with screens that differentiate between press and touch events (read: BlackBerry Storm).

Parameters:

x - the horizontal pixel position of the touch event relative to the parent item's left position

y - the vertical pixel position of the touch event relative to the parent item's top position

Returns:

true when the event was handled

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,
                            Graphics g)

Parameters:

background -

x -

y -

width -

height -

g -

paintBorder

public void paintBorder(Border border,
                        int x,
                        int y,
                        int width,
                        int height,
                        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.

destroy

public void destroy()

Destroys the containerview by removing references to the parent item

notifyItemPressedStart

protected boolean notifyItemPressedStart(Item item)

Call this to notify an item that it is being pressed using a FIRE game action or similar

Parameters:

item - the item that should be notified

Returns:

true when the item requests a repaint after this action

notifyItemPressedEnd

protected void notifyItemPressedEnd(Item item)

Call this to notify an item that it is not being pressed anymore after a FIRE game action or similar

Parameters:

item - the item that should be notified

setContentWidth

protected void setContentWidth(int width)

Sets the content width of this view. Subclasses can override this to react to content width changes

Parameters:

width - the new content width in pixel

setContentHeight

protected void setContentHeight(int height)

Sets the content height of this item. Subclasses can override this to react to content height changes

Parameters:

height - the new content height in pixel

onScreenSizeChanged

protected void onScreenSizeChanged(int screenWidth,
                                   int screenHeight)

Notifies this item about a new screen size. The default implementation is empty.

Parameters:

screenWidth - the screen width

screenHeight - the screen height