javax.microedition.lcdui
Class IdleItem

java.lang.Object
  javax.microedition.lcdui.Item
      javax.microedition.lcdui.CustomItem
          javax.microedition.lcdui.IdleItem

public abstract class IdleItem
extends CustomItem

This class represents a dedicated UI component that can be used to render content to the idle screen.

Relationship to CustomItem

IdleItem is defined as a subclass of the CustomItem. The behavior of the IdleItem is the same as in CustomItem. The CustomItem is used because it provides rendering power and flexibility of the Canvas component and supports the concept of being embedded in a broader UI context. This provides support for negotiating size and location of content, and includes well-defined notions of focus traversal, both within the component and within the broader UI. These ideas are fundamental to content within an idle screen.

The two new methods added in this class provide the additional functionality needed in idle screen items. All other functionality is the same as in CustomItem.

As a subclass of CustomItem, IdleItem has no constrains to what kinds of content can be displayed in it. The MIDlet using IdleItem has just as much control over rendering as it has within a Canvas. Two additional methods are defined to allow greater ability to control the appearance of the IdleItem. Also, the semantics of the paint method are refined to allow MIDlet content to appear over the top of any user-selected wallpaper or background image in the idle screen.

Position and Size

The platform on the device decides how the IdleItem is positioned on the idle screen. However, it is important that IdleItem objects are able to request the amount of screen space they require, and to learn what space they have been provided. CustomItem defines a comprehensive set of methods for indicating the minimum and preferred sizes of items, as well as a means to determine what size they have available to them (via paint). All of these methods are directly applicable to IdleItem, and operate in just the same way as for CustomItem.

Focus, Traversal and Interaction Modes

CustomItem defines a sophisticated model for focus, internal traversal and scrolling in form items. This model is directly relevant to the IdleItem, and applies without modification.

A platform indicates what traversal is or is not possible on the idle screen through getInteractionModes method. This allows a MIDlet to determine whether internal traversal, key events and pointer events are supported on IdleItem.

Commands

As a subclass of Item it is possible for a MIDlet to add commands to an IdleItem. This allows MIDlets to have full softkey support and options menus associated with content on the idle screen. When the idle screen MIDlet receives focus, the commands attached to it MUST be visible in the softkeys.

Labels

As a subclass of Item it is possible for a MIDlet to associate a label with each IdleItem. The platform is free to use this label as appropriate, or to ignore the label if labels do not normally appear on the idle screen.

Painting and Appearance

Because IdleItem is a subclass of CustomItem, the painting model automatically provides a great deal of freedom to a MIDlet. Within the area of the IdleItem the MIDlet has absolute control over what is painted and how. It is perfectly feasible for a MIDlet to use services such as JSR184 for 3D content or JSR226 for SVG content to paint the idle screen content.

In addition the IdleItem provides a number of support methods that can be used to match the basic appearance and focus conventions of the platform. These revolve around three key issues:

• Drawing focus and highlight
• Background images/wallpaper
• Fonts and Colors used on the idle screen

Drawing focus and highlight

If the IdleItem contains more than one focusable element then it typically needs a way to indicate which element is focused.

Painting the idle item

On many platforms the content on the idle screen appears over the top of a user-selected background image or wallpaper. The Java content should be able to achieve the same affect. To achieve this an application should set the paintMode to false (transparent) with method CustomItem.setPaintMode method. If paintMode is false (transparent), the application can only paint the pixels it needs and the implementation handles the other pixels. If paintMode is true, application should render every pixel on the painted area.

Fonts and Colors

Accessory methods are provided to determine appropriate fonts (Font.getFont) and colors (Display.getColor) for use on the idle screen.

Relationship to Display

The Display.setIdleItem method is provided to allow a MIDlet to set, or clear, the IdleItem used on the display. Each MIDlet may have a single IdleItem associated with each Display, which may be used when/if the Display switches to an idle state.

The following example shows how a MIDlet should request to add content to the idle screen.

   public class MyIdleItem extends IdleItem { ... }

   // this code within the MIDlet...
   IdleItem idleItem = new MyIdleItem("For Idle Screen");
   Display d = Display.getDisplay(this);
   d.setIdleItem(idleItem); // new method in Display class
 

Visibility and Adding/Removing from Display events

The IdleItem receives showNotify and hideNotify events to indicate when it is actually visible on the idle screen. It also receives events to say when it is actually addedToDisplay or removedFromDisplay

Event Sequence

The relationship between these events is as follows:

1. MIDlet requests that a new IdleItem be added to a Display with setIdleItem
2. The IdleItem is informed when/if it actually becomes a part of the idle screen of a Display through a call to the addedToDisplay method. This always occurs before calls to showNotify and traverse.
3. The IdleItem is informed that it has become visible through showNotify. This event will only ever occur after a call to addedToDisplay, and before a call to traverse.
4. The IdleItem is informed that it has become focused through traverse.
5. The IdleItem is informed that it has lost the focus through traverseOut.
6. The IdleItem is informed that it is no longer visible through hideNotify. This event will always occur before a call to removedFromDisplay.
7. The IdleItem is informed when it is removed from the idle screen through a call to the removedFromDisplay method. This always occurs after calls to traverseOut and hideNotify.

Since:

MIDP 3.0

Field Summary

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

Fields inherited from class javax.microedition.lcdui.Item

BUTTON, HYPERLINK, LAYOUT_2, LAYOUT_BOTTOM, LAYOUT_CENTER, LAYOUT_DEFAULT, LAYOUT_EXPAND, LAYOUT_LEFT, LAYOUT_NEWLINE_AFTER, LAYOUT_NEWLINE_BEFORE, LAYOUT_RIGHT, LAYOUT_SHRINK, LAYOUT_TOP, LAYOUT_VCENTER, LAYOUT_VEXPAND, LAYOUT_VSHRINK, PLAIN

Constructor Summary

protected

IdleItem(java.lang.String label) Constructor, so that the IdleItem can specify its label.

Method Summary

protected void	addedToDisplay(Display display) Indicates that this IdleItem is part of the idle screen.
protected void	removedFromDisplay(Display display) Indicates that this IdleItem is no longer part of the idle screen.

Methods inherited from class javax.microedition.lcdui.CustomItem

getGameAction, getInteractionModes, getKeyCode, getMinContentHeight, getMinContentWidth, getPrefContentHeight, getPrefContentWidth, hideNotify, invalidate, keyPressed, keyReleased, keyRepeated, paint, pointerDragged, pointerPressed, pointerReleased, repaint, repaint, setKeyListener, setPaintMode, showNotify, sizeChanged, traverse, traverseOut

Methods inherited from class javax.microedition.lcdui.Item

addCommand, getCommands, getLabel, getLayout, getLayoutHint, getMinimumHeight, getMinimumWidth, getPreferredHeight, getPreferredWidth, notifyStateChanged, removeCommand, setCommand, setDefaultCommand, setItemCommandListener, setLabel, setLayout, setLayoutHint, setPreferredSize

Methods inherited from class java.lang.Object

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

Constructor Detail

IdleItem

protected IdleItem(java.lang.String label)

Constructor, so that the IdleItem can specify its label.

This constructor copies the signature of the CustomItem constructor which allows for a label to be defined. It is up to the platform how or even if this label is used.

Parameters:

label - the label for the IdleItem.

Method Detail

addedToDisplay

protected void addedToDisplay(Display display)

Indicates that this IdleItem is part of the idle screen.

Display.setIdleItem does not guarantee that an IdleItem will become part of the idle screen for a display, it merely requests that this happens. This method is called to inform the IdleItem that it is actually part of the idle screen.

This method does not indicate that the IdleItem is visible. Visibility is handled separately with the standard showNotify method.

Parameters:

display - the Display this item was added to.

removedFromDisplay

protected void removedFromDisplay(Display display)

Indicates that this IdleItem is no longer part of the idle screen.

Called to indicate that the item is no longer part of the idle screen, either because the MIDlet or the user removed it.

Parameters:

display - the Display this was removed from.