javax.microedition.lcdui
Class Displayable

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

Direct Known Subclasses:

Canvas, Screen

public abstract class Displayable
extends 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.

Since:

MIDP 1.0

Method Summary
void	addCommand(Command cmd) Adds a command to the Displayable.
int	getHeight() Gets the height in pixels of the displayable area available to the application.
Ticker	getTicker() Gets the ticker used by this Displayable.
String	getTitle() Gets the title of the Displayable.
int	getWidth() Gets the width in pixels of the displayable area available to the application.
boolean	isShown() Checks if the Displayable is actually visible on the display.
void	removeCommand(Command cmd) Removes a command from the Displayable.
void	setCommandListener(CommandListener l) Sets a listener for Commands to this Displayable, replacing any previous CommandListener.
void	setTicker(Ticker ticker) Sets a ticker for use with this Displayable, replacing any previous ticker.
void	setTitle(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 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

See Also:

Displayable.setTitle(java.lang.String)

Since:

BlackBerry API 4.0.0, MIDP 2.0

setTitle

public void setTitle(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

See Also:

Displayable.getTitle()

Since:

BlackBerry API 4.0.0, MIDP 2.0

getTicker

public Ticker getTicker()

Gets the ticker used by this Displayable.

Returns:

ticker object used, or null if no ticker is present

See Also:

Displayable.setTicker(javax.microedition.lcdui.Ticker)

Since:

BlackBerry API 4.0.0, MIDP 2.0

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

See Also:

Displayable.getTicker()

Since:

BlackBerry API 4.0.0, MIDP 2.0

isShown

public boolean isShown()

Checks if the Displayable is actually visible on the display. In order for a Displayable to be visible, all of the following must be true: the Display's MIDlet must be running in the foreground, the Displayable must be the Display's current screen, and the Displayable must not be obscured by a system screen.

Returns:

true if the Displayable is currently 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 softbuttons 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:

NullPointerException - if cmd is null

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.

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 int getWidth()

Gets the width in pixels of the displayable area available to the application. The value returned is appropriate for the particular Displayable subclass. This value may depend on how the device uses the display and may be affected by the presence of a title, a ticker, or commands. This method returns the proper result at all times, even if the Displayable object has not yet been shown.

Returns:

width of the area available to the application

Since:

BlackBerry API 4.0.0, MIDP 2.0

getHeight

public int getHeight()

Gets the height in pixels of the displayable area available to the application. The value returned is appropriate for the particular Displayable subclass. This value may depend on how the device uses the display and may be affected by the presence of a title, a ticker, or commands. This method returns the proper result at all times, even if the Displayable object has not yet been shown.

Returns:

height of the area available to the application

Since:

BlackBerry API 4.0.0, 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 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:

BlackBerry API 4.0.0, MIDP 2.0