|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.lcdui.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.
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.
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.
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.
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.
Unless otherwise specified by a subclass, the default state of newly
created Items
is as follows:
Item
is not contained within
("owned by") any container;Commands
present;Command
is null
;ItemCommandListener
is null
;LAYOUT_DEFAULT
; and
Field Summary | |
static int |
BUTTON
An appearance mode value indicating that the Item
is to appear as a button. |
static int |
HYPERLINK
An appearance mode value indicating that the Item
is to appear as a hyperlink. |
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. |
static int |
PLAIN
An appearance mode value indicating that the Item is to have
a normal appearance. |
Method Summary | |
void |
addCommand(Command cmd)
Adds a context sensitive Command to the item. |
String |
getLabel()
Gets the label of this Item object. |
int |
getLayout()
Gets the layout directives used for placing the item. |
int |
getMinimumHeight()
Gets the minimum height for this Item . |
int |
getMinimumWidth()
Gets the minimum width for this Item . |
int |
getPreferredHeight()
Gets the preferred height of this Item . |
int |
getPreferredWidth()
Gets the preferred width of this Item . |
void |
notifyStateChanged()
Causes this Item's containing Form to notify
the Item's ItemStateListener . |
void |
removeCommand(Command cmd)
Removes the context sensitive command from item. |
void |
setDefaultCommand(Command cmd)
Sets default Command for this Item . |
void |
setItemCommandListener(ItemCommandListener l)
Sets a listener for Commands to this Item ,
replacing any previous
ItemCommandListener . |
void |
setLabel(String label)
Sets the label of the Item . |
void |
setLayout(int layout)
Sets the layout directives for this item. |
void |
setPreferredSize(int width,
int height)
Sets the preferred width and height for this Item . |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int LAYOUT_DEFAULT
Item
should follow the default layout policy of its container.
Value 0
is assigned to LAYOUT_DEFAULT
.
public static final int LAYOUT_LEFT
Item
should have a
left-aligned layout.
Value 1
is assigned to LAYOUT_LEFT
.
public static final int LAYOUT_RIGHT
Item
should have a
right-aligned layout.
Value 2
is assigned to LAYOUT_RIGHT
.
public static final int LAYOUT_CENTER
Item
should have a
horizontally centered layout.
Value 3
is assigned to LAYOUT_CENTER
.
public static final int LAYOUT_TOP
Item
should have a
top-aligned layout.
Value 0x10
is assigned to LAYOUT_TOP
.
public static final int LAYOUT_BOTTOM
Item
should have a
bottom-aligned layout.
Value 0x20
is assigned to LAYOUT_BOTTOM
.
public static final int LAYOUT_VCENTER
Item
should have a
vertically centered layout.
Value 0x30
is assigned to
LAYOUT_VCENTER
.
public static final int LAYOUT_NEWLINE_BEFORE
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
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
Item's
width may be reduced to its minimum width.
Value 0x400
is assigned to LAYOUT_SHRINK
public static final int LAYOUT_EXPAND
Item's
width may be increased to fill available space.
Value 0x800
is assigned to LAYOUT_EXPAND
.
public static final int LAYOUT_VSHRINK
Item's
height may be reduced to its minimum height.
Value 0x1000
is assigned to
LAYOUT_VSHRINK
.
public static final int LAYOUT_VEXPAND
Item's
height may be increased to fill available space.
Value 0x2000
is assigned to
LAYOUT_VEXPAND
.
public static final int LAYOUT_2
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
Item
is to have
a normal appearance.
Value 0
is assigned to PLAIN
.
public static final int HYPERLINK
Item
is to appear as a hyperlink.
Value 1
is assigned to HYPERLINK
.
public static final int BUTTON
Item
is to appear as a button.
Value 2
is assigned to BUTTON
.
Method Detail |
public void setLabel(String label)
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
.
label
- the label stringIllegalStateException
- if this Item
is contained
within an Alert
getLabel()
public String getLabel()
Item
object.setLabel(java.lang.String)
public int getLayout()
setLayout(int)
public void setLayout(int layout)
It is illegal to call this method if this Item
is contained within an Alert
.
layout
- a combination of layout directive values for this itemIllegalArgumentException
- if the value of layout is not a
bit-wise OR combination of layout directivesIllegalStateException
- if this Item
is
contained within an Alert
getLayout()
public void addCommand(Command cmd)
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
.
cmd
- the command to be addedIllegalStateException
- if this Item
is contained
within an Alert
NullPointerException
- if cmd is null
public void removeCommand(Command cmd)
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);
cmd
- the command to be removedpublic void setItemCommandListener(ItemCommandListener l)
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
.
l
- the new listener, or null
.IllegalStateException
- if this Item
is contained
within an Alert
public int getPreferredWidth()
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.getPreferredHeight()
,
setPreferredSize(int, int)
public int getPreferredHeight()
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.Item
getPreferredWidth()
,
setPreferredSize(int, int)
public void setPreferredSize(int width, int height)
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
.
width
- the value to which the width should be locked, or
-1
to unlockheight
- the value to which the height should be locked, or
-1
to unlockIllegalArgumentException
- if width or height is less than
-1
IllegalStateException
- if this Item
is contained
within an Alert
getPreferredHeight()
,
getPreferredWidth()
public int getMinimumWidth()
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.public int getMinimumHeight()
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.public void setDefaultCommand(Command cmd)
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
.
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
.
cmd
- the command to be used as this Item's
default
Command
, or null
if there is to
be no default commandIllegalStateException
- if this Item
is contained
within an Alert
public void notifyStateChanged()
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:
Item's
value has actually been changed, andItem'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.
IllegalStateException
- if the Item
is not owned
by a Form
|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |