javax.microedition.lcdui
Class Displayable

java.lang.Object
  javax.microedition.lcdui.Displayable

Direct Known Subclasses:

Canvas, Screen

public abstract class Displayable
extends java.lang.Object

An object that has the capability of being placed on the display. A Displayable object may have a title, a ticker, zero or more commands and a listener associated with it. The contents displayed and their interaction with the user are defined by subclasses.

The title string may contain line breaks. The display of the title string must break accordingly. For example, if only a single line is available for a title and the string contains a line break then only the characters up to the line break are displayed.

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

• it is not visible on the Display;
• there is no Ticker associated with this Displayable;
• the title is null;
• there are no Commands present; and
• there is no CommandListener present.

Exact placement of Commands

In MIDP3.0 the method of using type and priority for Commands placement is supplemented with a method to use absolute placement using the optional placement value. The available placements are retrieved from Displayable.getExactPlacements. A placement is encoded as a base value for each border plus an index of the soft key along the border. For more details see Display.

Since:

MIDP 3.0

Method Summary

void	addCommand(Command cmd) Adds a command to the Displayable.
Command	getCommand(int placement) Gets the Command at the given placement.
CommandLayoutPolicy	getCommandLayoutPolicy() This method will return the current CommandLayoutPolicy for this Displayable.
Command[]	getCommands() Gets the set of commands that has been added to the Displayable.
Display	getCurrentDisplay() Returns the Display associated with this Displayable.
abstract int	getHeight() Gets the height of the Displayable, in pixels.
Menu	getMenu(int placement) Gets the Menu at the given placement.
Ticker	getTicker() Gets the ticker used by this Displayable.
java.lang.String	getTitle() Gets the title of the Displayable.
abstract int	getWidth() Gets the width of the Displayable, in pixels.
void	invalidateCommandLayout() Request an update of the layout policy.
boolean	isShown() Checks if the Displayable is visible on the display.
void	removeCommand(Command cmd) Removes a command from the Displayable.
void	removeCommandOrMenu(int placement) Removes the Command or Menu present at the given exact placement.
void	setCommand(Command cmd, int placement) Adds or sets a Command to the Displayable at the given placement.
void	setCommandLayoutPolicy(CommandLayoutPolicy policy) This method will set a new CommandLayoutPolicy for this Displayable.
void	setCommandListener(CommandListener l) Sets a listener for Commands to this Displayable, replacing any previous CommandListener.
void	setMenu(Menu menu, int placement) Adds or sets a menu to the Displayable at the given placement.
void	setTicker(Ticker ticker) Sets a ticker for use with this Displayable, replacing any previous ticker.
void	setTitle(java.lang.String s) Sets the title of the Displayable.
protected void	sizeChanged(int w, int h) The implementation calls this method when the available area of the Displayable has been changed.

Methods inherited from class java.lang.Object

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

Method Detail

getTitle

public java.lang.String getTitle()

Gets the title of the Displayable. Returns null if there is no title.

Returns:

the title of the instance, or null if no title

Since:

MIDP 2.0

See Also:

setTitle(java.lang.String)

setTitle

public void setTitle(java.lang.String s)

Sets the title of the Displayable. If null is given, removes the title.

If the Displayable is actually visible on the display, the implementation should update the display as soon as it is feasible to do so.

The existence of a title may affect the size of the area available for Displayable content. Addition, removal, or the setting of the title text at runtime may dynamically change the size of the content area. This is most important to be aware of when using the Canvas class. If the available area does change, the application will be notified via a call to sizeChanged().

Parameters:

s - the new title, or null for no title

Throws:

DisplayCapabilityException - if the Displayable is set to a Display that does not support Titles

Since:

MIDP 2.0

See Also:

getTitle()

setTicker

public void setTicker(Ticker ticker)

Sets a ticker for use with this Displayable, replacing any previous ticker. If null, removes the ticker object from this Displayable. The same ticker may be shared by several Displayable objects within an application. This is done by calling setTicker() with the same Ticker object on several different Displayable objects. If the Displayable is actually visible on the display, the implementation should update the display as soon as it is feasible to do so.

The existence of a ticker may affect the size of the area available for Displayable's contents. Addition, removal, or the setting of the ticker at runtime may dynamically change the size of the content area. This is most important to be aware of when using the Canvas class. If the available area does change, the application will be notified via a call to sizeChanged().

Parameters:

ticker - the ticker object used on this screen

Throws:

DisplayCapabilityException - if the Displayable is set to a Display that does not support Tickers

Since:

MIDP 2.0

See Also:

getTicker()

getTicker

public Ticker getTicker()

Gets the ticker used by this Displayable.

Returns:

ticker object used, or null if no ticker is present

Since:

MIDP 2.0

See Also:

setTicker(javax.microedition.lcdui.Ticker)

isShown

public boolean isShown()

Checks if the Displayable is visible on the display. A Displayable is considered to be visible if at least one of its pixels is visible to the user. In order for a Displayable to be visible, all of the following must be true: the Display must not be in the background, the Displayable must be the Display's current screen, and at least one pixel of the screen's display resource must be allocated to the Display.

Returns:

true if the Displayable is currently at all visible

addCommand

public void addCommand(Command cmd)

Adds a command to the Displayable. The implementation may choose, for example, to add the command to any of the available soft buttons or place it in a menu. If the added command is already in the screen (tested by comparing the object references), the method has no effect. If the Displayable 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.

Parameters:

cmd - the command to be added

Throws:

java.lang.NullPointerException - if cmd is null

DisplayCapabilityException - if the Displayable is set to a Display that does not support Commands

getCommand

public Command getCommand(int placement)

Gets the Command at the given placement. If the placement is empty or contains a Menu, null is returned.

Parameters:

placement - the placement to query

Returns:

Command instance located at the given placement, or null if no Command exists at the given placement.

Throws:

java.lang.IllegalArgumentException - if the provided placement is not valid.

Since:

MIDP 3.0

setCommand

public void setCommand(Command cmd,
                       int placement)

Adds or sets a Command to the Displayable at the given placement. If the Command already exists on another placement of this Displayable, it will be moved to the new placement. Just before the Command is added, any Menu or Command already occupying the given placement will be removed from the associated Item or Displayable. This method should only be called from inside an implementation of the CommandLayoutPolicy interface. If the Displayable 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.

Parameters:

cmd - the Command to be added

placement - the placement of the Command to be added

Throws:

java.lang.NullPointerException - if cmd is null

DisplayCapabilityException - if the Displayable is set to a Display that does not support Commands

java.lang.IllegalArgumentException - if the provided placement is not valid or is associated with a placement that does not support commands

java.lang.IllegalStateException - If this method is not called from a CommandLayoutPolicy.onCommandLayout() implementation.

java.lang.IllegalStateException - If this Displayable is neither the same instance passed into the CommandLayoutPolicy.onCommandLayout() method nor the current tab of a TabbedPane

Since:

MIDP 3.0

getMenu

public Menu getMenu(int placement)

Gets the Menu at the given placement. If the placement is empty or contains a Command, null is returned.

Parameters:

placement - the placement to query

Returns:

Menu instance located at the given placement, or null if no Menu exists at the given placement.

Throws:

java.lang.IllegalArgumentException - if the provided placement is not valid.

Since:

MIDP 3.0

setMenu

public void setMenu(Menu menu,
                    int placement)

Adds or sets a menu to the Displayable at the given placement. If the menu already exists on another placement of this Displayable, it will be moved to the new placement. Just before the Menu is added, any Menu or Command already occupying the given placement will be removed from the associated Item or Displayable. This method should only be called from inside an implementation of the CommandLayoutPolicy interface. If the Displayable 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.

Parameters:

menu - the menu to be added

placement - the placement of the menu to be added

Throws:

java.lang.NullPointerException - if menu is null

DisplayCapabilityException - if the Displayable is set to a Display that does not support Menus

java.lang.IllegalArgumentException - if the provided placement is not valid or is associated with a placement that does not support menus

java.lang.IllegalStateException - If this method is not called from a CommandLayoutPolicy.onCommandLayout() implementation.

java.lang.IllegalStateException - If this Displayable is neither the same instance passed into the CommandLayoutPolicy.onCommandLayout() method nor the current tab of a TabbedPane

Since:

MIDP 3.0

removeCommandOrMenu

public void removeCommandOrMenu(int placement)

Removes the Command or Menu present at the given exact placement. This method should only be called from inside an implementation of the CommandLayoutPolicy interface.

Parameters:

placement - the placement of the Command or Menu to be removed

Throws:

java.lang.IllegalArgumentException - if the provided placement is not valid

java.lang.IllegalStateException - If this method is not called from a Command.onCommandLayout() implementation.

Since:

MIDP 3.0

removeCommand

public void removeCommand(Command cmd)

Removes a command from the Displayable. If the command is not in the Displayable (tested by comparing the object references), the method has no effect. If the Displayable 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 cmd is null, this method does nothing.

Parameters:

cmd - the command to be removed

setCommandListener

public void setCommandListener(CommandListener l)

Sets a listener for Commands to this Displayable, replacing any previous CommandListener. A null reference is allowed and has the effect of removing any existing listener.

Parameters:

l - the new listener, or null.

getWidth

public abstract int getWidth()

Gets the width of the Displayable, in pixels. The returned value indicates the width of the Displayable's content area that is available in its entirety for the developer to use. The content area specifically excludes any portions of the screen that are not directly useable by the developer such as areas occupied by status bars, commands, tickers, titles, and other on-screen artifacts (e.g. an on-screen keypad to support game actions on touch-screen devices). The returned value reflects the size and layout of the default Display if the Displayable is not currently shown on a Display.

Returns:

width of the area available to the application

Since:

MIDP 2.0

getHeight

public abstract int getHeight()

Gets the height of the Displayable, in pixels. The returned value indicates the height of the Displayable's content area that is available in its entirety for the developer to use. The content area specifically excludes any portions of the screen that are not directly useable by the developer such as areas occupied by status bars, commands, tickers, titles, and other on-screen artifacts (e.g. an on-screen keypad to support game actions on touch-screen devices). The returned value reflects the size and layout of the default Display if the Displayable is not currently shown on a Display.

Returns:

height of the area available to the application

Since:

MIDP 2.0

sizeChanged

protected void sizeChanged(int w,
                           int h)

The implementation calls this method when the available area of the Displayable has been changed. The "available area" is the area of the display that may be occupied by the application's contents, such as Items in a Form or graphics within a Canvas. It does not include space occupied by a title, a ticker, command labels, scroll bars, system status area, etc. A size change can occur as a result of the addition, removal, or changed contents of any of these display features.

This method is called at least once before the Displayable is shown for the first time. If the size of a Displayable changes while it is visible, sizeChanged will be called. If the size of a Displayable changes while it is not visible, calls to sizeChanged may be deferred. If the size had changed while the Displayable was not visible, sizeChanged will be called at least once at the time the Displayable becomes visible once again.

The default implementation of this method in Displayable and its subclasses defined in this specification must be empty. This method is intended solely for being overridden by the application. This method is defined on Displayable even though applications are prohibited from creating direct subclasses of Displayable. It is defined here so that applications can override it in subclasses of Canvas and Form. This is useful for Canvas subclasses to tailor their graphics and for Forms to modify Item sizes and layout directives in order to fit their contents within the available display area.

Parameters:

w - the new width in pixels of the available area

h - the new height in pixels of the available area

Since:

MIDP 2.0

getCurrentDisplay

public Display getCurrentDisplay()

Returns the Display associated with this Displayable. Returns null if this Displayable is not bound to any Display.

Returns:

Display associated with this Displayable. null if this Displayable is not bound to a Display.

Since:

MIDP 3.0

setCommandLayoutPolicy

public void setCommandLayoutPolicy(CommandLayoutPolicy policy)

This method will set a new CommandLayoutPolicy for this Displayable.

Parameters:

policy - The new CommandLayoutPolicy that should be used. If the parameter is null then default policy for the Display is used.

Since:

MIDP 3.0

getCommandLayoutPolicy

public CommandLayoutPolicy getCommandLayoutPolicy()

This method will return the current CommandLayoutPolicy for this Displayable.

Returns:

The current CommandLayoutPolicy

Since:

MIDP 3.0

getCommands

public Command[] getCommands()

Gets the set of commands that has been added to the Displayable.

Returns:

An array containing all commands added to the displayable

Since:

MIDP 3.0

invalidateCommandLayout

public void invalidateCommandLayout()

Request an update of the layout policy. If this displayable is not current on its display, or doesn't have focus the request will be ignored.

Since:

MIDP 3.0