com.nokia.mid.ui
Class CanvasGraphicsItem

java.lang.Object
  com.nokia.mid.ui.CanvasItem
      com.nokia.mid.ui.CanvasGraphicsItem

public abstract class CanvasGraphicsItem
extends CanvasItem

A CanvasGraphicsItem is a drawable component that is used with a parent object; with Canvas. The CanvasGraphicsItem may be added to and removed from Canvas through setParent method.

Parent for CanvasGraphicsItem must be set, through setParent method, before other methods are called and change the state or parameters of CanvasGraphicsItem.

The implementation presents the CanvasGraphicsItem with the same draw capabilities as Canvas has. See Graphics for drawing options.

CanvasGraphicsItem does not support DSA over its area. Playing video or using camera over CanvasGraphicsItem area can lead to artifacts on screen.

CanvasGraphicsItem does not support touch input. Pointer events are delivered to parent object from the area of the visible CanvasGraphicsItem.

Visibility of CanvasGraphicsItem is set through setVisible(). The default visbility is set to false. Changing parent does not affect the visibility status.

The CanvasGraphicsItem cannot have focus.

Since:

1.4

Constructor Summary

CanvasGraphicsItem(int width, int height)
Creates a new CanvasGraphicsItem object with the given initial size.

Method Summary

int	getZPosition() Returns the Z-position (elevation) of the item.
protected abstract void	paint(javax.microedition.lcdui.Graphics graphics) Renders the CanvasGraphicsItem.
void	repaint() Requests a repaint for the entire CanvasGraphicsItem.
void	repaint(int x, int y, int width, int height) Requests a repaint for the specified region of the CanvasGraphicsItem.
void	setParent(java.lang.Object parent) Set the parent object of this CanvasGraphicsItem.
void	setPosition(int x, int y) Sets the rendering position of this CanvasGraphicsItem.
void	setSize(int width, int height) Sets the size of this CanvasGraphicsItem in pixels.
void	setVisible(boolean visible) Sets the visibility value of CanvasGraphicsItem.
void	setZPosition(int z) Sets the Z-position (elevation) of the item.

Methods inherited from class com.nokia.mid.ui.CanvasItem

getHeight, getParent, getPositionX, getPositionY, getWidth, isVisible

Methods inherited from class java.lang.Object

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

Constructor Detail

CanvasGraphicsItem

public CanvasGraphicsItem(int width,
                          int height)

Creates a new CanvasGraphicsItem object with the given initial size.

Parameters:

width - width in pixels

height - height in pixels

Throws:

java.lang.IllegalArgumentException - if the width or height is less than one pixel

Method Detail

setParent

public void setParent(java.lang.Object parent)

Set the parent object of this CanvasGraphicsItem. Typically the parent object would be Canvas. Setting the parameter to null removes the association to the parent. If setParent(null) is called for a CanvasGraphicsItem yet not having any parent or setParent(parent) is called with the same parent, the call is silently ignored.

Overrides:

setParent in class CanvasItem

Parameters:

parent - the parent object

Throws:

java.lang.IllegalArgumentException - if aParent is not a valid object with which a CanvasGraphicsItem can be associated, or if CanvasItem is already set to another another parent

setSize

public void setSize(int width,
                    int height)

Sets the size of this CanvasGraphicsItem in pixels.

Overrides:

setSize in class CanvasItem

Parameters:

width - width in pixels

height - height in pixels

Throws:

java.lang.IllegalArgumentException - if the width or height is less than one pixel

setPosition

public void setPosition(int x,
                        int y)

Sets the rendering position of this CanvasGraphicsItem. The anchor point given is relative to the upper left corner of the target Canvas.

The CanvasGraphicsItem may be placed fully off or partially of the visible area of the target Canvas by the setPosition method; in this case the CanvasGraphicsItem is just parly visible.

Overrides:

setPosition in class CanvasItem

Parameters:

x - the x coordinate of the anchor point, in pixels.

y - the y coordinate of the anchor point, in pixels.

Throws:

java.lang.IllegalStateException - if a valid parent object hasn't been set.

See Also:

setParent(java.lang.Object aParent)

setVisible

public void setVisible(boolean visible)

Sets the visibility value of CanvasGraphicsItem. Initially CanvasGraphicsItem is not visible so it must be explicitly set to visible in order it to appear on UI.

Setting visibility to true shows the graphics item with its content. If the graphics item is already visible calling setVisible(true) does nothing.

Setting the visibility to false hides the graphics item and its content. If the graphics item is already hidden calling setVisible(false) does nothing.

Overrides:

setVisible in class CanvasItem

Parameters:

visible - visibility of the CanvasGraphicsItem

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set.

See Also:

setParent(java.lang.Object aParent)

setZPosition

public void setZPosition(int z)

Sets the Z-position (elevation) of the item.

The Z-position decides the stacking order of items on the same parent. An item of higher Z-position will be drawn on top of an item with a lower Z-position.

The Z-position is unique for each item, meaning that changing a Z-position of an item may change the Z-position of the items that share the same parent. The Z-position does not affect the item's size in any way.

When items are added with CanvasItem.setParent(java.lang.Object) they will get a Z-position that is increased by 1 from the item that is the top most item at that time.

Overrides:

setZPosition in class CanvasItem

Parameters:

z - the Z-position of the item.

Throws:

java.lang.IllegalArgumentException - if z < 0

java.lang.IllegalStateException - if a valid parent object has not been set.

See Also:

getZPosition(), setParent(java.lang.Object aParent)

getZPosition

public int getZPosition()

Returns the Z-position (elevation) of the item.

Overrides:

getZPosition in class CanvasItem

Returns:

The Z-position, or the elevation, of the item.

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set.

See Also:

, setParent(java.lang.Object aParent)

paint

protected abstract void paint(javax.microedition.lcdui.Graphics graphics)

Renders the CanvasGraphicsItem.

The application implements this method to paint graphics on CanvasGraphicsItem.

CanvasGraphicsItem paint works in the same way as Canvas paint method. The only difference to Canvas paint method is that application does not need to paint all the pixels of the clip region as that the clip region needing updating is cleared and fully transparent before paint is called. Content rendered by application in previous paint method calls is not available in the clip region. Coordinates used in Graphics methods are relative to CanvasGraphicsItem itself. This means (0,0) coordinate is top left pixel of CanvasGraphicsItem as positioned in the containing parent (e.g. Canvas).

Parameters:

graphics - the Graphics object to be used for rendering the Canvas

repaint

public final void repaint(int x,
                          int y,
                          int width,
                          int height)

Requests a repaint for the specified region of the CanvasGraphicsItem.

Coordinates are relative to the CanvasGraphicsItem coordinates. The method works in similar manner as Canvas repaint method.

Parameters:

x - the x coordinate of the rectangle to be repainted, in pixels

y - the y coordinate of the rectangle to be repainted, in pixels

width - the width of the rectangle to be repainted, in pixels

height - the height of the rectangle to be repainted, in pixels

repaint

public final void repaint()

Requests a repaint for the entire CanvasGraphicsItem. The effect is identical to repaint(0, 0, getWidth(), getHeight());

See Also:

repaint(int x, int y, int width, int height)