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:

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

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

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:
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
Since:
MIDP 2.0
See Also:
setTicker(javax.microedition.lcdui.Ticker)

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
Since:
MIDP 2.0
See Also:
setTitle(java.lang.String)

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:
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

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.

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
Since:
MIDP 2.0
See Also:
getTicker()

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
Since:
MIDP 2.0
See Also:
getTitle()

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:
MIDP 2.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.