de.enough.polish.ui
Class FakeCustomItem

java.lang.Object
  javax.microedition.lcdui.Item
      javax.microedition.lcdui.CustomItem
          de.enough.polish.ui.FakeCustomItem

Direct Known Subclasses:

ChartItem, FakeContainerCustomItem, FakeStringCustomItem, PictureBrowserItem

public abstract class FakeCustomItem
extends CustomItem

A superclass for components that can be added to a Form.

Items support following CSS attributes:

• margin, margin-left, margin-right, margin-top, margin-bottom: margins between border and next item.
• padding, padding-left, padding-right, padding-top, padding-bottom, padding-vertical, padding-horizontal: paddings between border and content.
• background: The background of this item.
• border: The border of this item.
• min-width: The minimum width of this item.
• max-width: The maximum width of this item.
• min-height: The minimum height of this item.
• max-height: The maximum height of this item.
• before: URL of image that should be placed before this item.
• after: URL of image that should be placed after this item.
• include-label: set to true when the background and border should include the label of this item as well.
• colspan: when this item is embedded in a table, you can span it over several cells, e.g. colspan: 2;.
• label-style: The name of the specialized label style for this item, e.g. "label-style: funnyLabel;"
• focused-style: The name of the specialized focused style for this item, e.g. "focused-style: funnyFocused;"
• view-type: The view of this item.

A superclass for components that can be added to a Form. All Item objects have a label field, which is a string that is attached to the item. The label is typically displayed near the component when it is displayed within a screen. The label should be positioned on the same horizontal row as the item or directly above the item. The implementation should attempt to distinguish label strings from other textual content, possibly by displaying the label in a different font, aligning it to a different margin, or appending a colon to it if it is placed on the same line as other string content. If the screen is scrolling, the implementation should try to keep the label visible at the same time as the Item.

In some cases, when the user attempts to interact with an Item, the system will switch to a system-generated screen where the actual interaction takes place. If this occurs, the label will generally be carried along and displayed within this new screen in order to provide the user with some context for the operation. For this reason it is recommended that applications supply a label to all interactive Item objects. However, this is not required, and a null value for a label is legal and specifies the absence of a label.

Item Layout

An Item's layout within its container is influenced through layout directives:

• LAYOUT_DEFAULT
• LAYOUT_LEFT
• LAYOUT_RIGHT
• LAYOUT_CENTER
• LAYOUT_TOP
• LAYOUT_BOTTOM
• LAYOUT_VCENTER
• LAYOUT_NEWLINE_BEFORE
• LAYOUT_NEWLINE_AFTER
• LAYOUT_SHRINK
• LAYOUT_VSHRINK
• LAYOUT_EXPAND
• LAYOUT_VEXPAND
• LAYOUT_2

The LAYOUT_DEFAULT directive indicates that the container's default layout policy is to be used for this item. LAYOUT_DEFAULT has the value zero and has no effect when combined with other layout directives. It is useful within programs in order to document the programmer's intent.

The LAYOUT_LEFT, LAYOUT_RIGHT, and LAYOUT_CENTER directives indicate horizontal alignment and are mutually exclusive. Similarly, the LAYOUT_TOP, LAYOUT_BOTTOM, and LAYOUT_VCENTER directives indicate vertical alignment and are mutually exclusive.

A horizontal alignment directive, a vertical alignment directive, and any combination of other layout directives may be combined using the bit-wise OR operator (|) to compose a layout directive value. Such a value is used as the parameter to the setLayout(int) method and is the return value from the getLayout() method.

Some directives have no defined behavior in some contexts. A layout directive is ignored if its behavior is not defined for the particular context within which the Item resides.

A complete specification of the layout of Items within a Form is given here.

Item Sizes

Items have two explicit size concepts: the minimum size and the preferred size. Both the minimum and the preferred sizes refer to the total area of the Item, which includes space for the Item's contents, the Item's label, as well as other space that is significant to the layout policy. These sizes do not include space that is not significant for layout purposes. For example, if the addition of a label to an Item would cause other Items to move in order to make room, then the space occupied by this label is significant to layout and is counted as part of the Item's minimum and preferred sizes. However, if an implementation were to place the label in a margin area reserved exclusively for labels, this would not affect the layout of neighboring Items. In this case, the space occupied by the label would not be considered part of the minimum and preferred sizes.

The minimum size is the smallest size at which the Item can function and display its contents, though perhaps not optimally. The minimum size may be recomputed whenever the Item's contents changes.

The preferred size is generally a size based on the Item's contents and is the smallest size at which no information is clipped and text wrapping (if any) is kept to a tolerable minimum. The preferred size may be recomputed whenever the Item's contents changes. The application can lock the preferred width or preferred height (or both) by supplying specific values for parameters to the setPreferredSize method. The manner in which an Item fits its contents within an application-specified preferred size is implementation-specific. However, it is recommended that textual content be word-wrapped to fit the preferred size set by the application. The application can unlock either or both dimensions by supplying the value -1 for parameters to the setPreferredSize method.

When an Item is created, both the preferred width and height are unlocked. In this state, the implementation computes the preferred width and height based on the Item's contents, possibly including other relevant factors such as the Item's graphic design and the screen dimensions. After having locked either the preferred width or height, the application can restore the initial, unlocked state by calling setPreferredSize(-1, -1).

The application can lock one dimension of the preferred size and leave the other unlocked. This causes the system to compute an appropriate value for the unlocked dimension based on arranging the contents to fit the locked dimension. If the contents changes, the size on the unlocked dimension is recomputed to reflect the new contents, but the size on the locked dimension remains unchanged. For example, if the application called setPreferredSize(50, -1), the preferred width would be locked at 50 pixels and the preferred height would be computed based on the Item's contents. Similarly, if the application called setPreferredSize(-1, 60), the preferred height would be locked at 60 pixels and the preferred width would be computed based on the Item's contents. This feature is particularly useful for Items with textual content that can be line wrapped.

The application can also lock both the preferred width and height to specific values. The Item's contents are truncated or padded as necessary to honor this request. For Items containing text, the text should be wrapped to the specified width, and any truncation should occur at the end of the text.

Items also have an implicit maximum size provided by the implementation. The maximum width is typically based on the width of the screen space available to a Form. Since Forms can scroll vertically, the maximum height should typically not be based on the height of the available screen space.

If the application attempts to lock a preferred size dimension to a value smaller than the minimum or larger than the maximum, the implementation may disregard the requested value and instead use either the minimum or maximum as appropriate. If this occurs, the actual values used must be visible to the application via the values returned from the getPreferredWidth and getPreferredHeight methods.

Commands

A Command is said to be present on an Item if the Command has been added to this Item with a prior call to addCommand(javax.microedition.lcdui.Command) or setDefaultCommand(javax.microedition.lcdui.Command) and if the Command has not been removed with a subsequent call to removeCommand(javax.microedition.lcdui.Command). Commands present on an item should have a command type of ITEM. However, it is not an error for a command whose type is other than ITEM to be added to an item. For purposes of presentation and placement within its user interface, the implementation is allowed to treat a command's items as if they were of type ITEM.

Items may have a default Command. This state is controlled by the setDefaultCommand(javax.microedition.lcdui.Command) method. The default Command is eligible to be bound to a special platform-dependent user gesture. The implementation chooses which gesture is the most appropriate to initiate the default command on that particular Item. For example, on a device that has a dedicated selection key, pressing this key might invoke the item's default command. Or, on a stylus-based device, tapping on the Item might invoke its default command. Even if it can be invoked through a special gesture, the default command should also be invokable in the same fashion as other item commands.

It is possible that on some devices there is no special gesture suitable for invoking the default command on an item. In this case the default command must be accessible to the user in the same fashion as other item commands. The implementation may use the state of a command being the default in deciding where to place the command in its user interface.

It is possible for an Item not to have a default command. In this case, the implementation may bind its special user gesture (if any) for another purpose, such as for displaying a menu of commands. The default state of an Item is not to have a default command. An Item may be set to have no default Command by removing it from the Item or by passing null to the setDefaultCommand() method.

The same command may occur on more than one Item and also on more than one Displayable. If this situation occurs, the user must be provided with distinct gestures to invoke that command on each Item or Displayable on which it occurs, while those Items or Displayables are visible on the display. When the user invokes the command, the listener (CommandListener or ItemCommandListener as appropriate) of just the object on which the command was invoked will be called.

Adding commands to an Item may affect its appearance, the way it is laid out, and the traversal behavior. For example, the presence of commands on an Item may cause row breaks to occur, or it may cause additional graphical elements (such as a menu icon) to appear. In particular, if a StringItem whose appearance mode is PLAIN (see below) is given one or more Commands, the implementation is allowed to treat it as if it had a different appearance mode.

J2ME Polish notifies the command-listener of the current screen, when an item-command has been selected and no item-command-listener has been registered.

Appearance Modes

The StringItem and ImageItem classes have an appearance mode attribute that can be set in their constructors. This attribute can have one of the values PLAIN, HYPERLINK, or BUTTON. An appearance mode of PLAIN is typically used for non-interactive display of textual or graphical material. The appearance mode values do not have any side effects on the interactivity of the item. In order to be interactive, the item must have one or more Commands (preferably with a default command assigned), and it must have a CommandListener that receives notification of Command invocations. The appearance mode values also do not have any effect on the semantics of Command invocation on the item. For example, setting the appearance mode of a StringItem to be HYPERLINK requests that the implementation display the string contents as if they were a hyperlink in a browser. It is the application's responsibility to attach a Command and a listener to the StringItem that provide behaviors that the user would expect from invoking an operation on a hyperlink, such as loading the referent of the link or adding the link to the user's set of bookmarks.

Setting the appearance mode of an Item to be other than PLAIN may affect its minimum, preferred, and maximum sizes, as well as the way it is laid out. For example, a StringItem with an appearance mode of BUTTON should not be wrapped across rows. (However, a StringItem with an appearance mode of HYPERLINK should be wrapped the same way as if its appearance mode is PLAIN.)

A StringItem or ImageItem in BUTTON mode can be used to create a button-based user interface. This can easily lead to applications that are inconvenient to use. For example, in a traversal-based system, users must navigate to a button before they can invoke any commands on it. If buttons are spread across a long Form, users may be required to perform a considerable amount of navigation in order to discover all the available commands. Furthermore, invoking a command from a button at the other end of the Form can be quite cumbersome. Traversal-based systems often provide a means of invoking commands from anywhere (such as from a menu), without the need to traverse to a particular item. Instead of adding a command to a button and placing that button into a Form, it would often be more appropriate and convenient for users if that command were added directly to the Form. Buttons should be used only in cases where direct user interaction with the item's string or image contents is essential to the user's understanding of the commands that can be invoked from that item.

Default State

Unless otherwise specified by a subclass, the default state of newly created Items is as follows:

• the Item is not contained within ("owned by") any container;
• there are no Commands present;
• the default Command is null;
• the ItemCommandListener is null;
• the layout directive value is LAYOUT_DEFAULT; and
• both the preferred width and preferred height are unlocked.

Since:

MIDP 1.0

Field Summary

net.rim.device.api.ui.Field	_bbField a blackberry specific internal field
int	appearanceMode The appearance mode of this item, either PLAIN or one of the interactive modes BUTTON, HYPERLINK or INTERACTIVE.
protected int	availableHeight
protected int	availableWidth
protected int	availContentHeight
protected int	availContentWidth
Background	background the background of this item
protected int	backgroundHeight
protected int	backgroundWidth
protected int	backgroundYOffset The vertical offset for the background, can be used for smoother scrolling, for example
protected int	beforeWidth
protected Border	bgBorder the background border of an item - this border is painted before the background.
protected Border	border
static int	BUTTON An appearance mode value indicating that the Item is to appear as a button.
boolean	cacheItemImage
protected int	colSpan
protected ArrayList	commands
protected Background	completeBackground
protected Dimension	completeBackgroundPadding
protected Border	completeBorder
protected int	contentHeight The height of this item's content
protected int	contentWidth The width of this item's content
protected int	contentX the horizontal position of this item's content relative to it's left edge (so for a left aligned item its marginLeft + border.widthLeft + paddingLeft
protected Dimension	contentXAdjustment
protected int	contentY the vertical position of this item's content relative to it's top edge
protected Dimension	contentYAdjustment
protected Dimension	cssHeight
protected String	cssSelector The appropriate CSS selector of this item.
protected Dimension	cssWidth
protected Command	defaultCommand
protected Style	focusedStyle
static int	HORIZONTAL A J2ME Polish constant defining a horizontal orientation.
static int	HYPERLINK An appearance mode value indicating that the Item is to appear as a hyperlink.
protected boolean	ignoreRepaintRequests
protected boolean	includeLabel
static int	INTERACTIVE A J2ME Polish appearance mode value indicating that the Item accepts input from the user.
protected int	internalHeight The internal height of this item's content.
protected int	internalWidth The internal width of this item's content.
protected int	internalX The internal horizontal position of this item's content relative to it's left edge.
protected int	internalY the vertical position of this item's internal content relative to it's top edge
protected boolean	isContentVisible
boolean	isFocused flag indicating whether this item is focused
protected boolean	isInlineLabel
protected boolean	isInvisible
protected boolean	isLayoutCenter
protected boolean	isLayoutExpand
protected boolean	isLayoutRight
protected boolean	isPressed
protected boolean	isShown
protected boolean	isStyleInitialised Determines whether the style has be dynamically assigned already.
protected ItemCommandListener	itemCommandListener
int	itemHeight the height of this item - only for read access
int	itemWidth the width of this item - only for read access
protected StringItem	label
protected Style	labelStyle
protected Style	landscapeStyle
protected int	layout
static int	LAYOUT_2 A layout directive indicating that new MIDP 2.0 layout rules are in effect for this Item.
static int	LAYOUT_BOTTOM A layout directive indicating that this Item should have a bottom-aligned layout.
static int	LAYOUT_CENTER A layout directive indicating that this Item should have a horizontally centered layout.
static int	LAYOUT_DEFAULT A layout directive indicating that this Item should follow the default layout policy of its container.
static int	LAYOUT_EXPAND A layout directive indicating that this Item's width may be increased to fill available space.
static int	LAYOUT_LEFT A layout directive indicating that this Item should have a left-aligned layout.
static int	LAYOUT_NEWLINE_AFTER A layout directive indicating that this Item should the last on its line or row, and that the next Item (if any) in the container should be placed on a new line or row.
static int	LAYOUT_NEWLINE_BEFORE A layout directive indicating that this Item should be placed at the beginning of a new line or row.
static int	LAYOUT_RIGHT A layout directive indicating that this Item should have a right-aligned layout.
static int	LAYOUT_SHRINK A layout directive indicating that this Item's width may be reduced to its minimum width.
static int	LAYOUT_TOP A layout directive indicating that this Item should have a top-aligned layout.
static int	LAYOUT_VCENTER A layout directive indicating that this Item should have a vertically centered layout.
static int	LAYOUT_VEXPAND A layout directive indicating that this Item's height may be increased to fill available space.
static int	LAYOUT_VSHRINK A layout directive indicating that this Item's height may be reduced to its minimum height.
protected int	marginBottom
protected int	marginLeft
protected int	marginRight
protected int	marginTop
protected Dimension	maximumHeight
protected Dimension	maximumItemHeight
protected Dimension	maximumItemWidth
protected Dimension	maximumWidth
protected Dimension	minimumHeight
protected Dimension	minimumItemHeight
protected Dimension	minimumItemWidth
protected Dimension	minimumWidth
protected NativeItem	nativeItem
static int	NO_POSITION_SET no internal position has been set for this item, value is -9999.
protected int	opacity
protected boolean	opacityPaintNormally
protected int[]	opacityRgbData
protected int	paddingBottom
protected int	paddingHorizontal
protected int	paddingLeft
protected int	paddingRight
protected int	paddingTop
protected int	paddingVertical
protected Item	parent The parent of this item.
static int	PLAIN An appearance mode value indicating that the Item is to have a normal appearance.
protected Style	portraitStyle
protected int	preferredHeight
protected int	preferredWidth
protected boolean	preserveViewType
int	relativeX the horizontal start position relative to it's parent's item left content edge
int	relativeY the vertical start position of this item relative to it's parent item top content edge
protected int	rowSpan
protected Screen	screen The screen to which this item belongs to.
protected boolean	setView
protected Style	style
static int	TRANSPARENT A J2ME Polish constant defining a transparent/invisible color.
protected boolean	useSingleRow indicates that label and content are positioned on the same row if true
static int	VERTICAL A J2ME Polish constant defining a vertical orientation.
protected ItemView	view
protected Dimension	xAdjustment
protected Dimension	yAdjustment

Fields inherited from class javax.microedition.lcdui.CustomItem

KEY_PRESS, KEY_RELEASE, KEY_REPEAT, NONE, POINTER_DRAG, POINTER_PRESS, POINTER_RELEASE, TRAVERSE_HORIZONTAL, TRAVERSE_VERTICAL

Constructor Summary

protected	FakeCustomItem() Convenience constructor.
protected	FakeCustomItem(String label, int layout) Convenience constructor.
protected	FakeCustomItem(String label, int layout, int appearanceMode, Style style) Creates a new Item.
protected	FakeCustomItem(Style style) Convenience constructor.

Method Summary

void	addCommand(Command cmd) Adds a command to this item
void	addCommand(Command cmd) Adds a context sensitive Command to the item.
void	addCommand(Command cmd, Style commandStyle) Adds a context sensitive Command to the item.
protected void	addCommands(ArrayList commandsList) Adds all commands to the specified list.
void	addRelativeToBackgroundRegion(Background animatedBackground, Border animatedBorder, ClippingRegion repaintRegion, int x, int y, int width, int height) Adds a region relative to this item's background x/y start position.
void	addRelativeToBackgroundRegion(ClippingRegion repaintRegion, int x, int y, int width, int height) Adds a region relative to this item's background x/y start position.
void	addRelativeToContentRegion(ClippingRegion repaintRegion, int x, int y, int width, int height) Adds a region relative to this item's content x/y start position.
void	addRepaintArea(ClippingRegion repaintRegion) Adds a repaint request for this item's space.
boolean	animate() Animates this item.
void	animate(long currentTime, ClippingRegion repaintRegion) Animates this item.
boolean	containsCommand(Command command) Determines whether this item contains the given command.
protected abstract String	createCssSelector() Retrieves the CSS selector for this item.
protected void	defocus(Style originalStyle) Removes the focus from this item.
void	destroy() Destroy the item by removing all references to parent, screen, listeners etc.
void	fireEvent(String eventName, Object eventData) Fires an event for this item as well as its subitems like its label.
protected Style	focus(Style newStyle, int direction) Focuses this item.
int	getAbsoluteX() Retrieves this item's current absolute horizontal position
int	getAbsoluteY() Retrieves this item's current absolute vertical position
int	getAppearanceMode() Returns the appearance mode of this Item.
Object	getAttribute(Object key) Gets an previously added attribute of this item.
HashMap	getAttributes() Returns a HashMap object with all registered attributes.
int	getAvailableContentHeight() Retrieves the height of the content.
int	getAvailableContentWidth() Retrieves the width of the content.
int	getAvailableHeight() Retrieves the available height for this item.
int	getAvailableWidth() Retrieves the available width for this item.
int	getBackgroundHeight() Retrieves the height of this item's background.
int	getBackgroundWidth() Retrieves the width of this item's background.
int	getBackgroundX() Retrieves the start of the background relative to this item's origin.
int	getBackgroundY() Retrieves the start of the background relative to this item's origin.
protected int	getBorderWidthBottom() Retrieves the border width.
protected int	getBorderWidthLeft() Retrieves the border width.
protected int	getBorderWidthRight() Retrieves the border width.
protected int	getBorderWidthTop() Retrieves the border width.
int	getContentHeight() Retrieves the height of the content.
int	getContentWidth() Retrieves the width of the content.
int	getContentX() Retrieves the start of the content relative to this item's absolute x position.
int	getContentY() Retrieves the start of the content relative to this item's absolute y position.
Command	getDefaultCommand()
Style	getFocusedStyle() Retrieves the approriate style for focusing this item.
int	getInternalHeight() Retrieves the internal area's vertical height
int	getInternalWidth() Retrieves the internal area's vertical width
int	getInternalX() Retrieves the internal area's horizontal start relative to this item's content area
int	getInternalY() Retrieves the internal area's vertical start relative to this item's content area
int	getItemAreaHeight() Retrieves the height of the area that this item covers.
Item	getItemAt(int relX, int relY) Determines if this item or one of it's children is within the specified point.
ItemCommandListener	getItemCommandListener() Gets the listener for Commands to this Item.
ArrayList	getItemCommands()
int	getItemHeight(int firstLineWidth, int availWidth) Retrieves the complete height of this item.
int	getItemHeight(int firstLineWidth, int availWidth, int availHeight) Retrieves the complete height of this item.
ItemStateListener	getItemStateListener() Gets an ItemStateListener specifically for this item.
int	getItemWidth(int firstLineWidth, int availWidth) Retrieves the complete width of this item.
int	getItemWidth(int firstLineWidth, int availWidth, int availHeight) Retrieves the complete width of this item.
String	getLabel() Gets the label of this Item object.
Item	getLabelItem() Retrieves the label item that is used by this item.\
int	getLayout() Gets the layout directives used for placing the item.
int	getMaximumHeight() Gets the maximum height for this Item.
int	getMaximumHeight(int availHeight) Gets the maximum height for this Item.
int	getMaximumWidth() Gets the maximum width for this Item.
int	getMaximumWidth(int availWidth) Gets the maximum width for this Item.
protected int	getMinContentHeight() Default implementation of javax.microedition.lcdui.CustomItem method.
protected int	getMinContentWidth() Default implementation of javax.microedition.lcdui.CustomItem method.
int	getMinimumHeight() Gets the minimum height for this Item.
int	getMinimumHeight(int availHeight) Gets the minimum height for this Item.
int	getMinimumWidth() Gets the minimum width for this Item.
int	getMinimumWidth(int availWidth) Gets the minimum width for this Item.
NativeItem	getNativeItem() Species a native implementation for this item.
Item	getParent() Retrieves the parent of this item.
protected int	getPrefContentHeight(int width) Default implementation of javax.microedition.lcdui.CustomItem method.
protected int	getPrefContentWidth(int height) Default implementation of javax.microedition.lcdui.CustomItem method.
int	getpreferredHeight() Gets the preferred height of this Item.
int	getpreferredWidth() Gets the preferred width of this Item.
int[]	getRgbData() Retrieves the RGB data of this item.
int[]	getRgbData(boolean supportTranslucency, int rgbOpacity) Retrieves the RGB data of this item.
Screen	getScreen() Retrieves the screen to which this item belongs to.
Style	getStyle() Retrieves the style of this item.
UiEventListener	getUiEventListener() Retrieves the UiEventListener for this item or for one of its parents.
ItemView	getView() Retrieves the view type for this item.
protected ItemView	getView(ItemView viewType, Style viewStyle) Retrieves the view type for this item or instantiates a new one.
protected boolean	handleCommand(Command cmd) Tries to handle the specified command.
protected boolean	handleCommand(Command cmd) Tries to handle the specified command.
protected boolean	handleGesture(int gesture, int x, int y) Handles a touch gestures.
protected boolean	handleGestureHold(int x, int y) Handles the hold touch gestures.
protected boolean	handleGestureSwipeLeft(int x, int y) Handles the swipe left gesture.
protected boolean	handleGestureSwipeRight(int x, int y) Handles the swipe right gesture.
protected boolean	handleKeyPressed(int keyCode, int gameAction) Handles the key-pressed event.
protected boolean	handleKeyReleased(int keyCode, int gameAction) Handles the key-released event.
protected boolean	handleKeyRepeated(int keyCode, int gameAction) Handles the key-repeated event.
protected boolean	handlePointerDragged(int relX, int relY) Handles the dragging/movement of a pointer.
protected boolean	handlePointerDragged(int relX, int relY, ClippingRegion repaintRegion) Handles the dragging/movement of a pointer.
protected boolean	handlePointerPressed(int relX, int relY) Handles the event when a pointer has been pressed at the specified position.
protected boolean	handlePointerReleased(int relX, int relY) 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.
protected 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(int firstLineWidth, int availWidth, int availHeight) Initialises this item.
protected abstract void	initContent(int firstLineWidth, int availWidth, int availHeight) Initialises this item.
protected void	initLayout(Style style, int availWidth)
protected void	initMargin(Style style, int availWidth) Initializes the margin of this item Subclasses can override this (e.g.
protected void	initPadding(Style style, int availWidth) Initializes the padding of this item Subclasses can override this (e.g.
protected void	initStyle() Initialises the appropriate style for this item.
boolean	isFocused() Determines whether this item is currently focused.
boolean	isInContentArea(int relX, int relY) Determines whether the given relative x/y position is inside of this item's (visible) content area.
boolean	isInContentWithPaddingArea(int relX, int relY) Determines whether the given relative x/y position is inside of this item's content area.
boolean	isInItemArea(int relX, int relY) Determines whether the given relative x/y position is inside of this item's area including paddings, margins and label.
boolean	isInItemArea(int relX, int relY, Item child) Determines whether the given relative x/y position is inside of the specified child item's area including paddings, margins and label.
boolean	isInitialized() Determines the initialization state of this item
boolean	isInteractive() Determines whether this item is interactive and thus can be selected.
boolean	isLayoutBottom() Determines the layout of this item.
boolean	isLayoutCenter() Determines the layout of this item.
boolean	isLayoutExpand() Determines the layout of this item.
boolean	isLayoutLeft() Determines the layout of this item.
boolean	isLayoutNewlineAfter() Determines the layout of this item.
boolean	isLayoutNewlineBefore() Determines the layout of this item.
boolean	isLayoutRight() Determines the layout of this item.
boolean	isLayoutShrink() Determines the layout of this item.
boolean	isLayoutTop() Determines the layout of this item.
boolean	isLayoutVerticalCenter() Determines the layout of this item.
boolean	isLayoutVerticalExpand() Determines the layout of this item.
boolean	isLayoutVerticalShrink() Determines the layout of this item.
boolean	isPressed() Determines whether this item is currently pressed.
boolean	isVisible() Gets the visible status of this item.
void	notifyItemPressedEnd() Is called when an item is pressed
boolean	notifyItemPressedStart() Is called when an item is pressed using the FIRE game action
void	notifyStateChanged() Causes this Item's containing Form to notify the Item's ItemStateListener.
void	notifyUnvisited() Is called when the visited state of this item should be reset.
protected void	notifyValueChanged(Object newValue) Notifies this item about a change event, e.g.
void	notifyVisited() Is called when this item has been visited.
void	onScreenSizeChanged(int screenWidth, int screenHeight) Notifies this item about a new screen size.
protected void	paint(Graphics g, int w, int h) Default implementation of javax.microedition.lcdui.CustomItem method.
void	paint(int x, int y, int leftBorder, int rightBorder, Graphics g) Paints this item on the screen.
protected void	paintBackground(int x, int y, int width, int height, Graphics g) Paints the background and - if defined - the bgborder of this item.
protected void	paintBackgroundAndBorder(int x, int y, int width, int height, Graphics g) Paints the background and border of this item.
protected void	paintBorder(int x, int y, int width, int height, Graphics g) Paints the border of this item.
protected void	paintCommands(int x, int y, Graphics g) Paints the commands for this item after the user has pressed/clicked on an item for a long time.
protected abstract void	paintContent(int x, int y, int leftBorder, int rightBorder, Graphics g) Paints the content of this item.
protected RgbImage	paintFilter(int x, int y, RgbFilter[] partFilters, RgbImage rgbImage, int lo, Graphics g) Paints the given filters and retrieves the last processed RGB image.
void	releaseResources() Releases all (memory intensive) resources such as images or RGB arrays of this item.
Object	removeAttribute(Object key) Removes an previously added attribute of this item.
void	removeCommand(Command cmd) Removes the context sensitive command from item.
protected void	repaintFully() Repaints the complete screen to which this item belongs to.
void	requestInit() Requests that this item and all its parents are to be re-initialised, if the size of this item has been changed.
void	setAbsoluteY(int absY) Sets the absolute vertical position of this item.
void	setAppearanceMode(int appearanceMode) Sets the appearance mode of this item.
void	setAttribute(Object key, Object value) Sets an arbitrary attribute for this item.
void	setBackground(Background background) Sets a new background for this item.
void	setBorder(Border border) Sets a new border for this item
protected void	setContentHeight(int height) Sets the content height of this item.
protected void	setContentWidth(int width) Sets the content width of this item.
void	setDefaultCommand(Command cmd) Sets default Command for this Item.
void	setDefaultCommand(Command cmd) Sets default Command for this Item.
void	setInitialized(boolean initialized) Sets the initialized state of this item.
void	setItemCommandListener(ItemCommandListener l) Sets a listener for Commands to this Item, replacing any previous ItemCommandListener.
void	setItemCommandListener(ItemCommandListener l) Sets a listener for Commands to this Item, replacing any previous ItemCommandListener.
void	setItemHeight(int height) Sets the item's complete height
void	setItemStateListener(ItemStateListener listener) Sets an ItemStateListener specifically for this item.
void	setItemTransition(ItemTransition transition)
void	setLabel(String label) Sets the label of the Item.
void	setLayout(int layout) Sets the layout directives for this item.
void	setNativeItem(NativeItem nativeItem) Species a native implementation for this item.
void	setParent(Item parent) Sets a parent for this item.
void	setParent(Item parent) Sets a parent for this item.
void	setpreferredSize(int width, int height) Sets the preferred width and height for this Item.
void	setStyle() Sets the style for an item with the use of style preprocessing e.g.: //#style myStyle setStyle();
void	setStyle(Style style) Sets the style of this item.
void	setStyle(Style style, boolean resetStyle) Sets the style of this item for animatable CSS attributes.
void	setUiEventListener(UiEventListener listener) Sets an UiEventListener for the this item and its children.
void	setView(ItemView view) Sets the view type for this item.
void	setVisible(boolean visible) Sets the visible status of this item.
void	show(Display display) Shows the screen to which item belongs to and focusses this item.
void	showCommands() Shows the commands on the screen.
protected void	showNotify() Called by the system to notify the item that it is now at least partially visible, when it previously had been completely invisible.
Image	toImage()
RgbImage	toRgbImage()
String	toString() Generates a String representation of this item.
void	updateInternalArea() Updates the internal area on BB and similar platforms that contain native fields.

Methods inherited from class javax.microedition.lcdui.CustomItem

getGameAction, getInteractionModes, invalidate, keyPressed, keyReleased, keyRepeated, pointerDragged, pointerPressed, pointerReleased, repaint, repaint, sizeChanged, traverse, traverseOut

Methods inherited from class javax.microedition.lcdui.Item

getPreferredHeight, getPreferredWidth, removeCommand, setPreferredSize

Methods inherited from class java.lang.Object

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

Field Detail

TRANSPARENT

public static final int TRANSPARENT

A J2ME Polish constant defining a transparent/invisible color. TRANSPARENT has the value -1.

See Also:

Constant Field Values

VERTICAL

public static final int VERTICAL

A J2ME Polish constant defining a vertical orientation. VERTICAL has the value 0.

See Also:

Constant Field Values

HORIZONTAL

public static final int HORIZONTAL

A J2ME Polish constant defining a horizontal orientation. HORIZONTAL has the value 1.

See Also:

Constant Field Values

LAYOUT_DEFAULT

public static final int LAYOUT_DEFAULT

A layout directive indicating that this Item should follow the default layout policy of its container.

Value 0 is assigned to LAYOUT_DEFAULT.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_LEFT

public static final int LAYOUT_LEFT

A layout directive indicating that this Item should have a left-aligned layout.

Value 1 is assigned to LAYOUT_LEFT.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_RIGHT

public static final int LAYOUT_RIGHT

A layout directive indicating that this Item should have a right-aligned layout.

Value 2 is assigned to LAYOUT_RIGHT.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_CENTER

public static final int LAYOUT_CENTER

A layout directive indicating that this Item should have a horizontally centered layout.

Value 3 is assigned to LAYOUT_CENTER.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_TOP

public static final int LAYOUT_TOP

A layout directive indicating that this Item should have a top-aligned layout.

Value 0x10 is assigned to LAYOUT_TOP.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_BOTTOM

public static final int LAYOUT_BOTTOM

A layout directive indicating that this Item should have a bottom-aligned layout.

Value 0x20 is assigned to LAYOUT_BOTTOM.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_VCENTER

public static final int LAYOUT_VCENTER

A layout directive indicating that this Item should have a vertically centered layout.

Value 0x30 is assigned to LAYOUT_VCENTER.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_NEWLINE_BEFORE

public static final int LAYOUT_NEWLINE_BEFORE

A layout directive indicating that this Item should be placed at the beginning of a new line or row.

Value 0x100 is assigned to LAYOUT_NEWLINE_BEFORE.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_NEWLINE_AFTER

public static final int LAYOUT_NEWLINE_AFTER

A layout directive indicating that this Item should the last on its line or row, and that the next Item (if any) in the container should be placed on a new line or row.

Value 0x200 is assigned to LAYOUT_NEWLINE_AFTER.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_SHRINK

public static final int LAYOUT_SHRINK

A layout directive indicating that this Item's width may be reduced to its minimum width.

Value 0x400 is assigned to LAYOUT_SHRINK

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_EXPAND

public static final int LAYOUT_EXPAND

A layout directive indicating that this Item's width may be increased to fill available space.

Value 0x800 is assigned to LAYOUT_EXPAND.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_VSHRINK

public static final int LAYOUT_VSHRINK

A layout directive indicating that this Item's height may be reduced to its minimum height.

Value 0x1000 is assigned to LAYOUT_VSHRINK.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_VEXPAND

public static final int LAYOUT_VEXPAND

A layout directive indicating that this Item's height may be increased to fill available space.

Value 0x2000 is assigned to LAYOUT_VEXPAND.

Since:

MIDP 2.0

See Also:

Constant Field Values

LAYOUT_2

public static final int LAYOUT_2

A layout directive indicating that new MIDP 2.0 layout rules are in effect for this Item. If this bit is clear, indicates that MIDP 1.0 layout behavior applies to this Item.

Value 0x4000 is assigned to LAYOUT_2.

Since:

MIDP 2.0

See Also:

Constant Field Values

PLAIN

public static final int PLAIN

An appearance mode value indicating that the Item is to have a normal appearance.

Value 0 is assigned to PLAIN.

Since:

MIDP 2.0

See Also:

Constant Field Values

HYPERLINK

public static final int HYPERLINK

An appearance mode value indicating that the Item is to appear as a hyperlink.

Value 1 is assigned to HYPERLINK.

Since:

MIDP 2.0

See Also:

Constant Field Values

BUTTON

public static final int BUTTON

An appearance mode value indicating that the Item is to appear as a button.

Value 2 is assigned to BUTTON.

Since:

MIDP 2.0

See Also:

Constant Field Values

INTERACTIVE

public static final int INTERACTIVE

A J2ME Polish appearance mode value indicating that the Item accepts input from the user.

Value 3 is assigned to INTERACTIVE.

See Also:

Constant Field Values

layout

protected int layout

itemCommandListener

protected ItemCommandListener itemCommandListener

defaultCommand

protected Command defaultCommand

preferredWidth

protected int preferredWidth

preferredHeight

protected int preferredHeight

cssWidth

protected Dimension cssWidth

cssHeight

protected Dimension cssHeight

minimumWidth

protected Dimension minimumWidth

minimumHeight

protected Dimension minimumHeight

maximumWidth

protected Dimension maximumWidth

maximumHeight

protected Dimension maximumHeight

minimumItemWidth

protected Dimension minimumItemWidth

minimumItemHeight

protected Dimension minimumItemHeight

maximumItemWidth

protected Dimension maximumItemWidth

maximumItemHeight

protected Dimension maximumItemHeight

background

public Background background

the background of this item

border

protected Border border

bgBorder

protected Border bgBorder

the background border of an item - this border is painted before the background. This field is only present when polish.css.bgborder is true.

style

protected Style style

itemWidth

public int itemWidth

the width of this item - only for read access

itemHeight

public int itemHeight

the height of this item - only for read access

paddingLeft

protected int paddingLeft

paddingTop

protected int paddingTop

paddingRight

protected int paddingRight

paddingBottom

protected int paddingBottom

paddingVertical

protected int paddingVertical

paddingHorizontal

protected int paddingHorizontal

marginLeft

protected int marginLeft

marginTop

protected int marginTop

marginRight

protected int marginRight

marginBottom

protected int marginBottom

contentWidth

protected int contentWidth

The width of this item's content

contentHeight

protected int contentHeight

The height of this item's content

availContentWidth

protected int availContentWidth

availContentHeight

protected int availContentHeight

backgroundWidth

protected int backgroundWidth

backgroundHeight

protected int backgroundHeight

appearanceMode

public int appearanceMode

The appearance mode of this item, either PLAIN or one of the interactive modes BUTTON, HYPERLINK or INTERACTIVE.

screen

protected Screen screen

The screen to which this item belongs to.

cssSelector

protected String cssSelector

The appropriate CSS selector of this item. This is either the style's name or a selector depending on the state of this item. A StringItem can have the selector "p", "a" or "button", for example. This variable can only be used, when the proprocessing variable "polish.useDynamicStyles" is defined.

isStyleInitialised

protected boolean isStyleInitialised

Determines whether the style has be dynamically assigned already.

parent

protected Item parent

The parent of this item.

commands

protected ArrayList commands

isLayoutCenter

protected boolean isLayoutCenter

isLayoutExpand

protected boolean isLayoutExpand

isLayoutRight

protected boolean isLayoutRight

relativeX

public int relativeX

the horizontal start position relative to it's parent's item left content edge

relativeY

public int relativeY

the vertical start position of this item relative to it's parent item top content edge

contentX

protected int contentX

the horizontal position of this item's content relative to it's left edge (so for a left aligned item its marginLeft + border.widthLeft + paddingLeft

contentY

protected int contentY

the vertical position of this item's content relative to it's top edge

NO_POSITION_SET

public static final int NO_POSITION_SET

no internal position has been set for this item, value is -9999. This is used as a value for internalX to describe that the item has no intenal position set

See Also:

Constant Field Values

internalX

protected int internalX

The internal horizontal position of this item's content relative to it's left edge. When it is equal NO_POSITION_SET this item's internal position is not known. The internal position is useful for items that have a large content which needs to be scrolled, e.g. containers.

internalY

protected int internalY

the vertical position of this item's internal content relative to it's top edge

internalWidth

protected int internalWidth

The internal width of this item's content.

internalHeight

protected int internalHeight

The internal height of this item's content.

isFocused

public boolean isFocused

flag indicating whether this item is focused

beforeWidth

protected int beforeWidth

labelStyle

protected Style labelStyle

label

protected StringItem label

useSingleRow

protected boolean useSingleRow

indicates that label and content are positioned on the same row if true

_bbField

public net.rim.device.api.ui.Field _bbField

a blackberry specific internal field

focusedStyle

protected Style focusedStyle

isPressed

protected boolean isPressed

colSpan

protected int colSpan

rowSpan

protected int rowSpan

includeLabel

protected boolean includeLabel

completeBackground

protected Background completeBackground

completeBorder

protected Border completeBorder

completeBackgroundPadding

protected Dimension completeBackgroundPadding

backgroundYOffset

protected int backgroundYOffset

The vertical offset for the background, can be used for smoother scrolling, for example

view

protected ItemView view

preserveViewType

protected boolean preserveViewType

setView

protected boolean setView

isInvisible

protected boolean isInvisible

isShown

protected boolean isShown

opacity

protected int opacity

opacityRgbData

protected int[] opacityRgbData

opacityPaintNormally

protected boolean opacityPaintNormally

xAdjustment

protected Dimension xAdjustment

yAdjustment

protected Dimension yAdjustment

contentXAdjustment

protected Dimension contentXAdjustment

contentYAdjustment

protected Dimension contentYAdjustment

isContentVisible

protected boolean isContentVisible

cacheItemImage

public boolean cacheItemImage

isInlineLabel

protected boolean isInlineLabel

availableWidth

protected int availableWidth

availableHeight

protected int availableHeight

ignoreRepaintRequests

protected boolean ignoreRepaintRequests

landscapeStyle

protected Style landscapeStyle

portraitStyle

protected Style portraitStyle

nativeItem

protected NativeItem nativeItem

Constructor Detail

FakeCustomItem

protected FakeCustomItem()

Convenience constructor. Creates a new item without label, with a left aligned layout and Item.PLAIN appearance mode.

FakeCustomItem

protected FakeCustomItem(Style style)

Convenience constructor. Creates a new item without label, with a left aligned layout, an Item.PLAIN appearance mode and the given style.

Parameters:

style - the style for this item

FakeCustomItem

protected FakeCustomItem(String label,
                         int layout)

Convenience constructor. Creates a new item with the specified label and layout, an Item.PLAIN appearance mode and default style.

Parameters:

label - the label of this item

layout - the layout of this item

FakeCustomItem

protected FakeCustomItem(String label,
                         int layout,
                         int appearanceMode,
                         Style style)

Creates a new Item.

Parameters:

label - the label of this item

layout - the layout of this item

appearanceMode - the mode of this item, either Item.PLAIN or Item.INTERACTIVE (Item.BUTTON, Item.HYPERLINK, Item.INTERACTIVE)

style - the style of this item - contains the background, border etc.

Method Detail

getMinContentWidth

protected final int getMinContentWidth()

Default implementation of javax.microedition.lcdui.CustomItem method.

Specified by:

getMinContentWidth in class CustomItem

Returns:

the minimum content width in pixels

getMinContentHeight

protected final int getMinContentHeight()

Default implementation of javax.microedition.lcdui.CustomItem method.

Specified by:

getMinContentHeight in class CustomItem

Returns:

the minimum content height in pixels

getPrefContentWidth

protected final int getPrefContentWidth(int height)

Default implementation of javax.microedition.lcdui.CustomItem method.

Specified by:

getPrefContentWidth in class CustomItem

Parameters:

height - the tentative content height in pixels, or -1 if a tentative height has not been computed. J2ME Polish will always specify -1 as the height.

Returns:

the preferred content width in pixels

getPrefContentHeight

protected final int getPrefContentHeight(int width)

Default implementation of javax.microedition.lcdui.CustomItem method.

Specified by:

getPrefContentHeight in class CustomItem

Parameters:

width - the tentative content width in pixels, or -1 if a tentative width has not been computed

Returns:

the preferred content height in pixels

paint

protected final void paint(Graphics g,
                           int w,
                           int h)

Default implementation of javax.microedition.lcdui.CustomItem method.

Specified by:

paint in class CustomItem

Parameters:

g - the Graphics object to be used for rendering the item

w - current width of the item in pixels

h - current height of the item in pixels

setLabel

public void setLabel(String label)

Sets the label of the Item. If label is null, specifies that this item has no label.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

setLabel in class Item

Parameters:

label - - the label string

Throws:

IllegalStateException - - if this Item is contained within an Alert

See Also:

getLabel()

getLabel

public String getLabel()

Gets the label of this Item object.

Overrides:

getLabel in class Item

Returns:

the label string

See Also:

setLabel(java.lang.String)

getLabelItem

public Item getLabelItem()

Retrieves the label item that is used by this item.\

Returns:

the item or null when no item is used.

getLayout

public int getLayout()

Gets the layout directives used for placing the item.

Overrides:

getLayout in class Item

Returns:

a combination of layout directive values

Since:

MIDP 2.0

See Also:

setLayout(int)

setLayout

public void setLayout(int layout)

Sets the layout directives for this item.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

setLayout in class Item

Parameters:

layout - - a combination of layout directive values for this item

Throws:

IllegalArgumentException - - if the value of layout is not a bit-wise OR combination of layout directives

IllegalStateException - - if this Item is contained within an Alert

Since:

MIDP 2.0

See Also:

getLayout()

getAppearanceMode

public int getAppearanceMode()

Returns the appearance mode of this Item. See Appearance Modes.

Returns:

the appearance mode value, one of Item.PLAIN, Item.HYPERLINK, or Item.BUTTON

Since:

MIDP 2.0

setAppearanceMode

public void setAppearanceMode(int appearanceMode)

Sets the appearance mode of this item.

Parameters:

appearanceMode - the mode value, one of Item.PLAIN, Item.HYPERLINK, or Item.BUTTON

setView

public void setView(ItemView view)

Sets the view type for this item. Please note that this is only supported when view-type CSS attributes are used within your application.

Parameters:

view - the new view, use null to remove the current view

getView

public ItemView getView()

Retrieves the view type for this item. Please note that this is only supported when view-type CSS attributes are used within your application.

Returns:

the current view, may be null

getStyle

public Style getStyle()

Retrieves the style of this item.

Returns:

the style of this item.

setBackground

public void setBackground(Background background)

Sets a new background for this item.

Parameters:

background - the new background, use null for not showing a background

setBorder

public void setBorder(Border border)

Sets a new border for this item

Parameters:

border - the new border, use null for not showing a border

setStyle

public void setStyle()

Sets the style for an item with the use of style preprocessing e.g.: //#style myStyle setStyle();

setStyle

public void setStyle(Style style)

Sets the style of this item.

Parameters:

style - the new style for this item.

Throws:

NullPointerException - when style is null

getView

protected ItemView getView(ItemView viewType,
                           Style viewStyle)

Retrieves the view type for this item or instantiates a new one. Please note that this is only supported when view-type CSS attributes are used within your application.

Parameters:

viewType - the view registered in the style

viewStyle - the style

Returns:

the view, may be null

setStyle

public void setStyle(Style style,
                     boolean resetStyle)

Sets the style of this item for animatable CSS attributes.

Parameters:

style - the new style for this element.

resetStyle - true when style settings should be resetted. This is not the case when styles are animated, for example.

Throws:

NullPointerException - when style is null

getItemWidth

public int getItemWidth(int firstLineWidth,
                        int availWidth)

Retrieves the complete width of this item. Note that the width can dynamically change, e.g. when a StringItem gets a new text.

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the maximum visible width of any following lines

Returns:

the complete width of this item.

getItemWidth

public int getItemWidth(int firstLineWidth,
                        int availWidth,
                        int availHeight)

Retrieves the complete width of this item. Note that the width can dynamically change, e.g. when a StringItem gets a new text.

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the maximum visible width of any following lines

availHeight - the maximum visible height, -1 if unknown

Returns:

the complete width of this item.

getItemHeight

public int getItemHeight(int firstLineWidth,
                         int availWidth)

Retrieves the complete height of this item. Note that the width can dynamically change, e.g. when a new style is set.

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the maximum visible width of any following lines

Returns:

the complete heigth of this item.

getItemHeight

public int getItemHeight(int firstLineWidth,
                         int availWidth,
                         int availHeight)

Retrieves the complete height of this item. Note that the width can dynamically change, e.g. when a new style is set.

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the maximum visible width of any following lines

availHeight - the maximum visible height, -1 if unknown

Returns:

the complete heigth of this item.

addCommand

public void addCommand(Command cmd)

Adds a command to this item

Overrides:

addCommand in class Item

Parameters:

cmd - the command

addCommand

public void addCommand(Command cmd)

Adds a context sensitive Command to the item. The semantic type of Command should be ITEM. The implementation will present the command only when the item is active, for example, highlighted.

If the added command is already in the item (tested by comparing the object references), the method has no effect. If the item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

cmd - the command to be added

Throws:

IllegalStateException - if this Item is contained within an Alert

NullPointerException - if cmd is null

Since:

MIDP 2.0

addCommand

public void addCommand(Command cmd,
                       Style commandStyle)

Adds a context sensitive Command to the item. The semantic type of Command should be ITEM. The implementation will present the command only when the item is active, for example, highlighted.

If the added command is already in the item (tested by comparing the object references), the method has no effect. If the item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

cmd - the command to be added

commandStyle - the style of the command, for the moment this is ignored

Throws:

IllegalStateException - if this Item is contained within an Alert

NullPointerException - if cmd is null

Since:

MIDP 2.0

removeCommand

public void removeCommand(Command cmd)

Removes the context sensitive command from item. If the command is not in the Item (tested by comparing the object references), the method has no effect. If the Item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so. If the command to be removed happens to be the default command, the command is removed and the default command on this Item is set to null. The following code:

 // Command c is the default command on Item item
 item.removeCommand(c);
 

is equivalent to the following code:

 // Command c is the default command on Item item
 item.setDefaultCommand(null);
 item.removeCommand(c);
 

Parameters:

cmd - - the command to be removed

Since:

MIDP 2.0

repaintFully

protected void repaintFully()

Repaints the complete screen to which this item belongs to. Subclasses can call this method whenever their contents have changed and they need an immediate refresh.

See Also:

CustomItem.repaint(), CustomItem.repaint(int, int, int, int)

getBorderWidthLeft

protected int getBorderWidthLeft()

Retrieves the border width.

Returns:

the border for the left side in pixels

getBorderWidthRight

protected int getBorderWidthRight()

Retrieves the border width.

Returns:

the border for the right side in pixels

getBorderWidthTop

protected int getBorderWidthTop()

Retrieves the border width.

Returns:

the border for the top side in pixels

getBorderWidthBottom

protected int getBorderWidthBottom()

Retrieves the border width.

Returns:

the border for the bottom side in pixels

requestInit

public void requestInit()

Requests that this item and all its parents are to be re-initialised, if the size of this item has been changed. All parents of this item are notified, too. This method should be called when an item changes its size more than usual.

getScreen

public Screen getScreen()

Retrieves the screen to which this item belongs to.

Returns:

either the corresponding screen or null when no screen could be found

setItemCommandListener

public void setItemCommandListener(ItemCommandListener l)

Sets a listener for Commands to this Item, replacing any previous ItemCommandListener. A null reference is allowed and has the effect of removing any existing listener. When no listener is registered, J2ME Polish notifies the command-listener of the current screen, when an item command has been selected.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

l - the new listener, or null.

Throws:

IllegalStateException - if this Item is contained within an Alert

Since:

MIDP 2.0

setItemCommandListener

public void setItemCommandListener(ItemCommandListener l)

Sets a listener for Commands to this Item, replacing any previous ItemCommandListener. A null reference is allowed and has the effect of removing any existing listener. When no listener is registered, J2ME Polish notifies the command-listener of the current screen, when an item command has been selected.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

setItemCommandListener in class Item

Parameters:

l - the new listener, or null.

Throws:

IllegalStateException - if this Item is contained within an Alert

Since:

MIDP 2.0

getItemCommandListener

public ItemCommandListener getItemCommandListener()

Gets the listener for Commands to this Item. When no listener is registered, null is returned

It is illegal to call this method if this Item is contained within an Alert.

Returns:

the ItemCommandListener associated with this item

setItemStateListener

public void setItemStateListener(ItemStateListener listener)

Sets an ItemStateListener specifically for this item. Change events are forwarded to both this listener as well as a possibly set listener of the corresponding screen.

Parameters:

listener - the listener which is set specifically for this item.

getItemStateListener

public ItemStateListener getItemStateListener()

Gets an ItemStateListener specifically for this item. Change events are forwarded to both this listener as well as a possibly set listener of the corresponding screen.

Returns:

the listener which has been set specifically for this item.

getpreferredWidth

public int getpreferredWidth()

Gets the preferred width of this Item. If the application has locked the width to a specific value, this method returns that value. Otherwise, the return value is computed based on the Item's contents, possibly with respect to the Item's preferred height if it is locked. See Item Sizes for a complete discussion.

Returns:

the preferred width of the Item

Since:

MIDP 2.0

See Also:

getpreferredHeight(), setpreferredSize(int, int)

getpreferredHeight

public int getpreferredHeight()

Gets the preferred height of this Item. If the application has locked the height to a specific value, this method returns that value. Otherwise, the return value is computed based on the Item's contents, possibly with respect to the Item's preferred width if it is locked. See Item Sizes for a complete discussion.

Returns:

the preferred height of the Item

Since:

MIDP 2.0

See Also:

getpreferredWidth(), setpreferredSize(int, int)

setpreferredSize

public void setpreferredSize(int width,
                             int height)

Sets the preferred width and height for this Item. Values for width and height less than -1 are illegal. If the width is between zero and the minimum width, inclusive, the minimum width is used instead. If the height is between zero and the minimum height, inclusive, the minimum height is used instead.

Supplying a width or height value greater than the minimum width or height locks that dimension to the supplied value. The implementation may silently enforce a maximum dimension for an Item based on factors such as the screen size. Supplying a value of -1 for the width or height unlocks that dimension. See Item Sizes for a complete discussion.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

width - - the value to which the width should be locked, or -1 to unlock

height - - the value to which the height should be locked, or -1 to unlock

Throws:

IllegalArgumentException - - if width or height is less than -1

IllegalStateException - - if this Item is contained within an Alert

Since:

MIDP 2.0

See Also:

getpreferredHeight(), getpreferredWidth()

getMinimumWidth

public int getMinimumWidth()

Gets the minimum width for this Item. This is a width at which the item can function and display its contents, though perhaps not optimally. See Item Sizes for a complete discussion.

Overrides:

getMinimumWidth in class Item

Returns:

the minimum width of the item

Since:

MIDP 2.0

getMinimumWidth

public int getMinimumWidth(int availWidth)

Gets the minimum width for this Item.

Parameters:

availWidth - the available width for percentage calculations

Returns:

the minimum width of the item

Since:

MIDP 2.0

getMinimumHeight

public int getMinimumHeight()

Gets the minimum height for this Item. This is a height at which the item can function and display its contents, though perhaps not optimally. See Item Sizes for a complete discussion.

Overrides:

getMinimumHeight in class Item

Returns:

the minimum height of the item

Since:

MIDP 2.0

getMinimumHeight

public int getMinimumHeight(int availHeight)

Gets the minimum height for this Item.

Parameters:

availHeight - the available height for percentage calculations

Returns:

the minimum height of the item

Since:

MIDP 2.0

getMaximumWidth

public int getMaximumWidth()

Gets the maximum width for this Item. This is a height at which the item can function and display its contents, though perhaps not optimally. See Item Sizes for a complete discussion.

Returns:

the minimum height of the item

Since:

MIDP 2.0

getMaximumWidth

public int getMaximumWidth(int availWidth)

Gets the maximum width for this Item.

Parameters:

availWidth - the available height for percentage calculations

Returns:

the minimum height of the item

Since:

MIDP 2.0

getMaximumHeight

public int getMaximumHeight()

Gets the maximum height for this Item. This is a height at which the item can function and display its contents, though perhaps not optimally. See Item Sizes for a complete discussion.

Returns:

the minimum height of the item

Since:

MIDP 2.0

getMaximumHeight

public int getMaximumHeight(int availHeight)

Gets the maximum height for this Item.

Parameters:

availHeight - the available height for percentage calculations

Returns:

the minimum height of the item

Since:

MIDP 2.0

setDefaultCommand

public void setDefaultCommand(Command cmd)

Sets default Command for this Item. If the Item previously had a default Command, that Command is no longer the default, but it remains present on the Item.

If not null, the Command object passed becomes the default Command for this Item. If the Command object passed is not currently present on this Item, it is added as if addCommand(javax.microedition.lcdui.Command) had been called before it is made the default Command, unless the "polish.Item.suppressDefaultCommand" preprocessing variable is set to "true".

If null is passed, the Item is set to have no default Command. The previous default Command, if any, remains present on the Item.

It is illegal to call this method if this Item is contained within an Alert.

Parameters:

cmd - the command to be used as this Item's default Command, or null if there is to be no default command

Throws:

IllegalStateException - - if this Item is contained within an Alert

Since:

MIDP 2.0

setDefaultCommand

public void setDefaultCommand(Command cmd)

Sets default Command for this Item.

Overrides:

setDefaultCommand in class Item

Parameters:

cmd - the command to be used as this Item's default Command, or null if there is to be no default command

notifyStateChanged

public void notifyStateChanged()

Causes this Item's containing Form to notify the Item's ItemStateListener. The application calls this method to inform the listener on the Item that the Item's state has been changed in response to an action. Even though this method simply causes a call to another part of the application, this mechanism is useful for decoupling the implementation of an Item (in particular, the implementation of a CustomItem, though this also applies to subclasses of other items) from the consumer of the item.

If an edit was performed by invoking a separate screen, and the editor now wishes to "return" to the form which contained the selected Item, the preferred method is Display.setCurrent(Item) instead of Display.setCurrent(Displayable), because it allows the Form to restore focus to the Item that initially invoked the editor.

In order to make sure that the documented behavior of ItemStateListener is maintained, it is up to the caller (application) to guarantee that this function is not called unless:

• the Item's value has actually been changed, and
• the change was the result of a user action (an "edit") and NOT as a result of state change via calls to Item's APIs

The call to ItemStateListener.itemStateChanged may be delayed in order to be serialized with the event stream. The notifyStateChanged method does not block awaiting the completion of the itemStateChanged method.

Overrides:

notifyStateChanged in class Item

Throws:

IllegalStateException - if the Item is not owned by a Form

Since:

MIDP 2.0

notifyValueChanged

protected void notifyValueChanged(Object newValue)

Notifies this item about a change event, e.g. when the text of a StringItem has been changed or similar. In contrast to notifyStateChanged() this method is also called when the change is not user initiated, i.e. when the application itself changes the value. The default implementation notfies native UI items about the change and fires an Event when either CSS animations are used or when the preprocessing variable polish.handleEvents is set to true.

Parameters:

newValue - the changed value of this object

See Also:

notifyStateChanged()

paint

public void paint(int x,
                  int y,
                  int leftBorder,
                  int rightBorder,
                  Graphics g)

Paints this item on the screen. This method should normally not be overriden. Override it only when you know what you are doing!

Parameters:

x - the left start position of this item.

y - the top start position of this item.

leftBorder - the left border, nothing must be painted left of this position

rightBorder - the right border, nothing must be painted right of this position, rightBorder > x >= leftBorder

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

paintCommands

protected void paintCommands(int x,
                             int y,
                             Graphics g)

Paints the commands for this item after the user has pressed/clicked on an item for a long time. Note that the preproessing variable polish.Item.ShowCommandsOnHold needs to be set to true for this feature.

Parameters:

x - horizontal left start position

y - vertical top start position

g - the graphics context

paintBackgroundAndBorder

protected void paintBackgroundAndBorder(int x,
                                        int y,
                                        int width,
                                        int height,
                                        Graphics g)

Paints the background and border of this item. The call is forwarded to paintBackground() and paintBorder().

Parameters:

x - the horizontal start position

y - the vertical start position

width - the width

height - the height

g - graphics context

See Also:

paintBackground(int, int, int, int, Graphics), paintBorder(int, int, int, int, Graphics)

paintBorder

protected void paintBorder(int x,
                           int y,
                           int width,
                           int height,
                           Graphics g)

Paints the border of this item.

Parameters:

x - the horizontal start position

y - the vertical start position

width - the width

height - the height

g - graphics context

paintBackground

protected void paintBackground(int x,
                               int y,
                               int width,
                               int height,
                               Graphics g)

Paints the background and - if defined - the bgborder of this item.

Parameters:

x - the horizontal start position

y - the vertical start position

width - the width

height - the height

g - graphics context

paintFilter

protected RgbImage paintFilter(int x,
                               int y,
                               RgbFilter[] partFilters,
                               RgbImage rgbImage,
                               int lo,
                               Graphics g)

Paints the given filters and retrieves the last processed RGB image.

Parameters:

x - horizontal paint position

y - vertical paint position

partFilters - the filters

rgbImage - the initial RGB image

lo - the layout for the processed RGB image

g - the graphics context

Returns:

the processed RGB image

init

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

Initialises this item. You should always call super.init( firstLineWidth, lineWidth) when overriding this method. This method call either ItemView.initContent() or Item.initContent() to initialize the actual content. A valid case for overriding would be if additional initialization needs to be done even when an ItemView is associated with this Item. Usually implementing initContent() should suffice.

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the maximum width of any following lines

availHeight - the maximum height that can be used without scrolling

See Also:

initContent(int, int, int), ItemView.initContent(Item, int, int, int)

initLayout

protected void initLayout(Style style,
                          int availWidth)

initMargin

protected void initMargin(Style style,
                          int availWidth)

Initializes the margin of this 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 this item Subclasses can override this (e.g. the container embedded in a screen)

Parameters:

style - the style

availWidth - the available width

setContentWidth

protected void setContentWidth(int width)

Sets the content width of this item. 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

initStyle

protected void initStyle()

Initialises the appropriate style for this item.

initContent

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

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

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the available maximum width of this item in pixels

availHeight - the available maximum height of this item in pixels

See Also:

contentWidth, contentHeight, preferredWidth, preferredHeight

paintContent

protected abstract void paintContent(int x,
                                     int y,
                                     int leftBorder,
                                     int rightBorder,
                                     Graphics g)

Paints the content of this item. The background has already been painted and the border will be added after this method returns.

Parameters:

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.

createCssSelector

protected abstract String createCssSelector()

Retrieves the CSS selector for this item. The CSS selector is used for the dynamic assignment of styles - that is the styles are assigned by the usage of the item and not by a predefined style-name. With the #style preprocessing command styles are set fix, this method yields in a faster GUI and is recommended. When in a style-sheet dynamic styles are used, e.g. "Form>p", than the selector of the item is needed.
This abstract method needs only be implemented, when dynamic styles are used: #ifdef polish.useDynamicStyles
The returned selector needs to be in lower case.

Returns:

the appropriate CSS selector for this item. The selector needs to be in lower case.

handleKeyPressed

protected boolean handleKeyPressed(int keyCode,
                                   int gameAction)

Handles the key-pressed event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation just handles the FIRE game-action when a default-command and an item-command-listener have been registered.

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

handleKeyRepeated

protected boolean handleKeyRepeated(int keyCode,
                                    int gameAction)

Handles the key-repeated event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation forwards the event to the handleKeyPressed method.

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

See Also:

handleKeyPressed(int, int)

handleKeyReleased

protected boolean handleKeyReleased(int keyCode,
                                    int gameAction)

Handles the key-released event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation invokes the default command if one is present

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

See Also:

handleKeyPressed(int, int)

notifyVisited

public void notifyVisited()

Is called when this item has been visited.

notifyUnvisited

public void notifyUnvisited()

Is called when the visited state of this item should be reset.

notifyItemPressedStart

public boolean notifyItemPressedStart()

Is called when an item is pressed using the FIRE game action

Returns:

true when the item requests a repaint after this action

isPressed

public boolean isPressed()

Determines whether this item is currently pressed.

Returns:

true when this item is pressed

isFocused

public boolean isFocused()

Determines whether this item is currently focused.

Returns:

true when this item is focused

notifyItemPressedEnd

public void notifyItemPressedEnd()

Is called when an item is pressed

isInContentArea

public boolean isInContentArea(int relX,
                               int relY)

Determines whether the given relative x/y position is inside of this item's (visible) content area. Subclasses which extend their area over the declared/official content area, which is determined in the initContent() method (like popup items), might want to override this method or possibly the getContentX(), getContentY() methods. It is assumed that the item has been initialized before.

Parameters:

relX - the x position relative to this item's left position

relY - the y position relative to this item's top position

Returns:

true when the relX/relY coordinate is within this item's content area.

See Also:

initContent(int, int, int)

isInContentWithPaddingArea

public boolean isInContentWithPaddingArea(int relX,
                                          int relY)

Determines whether the given relative x/y position is inside of this item's content area. Subclasses which extend their area over the declared/official content area, which is determined in the initContent() method (like popup items), might want to override this method or possibly the getContentX(), getContentY() methods. It is assumed that the item has been initialized before.

Parameters:

relX - the x position relative to this item's left position

relY - the y position relative to this item's top position

Returns:

true when the relX/relY coordinate is within this item's content + padding area.

See Also:

initContent(int, int, int)

isInItemArea

public boolean isInItemArea(int relX,
                            int relY)

Determines whether the given relative x/y position is inside of this item's area including paddings, margins and label. Subclasses which extend their area over the declared/official content area, which is determined in the initContent() method (like popup items), might want to override this method. It is assumed that the item has been initialized before.

Parameters:

relX - the x position relative to this item's left position

relY - the y position relative to this item's top position

Returns:

true when the relX/relY coordinate is within this item's area.

See Also:

initContent(int, int, int)

isInItemArea

public boolean isInItemArea(int relX,
                            int relY,
                            Item child)

Determines whether the given relative x/y position is inside of the specified child item's area including paddings, margins and label. Subclasses which extend their area over the declared/official content area, which is determined in the initContent() method (like popup items), might want to override this method. It is assumed that the item has been initialized before.

Parameters:

relX - the x position relative to this item's left content position

relY - the y position relative to this item's top content position

child - the child

Returns:

true when the relX/relY coordinate is within the child item's area.

handlePointerPressed

protected boolean handlePointerPressed(int relX,
                                       int relY)

Handles the event when a pointer has been pressed at the specified position. The default method discards this event when relX/relY is outside of the item's area. When the event took place inside of the content area, the pointer-event is translated into an artificial FIRE game-action keyPressed event, which is subsequently handled by the handleKeyPressed(-1, Canvas.FIRE) method. This method needs should be overwritten only when the "polish.hasPointerEvents" preprocessing symbol is defined: "//#ifdef polish.hasPointerEvents".

Parameters:

relX - the x position of the pointer pressing relative to this item's left position

relY - the y position of the pointer pressing relative to this item's top position

Returns:

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

See Also:

this method is used for determining whether the event belongs to this item, for a helper method for determining whether the event took place into the actual content area, handleKeyPressed(int, int), for calculating the horizontal position relative to the content (relX - contentX), for calculating the vertical position relative to the content (relY - contentY)

handlePointerReleased

protected boolean handlePointerReleased(int relX,
                                        int relY)

Handles the event when a pointer has been released at the specified position. The default method discards this event when relX/relY is outside of the item's area. When the event took place inside of the content area, the pointer-event is translated into an artificial FIRE game-action keyReleased event, which is subsequently handled bu the handleKeyPressed(-1, Canvas.FIRE) method. This method needs should be overwritten only when the "polish.hasPointerEvents" preprocessing symbol is defined: "//#ifdef polish.hasPointerEvents".

Parameters:

relX - the x position of the pointer pressing relative to this item's left position

relY - the y position of the pointer pressing relative to this item's top position

Returns:

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

See Also:

this method is used for determining whether the event belongs to this item, for a helper method for determining whether the event took place into the actual content area, handleKeyPressed(int, int), for calculating the horizontal position relative to the content (relX - contentX), for calculating the vertical position relative to the content (relY - contentY)

handlePointerDragged

protected boolean handlePointerDragged(int relX,
                                       int relY)

Handles the dragging/movement of a pointer. This method should be overwritten only when the polish.hasPointerEvents preprocessing symbol is defined. The default implementation returns false.

Parameters:

relX - the x position of the pointer pressing relative to this item's left position

relY - the y position of the pointer pressing relative to this item's top position

Returns:

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

handlePointerDragged

protected boolean handlePointerDragged(int relX,
                                       int relY,
                                       ClippingRegion repaintRegion)

Handles the dragging/movement of a pointer. This method should be overwritten only when the polish.hasPointerEvents preprocessing symbol is defined. The default implementation returns false.

Parameters:

relX - the x position of the pointer pressing relative to this item's left position

relY - the y position of the pointer pressing relative to this item's top position

Returns:

true when the dragging 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 this item's left position

y - the vertical pixel position of the touch event relative to this 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 this item's left position

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

Returns:

true when the event was handled

handleGesture

protected boolean handleGesture(int gesture,
                                int x,
                                int y)

Handles a touch gestures. Note that touch gesture support needs to be activated using the preprocessing variable polish.supportGestures. The default implementation calls handleGestureHold() in case GESTURE_HOLD is specified.

Parameters:

gesture - the gesture identifier, e.g. GESTURE_HOLD

Returns:

true when this gesture was handled

See Also:

handleGestureHold(int, int)

handleGestureHold

protected boolean handleGestureHold(int x,
                                    int y)

Handles the hold touch gestures. Note that touch gesture support needs to be activated using the preprocessing variable polish.supportGestures The default implementation shows the commands of this item, but only when the preprocessing variable polish.Item.ShowCommandsOnHold is set to true.

Returns:

true when this gesture was handled

handleGestureSwipeLeft

protected boolean handleGestureSwipeLeft(int x,
                                         int y)

Handles the swipe left gesture.

Returns:

true when the gesture was handled

handleGestureSwipeRight

protected boolean handleGestureSwipeRight(int x,
                                          int y)

Handles the swipe right gesture.

Returns:

true when the gesture was handled

addRepaintArea

public void addRepaintArea(ClippingRegion repaintRegion)

Adds a repaint request for this item's space.

Parameters:

repaintRegion - the clipping rectangle to which the repaint area should be added

addRelativeToContentRegion

public void addRelativeToContentRegion(ClippingRegion repaintRegion,
                                       int x,
                                       int y,
                                       int width,
                                       int height)

Adds a region relative to this item's content x/y start position.

Parameters:

repaintRegion - the clipping region

x - horizontal start relative to this item's content position

y - vertical start relative to this item's content position

width - width

height - height

See Also:

getContentWidth(), getContentHeight()

addRelativeToBackgroundRegion

public void addRelativeToBackgroundRegion(ClippingRegion repaintRegion,
                                          int x,
                                          int y,
                                          int width,
                                          int height)

Adds a region relative to this item's background x/y start position.

Parameters:

repaintRegion - the clipping region

x - horizontal start relative to this item's background position

y - vertical start relative to this item's background position

width - width

height - height

See Also:

getBackgroundWidth(), getBackgroundHeight()

addRelativeToBackgroundRegion

public void addRelativeToBackgroundRegion(Background animatedBackground,
                                          Border animatedBorder,
                                          ClippingRegion repaintRegion,
                                          int x,
                                          int y,
                                          int width,
                                          int height)

Adds a region relative to this item's background x/y start position.

Parameters:

animatedBackground - the background that requests the repaint (could be a complete-background), can be null

animatedBorder - the border that requests the repaint (could be a complete-border), can be null

repaintRegion - the clipping region

x - horizontal start relative to this item's background position

y - vertical start relative to this item's background position

width - width

height - height

See Also:

getBackgroundWidth(), getBackgroundHeight()

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:

addRelativeToContentRegion(ClippingRegion, int, int, int, int)

animate

public boolean animate()

Animates this item. Subclasses can override this method to create animations. The default implementation returns false

Returns:

true when this item has been animated.

See Also:

animate(long, ClippingRegion)

getFocusedStyle

public Style getFocusedStyle()

Retrieves the approriate style for focusing this item. This is either a item specific one or one inherit by its parents. When no parent has a specific focus style, the StyleSheet.focusedStyle is used.

Returns:

the style used for focussing this item.

focus

protected Style focus(Style newStyle,
                      int direction)

Focuses this item.

Parameters:

newStyle - the style which is used to indicate the focused state

direction - the direction from which this item is focused, either Canvas.UP, Canvas.DOWN, Canvas.LEFT, Canvas.RIGHT or 0. When 0 is given, the direction is unknown.

Returns:

the current style of this item

showCommands

public void showCommands()

Shows the commands on the screen.

addCommands

protected void addCommands(ArrayList commandsList)

Adds all commands to the specified list.

Parameters:

commandsList - an ArrayList into which the commands from this item should be added.

handleCommand

protected boolean handleCommand(Command cmd)

Tries to handle the specified command. The item checks if the command belongs to this item and if it has an associated ItemCommandListener. Only then it handles the command.

Parameters:

cmd - the command

Returns:

true when the command has been handled by this item

handleCommand

protected boolean handleCommand(Command cmd)

Tries to handle the specified command. The item checks if the command belongs to this item and if it has an associated ItemCommandListener. Only then it handles the command.

Parameters:

cmd - the command

Returns:

true when the command has been handled by this item

defocus

protected void defocus(Style originalStyle)

Removes the focus from this item.

Parameters:

originalStyle - the original style which will be restored.

showNotify

protected void showNotify()

Called by the system to notify the item that it is now at least partially visible, when it previously had been completely invisible. The item may receive paint() calls after showNotify() has been called.

The default implementation of this method sets the isShown field to true and calls showNotify on style elements.

Overrides:

showNotify in class CustomItem

hideNotify

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

The default implementation of this method sets the isShown field to false and calls hideNotify on style elements.

Overrides:

hideNotify in class CustomItem

show

public void show(Display display)

Shows the screen to which item belongs to and focusses this item. This method is the equivalent to display.setCurrentItem( item ).

Parameters:

display - the display of the MIDlet.

releaseResources

public void releaseResources()

Releases all (memory intensive) resources such as images or RGB arrays of this item. The default implementation releases any background resources.

destroy

public void destroy()

Destroy the item by removing all references to parent, screen, listeners etc. and calling releaseResources()

setAttribute

public void setAttribute(Object key,
                         Object value)

Sets an arbitrary attribute for this item.

Parameters:

key - the key for the attribute

value - the attribute value

getAttribute

public Object getAttribute(Object key)

Gets an previously added attribute of this item.

Parameters:

key - the key of the attribute

Returns:

the attribute value, null if none has been registered under the given key before

removeAttribute

public Object removeAttribute(Object key)

Removes an previously added attribute of this item.

Parameters:

key - the key of the attribute

Returns:

the attribute value, null if none has been registered under the given key before

getAttributes

public HashMap getAttributes()

Returns a HashMap object with all registered attributes.

Returns:

a HashMap object with all attribute key/value pairs, null if no attribute was stored before.

getItemAt

public Item getItemAt(int relX,
                      int relY)

Determines if this item or one of it's children is within the specified point. The default implementation returns this item or this item's label when the position fits.

Parameters:

relX - the x position of the point relative to this item's left position

relY - the y position of the point relative to this item's top position

Returns:

this item or one of it's children, when the position fits, otherwise null is returned

getAbsoluteX

public int getAbsoluteX()

Retrieves this item's current absolute horizontal position

Returns:

the absolute x position of this item in pixel.

getAbsoluteY

public int getAbsoluteY()

Retrieves this item's current absolute vertical position

Returns:

the absolute y position of this item in pixel.

setAbsoluteY

public void setAbsoluteY(int absY)

Sets the absolute vertical position of this item. Note that results may vary depending on the view-type of the root container.

Parameters:

absY - the absolute y position of this item in pixel.

getContentX

public int getContentX()

Retrieves the start of the content relative to this item's absolute x position.

Returns:

the horizontal start of the content

See Also:

getAbsoluteX()

getContentY

public int getContentY()

Retrieves the start of the content relative to this item's absolute y position.

Returns:

the vertical start of the content

See Also:

getAbsoluteY()

getContentWidth

public int getContentWidth()

Retrieves the width of the content.

Returns:

the content width in pixels

getContentHeight

public int getContentHeight()

Retrieves the height of the content.

Returns:

the content height in pixels

getAvailableContentWidth

public int getAvailableContentWidth()

Retrieves the width of the content.

Returns:

the content width in pixels

getAvailableContentHeight

public int getAvailableContentHeight()

Retrieves the height of the content.

Returns:

the content height in pixels

getItemAreaHeight

public int getItemAreaHeight()

Retrieves the height of the area that this item covers. This can be different from the original itemHeight for items that have popups such as the POPUP ChoiceGroup

Returns:

the height of the item's area in pixel

getBackgroundX

public int getBackgroundX()

Retrieves the start of the background relative to this item's origin.

Returns:

the horizontal background start in pixels.

getBackgroundY

public int getBackgroundY()

Retrieves the start of the background relative to this item's origin.

Returns:

the horizontal background start in pixels.

getBackgroundWidth

public int getBackgroundWidth()

Retrieves the width of this item's background.

Returns:

the width in pixels

getBackgroundHeight

public int getBackgroundHeight()

Retrieves the height of this item's background.

Returns:

the height in pixels

getParent

public Item getParent()

Retrieves the parent of this item.

Returns:

this item's parent.

setParent

public void setParent(Item parent)

Sets a parent for this item.

Parameters:

parent - the parent of this item

setParent

public void setParent(Item parent)

Sets a parent for this item.

Parameters:

parent - the parent of this item

setVisible

public void setVisible(boolean visible)

Sets the visible status of this item. Invisible items occupy no space on the UI screen and cannot be focused/traversed. Note that you can call this method ONLY when the preprocessing variable polish.supportInvisibleItems is true or when you use the CSS attribute 'visible' in your polish.css file.

Parameters:

visible - true when this item should become visible.

isVisible

public boolean isVisible()

Gets the visible status of this item. Invisible items occupy no space on the UI screen and cannot be focused/traversed. Note that you can call this method ONLY when the preprocessing variable polish.supportInvisibleItems is true or when you use the 'visible' CSS attribute.

Returns:

true when this item is visible.

toString

public String toString()

Generates a String representation of this item. This method is only implemented when the logging framework is active or the preprocessing variable "polish.keepToString" is set to true.

Overrides:

toString in class Object

Returns:

a String representation of this item.

containsCommand

public boolean containsCommand(Command command)

Determines whether this item contains the given command.

Parameters:

command - the command

Returns:

true when this item contains this command

getDefaultCommand

public Command getDefaultCommand()

Returns:

the default command

getItemCommands

public ArrayList getItemCommands()

Returns:

the commands associated with this item in an arraylist - might be null!

setInitialized

public void setInitialized(boolean initialized)

Sets the initialized state of this item.

Parameters:

initialized - true when this item is deemed to be initialized, otherwise false. When setting to 'false' the item will run its init() and initContent() methods at the next option.

isInitialized

public boolean isInitialized()

Determines the initialization state of this item

Returns:

true when it is initialized, false otherwise

setItemHeight

public void setItemHeight(int height)

Sets the item's complete height

Parameters:

height - the height in pixel

getInternalX

public int getInternalX()

Retrieves the internal area's horizontal start relative to this item's content area

Returns:

the horizontal start in pixels, -1 if it not set

getInternalY

public int getInternalY()

Retrieves the internal area's vertical start relative to this item's content area

Returns:

the vertical start in pixels, -1 if it not set

getInternalWidth

public int getInternalWidth()

Retrieves the internal area's vertical width

Returns:

the vertical width in pixels, -1 if it not set

getInternalHeight

public int getInternalHeight()

Retrieves the internal area's vertical height

Returns:

the vertical height in pixels, -1 if it not set

fireEvent

public void fireEvent(String eventName,
                      Object eventData)

Fires an event for this item as well as its subitems like its label.

Parameters:

eventName - the name of the event

eventData - the event data

See Also:

EventManager.fireEvent(String, Object, Object)

updateInternalArea

public void updateInternalArea()

Updates the internal area on BB and similar platforms that contain native fields.

isLayoutRight

public boolean isLayoutRight()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a right layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutLeft

public boolean isLayoutLeft()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a left layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutCenter

public boolean isLayoutCenter()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a center layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutTop

public boolean isLayoutTop()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a top layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutBottom

public boolean isLayoutBottom()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a bottom layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutVerticalCenter

public boolean isLayoutVerticalCenter()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a vcenter layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutVerticalShrink

public boolean isLayoutVerticalShrink()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a vshrink layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutVerticalExpand

public boolean isLayoutVerticalExpand()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a vexpand layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutExpand

public boolean isLayoutExpand()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a horizontal expand layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutShrink

public boolean isLayoutShrink()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a horizontal shrink layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutNewlineAfter

public boolean isLayoutNewlineAfter()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a newwline-after layout.

See Also:

setLayout(int), init(int,int,int)

isLayoutNewlineBefore

public boolean isLayoutNewlineBefore()

Determines the layout of this item. Note that either setLayout() or init() has to be called before this method returns valid values.

Returns:

true when the item has a newwline-after layout.

See Also:

setLayout(int), init(int,int,int)

setItemTransition

public void setItemTransition(ItemTransition transition)

toImage

public Image toImage()

toRgbImage

public RgbImage toRgbImage()

isInteractive

public boolean isInteractive()

Determines whether this item is interactive and thus can be selected.

Returns:

true when this item is deemed to be interactive

onScreenSizeChanged

public void onScreenSizeChanged(int screenWidth,
                                int screenHeight)

Notifies this item about a new screen size. The default implementation just checks if the design should switch to portrait or landscape-style (if those CSS attributes are used). The item will be re-initialized with its available dimensions using init(int,int,int) soon.

Parameters:

screenWidth - the screen width

screenHeight - the screen height

getAvailableWidth

public int getAvailableWidth()

Retrieves the available width for this item.

Returns:

the available width in pixel, can be 0 when this item has not yet been initialized

getAvailableHeight

public int getAvailableHeight()

Retrieves the available height for this item.

Returns:

the available height in pixel, can be 0 when this item has not yet been initialized

setUiEventListener

public void setUiEventListener(UiEventListener listener)

Sets an UiEventListener for the this item and its children.

Parameters:

listener - the listener, use null to remove a listener

getUiEventListener

public UiEventListener getUiEventListener()

Retrieves the UiEventListener for this item or for one of its parents.

Returns:

the listener or null, if none has been registered

getRgbData

public int[] getRgbData()

Retrieves the RGB data of this item. This method only works on MIDP 2.0+ devices.

Returns:

the RGB data as an int array.

getRgbData

public int[] getRgbData(boolean supportTranslucency,
                        int rgbOpacity)

Retrieves the RGB data of this item. This method only works on MIDP 2.0+ devices.

Parameters:

supportTranslucency - true when not only transparent but also translucent parts of the item should be rendered correctly

rgbOpacity - The opacity of the item between 0 (fully transparent) and 255 (fully opaque)

Returns:

the RGB data as an int array.

setNativeItem

public void setNativeItem(NativeItem nativeItem)

Species a native implementation for this item. This method is only available when the preprocessing variable polish.useNativeGui is set to true.

Parameters:

nativeItem - the native implementation

getNativeItem

public NativeItem getNativeItem()

Species a native implementation for this item. This method is only available when the preprocessing variable polish.useNativeGui is set to true.

Returns:

the native implementation, can be null