FileDocCategorySizeDatePackage
Item.javaAPI DocJ2ME MIDP 2.055695Thu Nov 07 12:02:28 GMT 2002javax.microedition.lcdui

Item

public abstract class Item extends Object
A superclass for components that can be added to a {@link Form 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 {@link #setLayout} method and is the return value from the {@link #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 {@link #setPreferredSize 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 {@link #getPreferredWidth getPreferredWidth} and {@link #getPreferredHeight 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 {@link #addCommand} or {@link #setDefaultCommand} and if the Command has not been removed with a subsequent call to {@link #removeCommand}. 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 {@link #setDefaultCommand} 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.

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 {@link #PLAIN PLAIN}, {@link #HYPERLINK HYPERLINK}, or {@link #BUTTON 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

Fields Summary
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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

static final int
X
bounds[] array index to x coordinate
static final int
Y
bounds[] array index to y coordinate
static final int
WIDTH
bounds[] array index to width
static final int
HEIGHT
bounds[] array index to height
static final int
VALID_LAYOUT
internal bitmask representing a valid layout mask
int[]
bounds
An array of 4 elements, describing the x, y, width, height of this Item's bounds in the viewport coordinate space. If its null, it means the Item is currently not in the viewport
boolean
hasFocus
A flag indicating this Item has the input focus. This is maintained by the Item superclass for easy use by subclass code.
boolean
visible
A flag indicating this Item is currently (at least partially) visible on the Form it is on. This is maintained by the Item superclass for easy use by subclass code.
boolean
sizeChanged
A flag indicating the size of this Item has changed in a subsequent layout operation
ItemCommandListener
commandListener
commandListener that has to be notified of when ITEM command is activated
String
label
The label of this Item
Screen
owner
The owner Screen for this Item
int
layout
The layout type of this Item
Command
defaultCommand
This is a default Command which represents the callback to a selection event.
int
numCommands
The number of Commands added to this Item
int
lockedWidth
The locked width of this Item, -1 by default
int
lockedHeight
The locked height of this Item, -1 by default
static final boolean
LABEL_BOLD_ON_TRAVERSE
A flag signaling how labels are painted. If true, labels are only painted bold on traverse, else they are always painted bold
static final int
BUTTON_PAD
Padding used between Button Border and ImageItem
static final int
BUTTON_BORDER
Button Border is 3 pixel wide and 3 pixel high
static final int
LIGHT_GRAY_COLOR
Button border color for light gray border
static final int
DARK_GRAY_COLOR
Button border color for dark gray border
static final Font
LABEL_FONT
The font to render item labels with focus
static final int
LABEL_PAD
2 pixel padding between the label and the item's contents
static final int
LABEL_HEIGHT
The height of the label (maximum of 1 line
static final int
DEFAULT_WIDTH
Maximum width available to any Item
private Command[]
commands
An array of Commands added to this Item
Constructors Summary
Item(String label)
Creates a new item with a given label.

param
label the label string; null is allowed


// ************************************************************
//  Static initializer, constructor
// ************************************************************

     
        VALID_LAYOUT =
            Item.LAYOUT_DEFAULT |
            Item.LAYOUT_LEFT |
            Item.LAYOUT_RIGHT |
            Item.LAYOUT_CENTER |
            Item.LAYOUT_TOP |
            Item.LAYOUT_BOTTOM |
            Item.LAYOUT_VCENTER |
            Item.LAYOUT_SHRINK |
            Item.LAYOUT_EXPAND |
            Item.LAYOUT_VSHRINK |
            Item.LAYOUT_VEXPAND |
            Item.LAYOUT_NEWLINE_BEFORE |
            Item.LAYOUT_NEWLINE_AFTER |
            Item.LAYOUT_2;
    
        // SYNC NOTE: probably safe, but since subclasses can't lock
        // around their call to super(), we'll lock it here
        synchronized (Display.LCDUILock) {
            this.label = label;
        }
Methods Summary
public voidaddCommand(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.

param
cmd the command to be added
throws
IllegalStateException if this Item is contained within an Alert
throws
NullPointerException if cmd is null
since
MIDP 2.0

        synchronized (Display.LCDUILock) {
            addCommandImpl(cmd);
        }
voidaddCommandImpl(Command cmd)
Adds a context sensitive Command to the item.

param
cmd the command to be removed

        // LCDUI Lock must be acquired
        // prior to calling this method.
        if (cmd == null) {
            throw new NullPointerException();
        }

        for (int i = 0; i < numCommands; ++i) {
            if (commands[i] == cmd) {
                return;
            }
        }

        if ((commands == null) || (numCommands == commands.length)) {
            Command[] newCommands = new Command[numCommands + 4];
            if (commands != null) {
                System.arraycopy(commands, 0, newCommands, 0,
                                 numCommands);
            }
            commands = newCommands;
        }

        commands[numCommands] = cmd;
        ++numCommands;

        if (owner != null) {
            owner.updateCommandSet();
        }
intcallGetLayout()
Get the effective layout type of this Item

return
layout The translated layout type.

        int l = this.layout;
        if (l == LAYOUT_DEFAULT) {
            return LAYOUT_TOP | LAYOUT_LEFT;
        } else {
            return l;
        }
voidcallHideNotify()
Called by the system to notify this Item it is being hidden

The default implementation of this method updates the 'visible' state

        this.visible = false;
voidcallKeyPressed(int keyCode)
Called by the system to signal a key press

param
keyCode the key code of the key that has been pressed
see
#getInteractionModes
voidcallKeyReleased(int keyCode)
Called by the system to signal a key release

param
keyCode the key code of the key that has been released
see
#getInteractionModes
voidcallKeyRepeated(int keyCode)
Called by the system to signal a key repeat

param
keyCode the key code of the key that has been repeated
see
#getInteractionModes
voidcallKeyTyped(char c)
Called by the system to signal a key typed

param
c The character entered from the QWERTY keyboard
abstract intcallMinimumHeight()
Get the minimum height of this Item

return
the minimum height

abstract intcallMinimumWidth()
Get the minimum width of this Item
return
the minimum width
abstract voidcallPaint(Graphics g, int w, int h)
Paint the content of this Item
param
g the Graphics object to be used for rendering the item
param
w current width of the item in pixels
param
h current height of the item in pixels
voidcallPointerDragged(int x, int y)
Called by the system to signal a pointer drag
param
x the x coordinate of the pointer drag
param
y the x coordinate of the pointer drag
see
#getInteractionModes
 
voidcallPointerPressed(int x, int y)
Called by the system to signal a pointer press
param
x the x coordinate of the pointer down
param
y the y coordinate of the pointer down
see
#getInteractionModes
 
voidcallPointerReleased(int x, int y)
Called by the system to signal a pointer release
param
x the x coordinate of the pointer up
param
y the x coordinate of the pointer up
see
#getInteractionModes
abstract intcallPreferredHeight(int width)
Get the preferred height of this Item
param
width the tentative content width in pixels, or -1 if a
tentative width has not been computed
return
the preferred height
abstract intcallPreferredWidth(int height)
Get the preferred width of this Item
param
height the tentative content height in pixels, or -1 if a
tentative height has not been computed
return
the preferred width
voidcallShowNotify()
Called by the system to notify this Item it is being shown


The default implementation of this method updates
the 'visible' state
        this.visible = true;
    
voidcallSizeChanged(int w, int h)
Called by the system to indicate the size available to this Item
has changed
param
w the new width of the item's content area
param
h the new height of the item's content area
 
booleancallTraverse(int dir, int viewportWidth, int viewportHeight, int[] visRect_inout)
Called by the system


The default implementation of the traverse() method always returns
false.
param
dir the direction of traversal
param
viewportWidth the width of the container's viewport
param
viewportHeight the height of the container's viewport
param
visRect_inout passes the visible rectangle into the method, and
returns the updated traversal rectangle from the method
return
true if internal traversal had occurred, false if traversal
should proceed out
see
#getInteractionModes
see
#traverseOut
see
#TRAVERSE_HORIZONTAL
see
#TRAVERSE_VERTICAL

        hasFocus = true;
        return false;
    
voidcallTraverseOut()
Called by the system to indicate traversal has left this Item
see
#getInteractionModes
see
#traverse
see
#TRAVERSE_HORIZONTAL
see
#TRAVERSE_VERTICAL
        hasFocus = false;
    
voidcommitPendingInteraction()
Called to commit any pending user interaction for the item
 
voiddrawButtonBorder(Graphics g, int x, int y, int w, int h, boolean hasFocus)
Draw a Button Border around this Item when in Button Mode
param
g The Graphics context to paint to
param
x x co-ordinate of the Button Border
param
y y co-ordinate of the Button Border
param
w width of the Button Border
param
h height of the Button Border
param
hasFocus A flag indicating this Item has focus or not
        g.setColor(hasFocus ? DARK_GRAY_COLOR : LIGHT_GRAY_COLOR);
        g.fillRect(x, y, w, BUTTON_BORDER);
        g.fillRect(x, y, BUTTON_BORDER, h);

        g.setColor(hasFocus ? LIGHT_GRAY_COLOR : DARK_GRAY_COLOR);

        g.fillTriangle(x, y + h,
            x + BUTTON_BORDER,
            y + h - BUTTON_BORDER,
            x + BUTTON_BORDER,
            y + h);

        g.fillRect(x + BUTTON_BORDER,
            y + h - BUTTON_BORDER,
            w - BUTTON_BORDER,
            BUTTON_BORDER);

        g.fillTriangle(x + w, y,
            x + w - BUTTON_BORDER,
            y + BUTTON_BORDER,
            x + w,
            y + BUTTON_BORDER);

        g.fillRect(x + w - BUTTON_BORDER,
            y + BUTTON_BORDER,
            BUTTON_BORDER, h - BUTTON_BORDER);

        g.setColor(Display.FG_COLOR);
    
booleanequateNLA()
Determine if this Item should have a newline after it
return
true if it should have a newline after
        return ((layout & LAYOUT_NEWLINE_AFTER) == LAYOUT_NEWLINE_AFTER);
    
booleanequateNLB()
Determine if this Item should have a newline before it
return
true if it should have a newline before
        return ((layout & LAYOUT_NEWLINE_BEFORE) == LAYOUT_NEWLINE_BEFORE);
    
intgetCommandCount()
Gets the number of commands that have been added to this Item
return
int The number of commands that have been added to this
Item
        return numCommands;
    
Command[]getCommands()
Gets the set of Commands that have been added to this Item
return
Command[] The array of Commands added to this Item
        return commands;
    
ItemCommandListenergetItemCommandListener()
Gets ItemCommandListener for this Item
return
ItemCommandListener The ItemCommandListener for this Item
        return commandListener;
    
public java.lang.StringgetLabel()
Gets the label of this Item object.
return
the label string
see
#setLabel
        // SYNC NOTE: return of atomic value, no locking necessary
        return label;
    
intgetLabelHeight(int w)
Return the height of the label for this Item. If null,
returns 0, otherwise, returns LABEL_HEIGHT - which is
one line height, multi-line labels are currently disabled
by this method
param
w the width available for the label (-1 means as wide
as possible)
return
the height for the label
        if (label == null || label.length() == 0) {
            return 0;
        } 

        if (w == -1) {
            w = DEFAULT_WIDTH;
        }
        return Text.getHeightForWidth(label, LABEL_FONT, w, 0);
    
intgetLabelWidth()
Return the width of the label for this Item. If null,
returns 0, otherwise, returns the width in pixels of the
current label using LABEL_FONT.
return
the width for the label
        if (label == null || label.length() == 0) {
            return 0;
        }
        
        return Text.getWidestLineWidth(label.toCharArray(), 0, DEFAULT_WIDTH,
                                       LABEL_FONT);
    
public intgetLayout()
Gets the layout directives used for placing the item.
return
a combination of layout directive values
since
MIDP 2.0
see
#setLayout
        // SYNC NOTE: return of atomic value, no locking necessary
        return layout;
    
public intgetMinimumHeight()
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.
return
the minimum height of the item
since
MIDP 2.0
        synchronized (Display.LCDUILock) {
            return callMinimumHeight();
        }
    
public intgetMinimumWidth()
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.
return
the minimum width of the item
since
MIDP 2.0
        synchronized (Display.LCDUILock) {
            return callMinimumWidth();
        }
    
final ScreengetOwner()
Get the owner of this Item
return
Screen The owner of this Item
        return owner;
    
public intgetPreferredHeight()
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.
return
the preferred height of the Item
see
#getPreferredWidth
see
#setPreferredSize
since
MIDP 2.0
        synchronized (Display.LCDUILock) {
            return (lockedHeight != -1) ? lockedHeight :
                        callPreferredHeight(lockedWidth);
        }
    
public intgetPreferredWidth()
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.
return
the preferred width of the Item
see
#getPreferredHeight
see
#setPreferredSize
since
MIDP 2.0
        synchronized (Display.LCDUILock) {
            return (lockedWidth != -1) ? lockedWidth :
                        callPreferredWidth(lockedHeight);
        }
    
voidinvalidate()
Called by subclass code to indicate to the system that it has
either modified its size requirements or performed an internal
traversal
        synchronized (Display.LCDUILock) {
            if (owner != null) {
                owner.invalidate(this);
            }
        }
    
public voidnotifyStateChanged()
Causes this Item's containing Form to notify
the Item's {@link 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.
throws
IllegalStateException if the Item is not owned
by a Form
since
MIDP 2.0
 
        // get a copy of the object reference to item's owning form
        Screen owner = this.owner;

        if (owner == null || !(owner instanceof Form)) {
            throw new IllegalStateException();
        }

        owner.itemStateChanged(this);
    
intpaintLabel(Graphics g, int width)
Called by subclasses to paint this Item's label
param
g the graphics to draw to
param
width the allowable width for the label
return
the vertical offset of the label, if it was painted, 0
if it was not
        int labelHeight = getLabelHeight(width);
        if (LABEL_BOLD_ON_TRAVERSE) {
            Text.paint(label, hasFocus ? LABEL_FONT: Screen.CONTENT_FONT,
                    g, width, labelHeight, 0, Text.NORMAL, null);
        } else {
            Text.paint(label, LABEL_FONT,
                    g, width, labelHeight, 0, Text.NORMAL, null);
        }
        return labelHeight;
    
public voidremoveCommand(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);

 
param
cmd the command to be removed
since
MIDP 2.0
        synchronized (Display.LCDUILock) {
            removeCommandImpl(cmd);
        }
    
voidremoveCommandImpl(Command cmd)
Removes the context sensitive command from item.
param
cmd the command to be removed
        // LCDUI Lock must be acquired
        // prior to calling this method.
        for (int i = 0; i < numCommands; ++i) {
            if (commands[i] == cmd) {
                commands[i] = commands[--numCommands];
                commands[numCommands] = null;

                if (cmd == defaultCommand) {
                    defaultCommand = null;
                }

                if (owner != null) {
                    owner.updateCommandSet();
                }

                break;
            }
        }
    
voidrepaint()
Called by subclasses to repaint this entire Item's bounds
        if (bounds != null) {
            repaint(0, 0, bounds[WIDTH], bounds[HEIGHT]);
        }
    
voidrepaint(int x, int y, int w, int h)
Called by subclasses to repaint a portion of this Item's bounds
param
x the x coordinate of the origin of the dirty region
param
y the y coordinate of the origin of the dirty region
param
w the width of the dirty region
param
h the height of the dirty region

        if (owner != null) {

            if (x < 0) {
                x = 0;
            } else if (x > bounds[WIDTH]) {
                return;
            }

            if (y < 0) {
                y = 0;
            } else if (y > bounds[HEIGHT]) {
                return;
            }

            if (w < 0) {
                w = 0;
            } else if (w > bounds[WIDTH]) {
                w = bounds[WIDTH];
            }

            if (h < 0) {
                h = 0;
            } else if (h > bounds[HEIGHT]) {
                h = bounds[HEIGHT];
            }
            owner.repaintItem(this, x, y, w, h);
        }
    
public voidsetDefaultCommand(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 {@link #addCommand}
had been called
before it is made the default Command.



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.
param
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
        if (cmd != null) {
            addCommand(cmd);
        }
        defaultCommand = cmd;
    
public voidsetItemCommandListener(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.


It is illegal to call this method if this Item
is contained within an Alert.
param
l the new listener, or null.
throws
IllegalStateException if this Item is contained
within an Alert
since
MIDP 2.0
        synchronized (Display.LCDUILock) {
            commandListener = l;
        }
    
public voidsetLabel(java.lang.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.
param
label the label string
throws
IllegalStateException if this Item is contained
within an Alert
see
#getLabel
        synchronized (Display.LCDUILock) {
            this.label = label;
            invalidate();
        }
    
public voidsetLayout(int layout)
Sets the layout directives for this item.


It is illegal to call this method if this Item
is contained within an Alert.
param
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
throws
IllegalStateException if this Item is
contained within an Alert
since
MIDP 2.0
see
#getLayout
        synchronized (Display.LCDUILock) {
            setLayoutImpl(layout);
            invalidate();
        }
    
voidsetLayoutImpl(int layout)
Set the layout type of this Item
param
layout The layout type.

        if ((layout & ~VALID_LAYOUT) != 0) {
            throw new IllegalArgumentException();
        }

        this.layout = layout;
    
voidsetOwner(Screen owner)
Set the Screen owner of this Item
param
owner The Screen containing this Item
        synchronized (Display.LCDUILock) {
            if (this.owner != null && owner != null) {
                throw new IllegalStateException();
            }
            this.owner = owner;
        }
    
public voidsetPreferredSize(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.
param
width the value to which the width should be locked, or
-1 to unlock
param
height the value to which the height should be locked, or
-1 to unlock
throws
IllegalArgumentException if width or height is less than
-1
throws
IllegalStateException if this Item is contained
within an Alert
see
#getPreferredHeight
see
#getPreferredWidth
since
MIDP 2.0
        if (width < -1 || height < -1) {
            throw new IllegalArgumentException();
        }

        synchronized (Display.LCDUILock) {
            if (owner != null && owner instanceof Alert) {
                throw new IllegalStateException();
            }

            int minWidth  = getMinimumWidth();
            int minHeight = getMinimumHeight();

            this.lockedWidth  = (width != -1 && width < minWidth) 
                              ? minWidth 
                              : width;

            this.lockedHeight = (height != -1 && height < minHeight) 
                              ? minHeight 
                              : height;

            if (visible) {
                if (lockedWidth != bounds[WIDTH] ||
                        lockedHeight != bounds[HEIGHT]) {
                    invalidate();
                }
            }
        } // synchronized
    
booleanshouldHExpand()
Determine if this Item should horizontally expand
return
true if it should horizontally expand
        return ((layout & LAYOUT_EXPAND) == LAYOUT_EXPAND);
    
booleanshouldHShrink()
Determine if this Item should horizontally shrink
return
true if it should horizontally shrink
        return ((layout & LAYOUT_SHRINK) == LAYOUT_SHRINK);
    
booleanshouldSkipTraverse()
Determine if this Item should not be traversed to
return
true if this Item should not be traversed to
        return false;
    
booleanshouldVExpand()
Determine if this Item should vertically expand
return
true if it should vertically expand
        return ((layout & LAYOUT_VEXPAND) == LAYOUT_VEXPAND);
    
booleanshouldVShrink()
Determine if this Item should vertically shrink
return
true if it should vertically shrink
        return ((layout & LAYOUT_VSHRINK) == LAYOUT_VSHRINK);