javax.microedition.lcdui
Class CanvasItem

java.lang.Object
  javax.microedition.lcdui.CanvasItem

Direct Known Subclasses:

TextEditor

public abstract class CanvasItem
extends java.lang.Object

CanvasItem abstracts the generic features of it's subclasses, such as TextEditor component. Such features include setting the size and position component. Also associating the item, such as TextEditor, with it's parent, such as Canvas or CustomItem, may be done through this API with setParent() method.

Since:

3.0

See Also:

TextEditor, Canvas, CustomItem

Constructor Summary

CanvasItem()
Constructor for CanvasItem.

Method Summary

int	getHeight() Gets the height of this CanvasItem in pixels.
java.lang.Object	getParent() Gets the parent object of this CanvasItem.
int	getPositionX() Gets the x-coordinate of the rendering position of this CanvasItem.
int	getPositionY() Gets the y-coordinate of the rendering position of this CanvasItem.
int	getWidth() Gets the width of this CanvasItem in pixels.
int	getZPosition() Gets the Z-position, or the elevation, of the item.
void	setParent(java.lang.Object parent) Sets the parent object of this CanvasItem.
void	setPositionX(int x) Sets the x-coordinate of the rendering position of this CanvasItem.
void	setPositionY(int y) Sets the y-coordinate of the rendering position of this CanvasItem.
void	setSize(int width, int height) Sets the size of this CanvasItem in pixels.
void	setVisible(boolean visible) Sets the visibility value of the CanvasItem.
void	setZPosition(int z) Sets the Z-position, or the elevation, of the item.

Methods inherited from class java.lang.Object

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

Constructor Detail

CanvasItem

public CanvasItem()

Constructor for CanvasItem.

Method Detail

setParent

public void setParent(java.lang.Object parent)

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

Parameters:

parent - the parent object

Throws:

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

getParent

public java.lang.Object getParent()

Gets the parent object of this CanvasItem. Typically the parent object would be Canvas or CustomItem.

Returns:

the parent object, null if no parent has been set

setSize

public void setSize(int width,
                    int height)

Sets the size of this CanvasItem in pixels.

Parameters:

width - width in pixels

height - height in pixels

Throws:

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

getHeight

public int getHeight()

Gets the height of this CanvasItem in pixels.

Returns:

height in pixels

getWidth

public int getWidth()

Gets the width of this CanvasItem in pixels.

Returns:

width in pixels

setPositionX

public void setPositionX(int x)

Sets the x-coordinate of the rendering position of this CanvasItem. The origin is relative to the coordinate system of the parent.

The CanvasItem may be placed partially or fully off of the visible area of the parent by the setPosition method; in this case the CanvasItem is just not fully visible.

Parameters:

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

setPositionY

public void setPositionY(int y)

Sets the y-coordinate of the rendering position of this CanvasItem. The origin is relative to the coordinate system of the parent.

The CanvasItem may be placed partially or fully off of the visible area of the parent by the setPosition method; in this case the CanvasItem is just not fully visible.

Parameters:

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

getPositionX

public int getPositionX()

Gets the x-coordinate of the rendering position of this CanvasItem. The origin is relative to the coordinate system of the parent.

Returns:

the x-coordinate position of the CanvasItem

getPositionY

public int getPositionY()

Gets the y-coordinate of the rendering position of this CanvasItem. The origin is relative to the coordinate system of the parent.

Returns:

the y-coordinate position of the CanvasItem

setVisible

public void setVisible(boolean visible)

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

If the CanvasItem is already visible, calling setVisible(true) does nothing. If the editor is already hidden calling setVisible(false) does nothing.

Parameters:

visible - true to set visible, false to set invisible

Throws:

java.lang.IllegalStateException - if the item is not added to any parent

setZPosition

public void setZPosition(int z)

Sets the Z-position, or the elevation, of the item. The elevation decides the stacking order of neighboring items. An item of high Z-position will be drawn on top of an item with a lower Z-position if they share the same parent item.

Modifying Z-value of an item should not impact Z-position of other items, so there may be items with the same Z-position. Items that share the same Z-position will be drawn in an undefined order, although the order will stay the same for as long as the items live.

The Z-position does not affect the item's size in any way.

When items are added with setParent they will get a Z-position that is increased by 1 from the previously added item. However if setZPosition has been called before calling setParent then setting the parent does not change the already set Z-position of this CanvasItem.

Parameters:

z - the Z-position of the item

Throws:

java.lang.IllegalArgumentException - if z < 0

getZPosition

public int getZPosition()

Gets the Z-position, or the elevation, of the item. The Z-position decides the stacking order of neighboring items.

Returns:

the Z-position of the item