FileDocCategorySizeDatePackage
Displayable.javaAPI DocphoneME MR2 API (J2ME)17430Wed May 02 18:00:24 BST 2007javax.microedition.lcdui

Displayable

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

Fields Summary
Command[]
commands
An array of Commands added to this Displayable
int
numCommands
The number of Commands added to this Displayable
CommandListener
listener
The CommandListener for Commands added to this Displayable
boolean
isInFullScreenMode
True, if this Displayable is in full screen mode
boolean
isRotated
True, if this Displayable is rotated
String
title
The title for this Displayable
Ticker
ticker
The ticker that may be set for this Displayable
DisplayableLF
displayableLF
The Look &s; Feel object associated with this Displayable
Constructors Summary
Displayable()
Create a new Displayable
Displayable(String title)
Create a new Displayable with a passed in title

param
title the Displayable's title, or null for no title

        synchronized (Display.LCDUILock) {
            this.title = title;
        }
Methods Summary
public voidaddCommand(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.

param
cmd the command to be added
throws
NullPointerException if cmd is null

        if (cmd == null) {
            throw new NullPointerException();
        }

        synchronized (Display.LCDUILock) {
            addCommandImpl(cmd);
            displayableLF.lAddCommand(cmd, numCommands-1);
        }
intaddCommandImpl(Command cmd)
Add a Command to this Displayable

param
cmd The Command to add to this Displayable
return
command index

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

        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;

        return numCommands-1;
public intgetHeight()
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.

return
height of the area available to the application

        synchronized (Display.LCDUILock) {
            return displayableLF.lGetHeight();
        }
DisplayableLFgetLF()
Gets look&feel for this Displayable object This method is implemented in the subclasses.

return
- DisplayableLF for this Displayable object

        return displayableLF;
public TickergetTicker()
Gets the ticker used by this Displayable.

return
ticker object used, or null if no ticker is present
see
#setTicker

        synchronized (Display.LCDUILock) {
            return ticker;
        }
public java.lang.StringgetTitle()
Gets the title of the Displayable. Returns null if there is no title.

return
the title of the instance, or null if no title
see
#setTitle

        synchronized (Display.LCDUILock) {
            return title;
        }
public intgetWidth()
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.

return
width of the area available to the application

        synchronized (Display.LCDUILock) {
            return displayableLF.lGetWidth();
        }
public booleanisShown()
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.

return
true if the Displayable is currently visible

        synchronized (Display.LCDUILock) {
            return displayableLF.lIsShown();
        }
voiditemStateChanged(Item src)
Called to schedule a call to itemStateChanged() due to a change in the given Item.

param
src the Item which has changed

        /*
         * This call could happen on a Displayable that is not currently
         * visible (either not current, or the Display instance is not
         * foreground).
         */
        Display.itemStateChanged(src);
public voidremoveCommand(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.

param
cmd the command to be removed

        synchronized (Display.LCDUILock) {
            int i = removeCommandImpl(cmd);
            if (i != -1) {
                displayableLF.lRemoveCommand(cmd, i);
            }
        }
intremoveCommandImpl(Command cmd)
Remove a Command from this Displayable

param
cmd The Command to remove from this Displayable
return
command index

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

        return -1;
public voidsetCommandListener(CommandListener l)
Sets a listener for {@link Command Commands} to this Displayable, replacing any previous CommandListener. A null reference is allowed and has the effect of removing any existing listener.

param
l the new listener, or null.

        synchronized (Display.LCDUILock) {
            listener = l;
        }
	displayableLF.updateCommandSet();
public voidsetTicker(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 {@link #sizeChanged(int, int) sizeChanged()}.

param
ticker the ticker object used on this screen
see
#getTicker

        synchronized (Display.LCDUILock) {

            // Return early if there's nothing to do :
            // ticker is the same or (old and new tickers are null)
            if (this.ticker == ticker) {
                return;
            }
            Ticker oldTicker = this.ticker;

            this.ticker = ticker;
            
            displayableLF.lSetTicker(oldTicker, ticker); 
        }
public voidsetTitle(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 {@link #sizeChanged(int, int) sizeChanged()}.

param
s the new title, or null for no title
see
#getTitle

        synchronized (Display.LCDUILock) {

            if (title == s || (title != null && title.equals(s))) {
                return;
            }
            String oldTitle = title;
            this.title = s;
            displayableLF.lSetTitle(oldTitle, title);
        }
protected voidsizeChanged(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.

param
w the new width in pixels of the available area
param
h the new height in pixels of the available area

        // this method is intended to be overridden by the application
voiduCallItemStateChanged(Item src)
Called by the event handler to notify any ItemStateListener of a change in the given Item. The default implementation of this function does nothing.

param
src The Item which has changed