org.netbeans.microedition.lcdui
Class WaitScreen

java.lang.Object
  extended by javax.microedition.lcdui.Displayable
      extended by javax.microedition.lcdui.Canvas
          extended by org.netbeans.microedition.lcdui.AbstractInfoScreen
              extended by org.netbeans.microedition.lcdui.WaitScreen

public class WaitScreen
extends AbstractInfoScreen

This component suits as a wait screen, which let the user to execute a blocking background task (e.g. a network communication) and waits for it until finished.

The background task is being started immediately prior the component is being shown on the screen.

When the background task is finished, this component calls commandAction method on assigned CommandListener object. In the case of success, the commandAction method is called with SUCCESS_COMMAND as parameter, in the case of failure, the commandAction method is called with FAILURE_COMMAND as parameter.

The functionality from previous version, where the component automatically swiches to another Displayable objects is still available, but has beeen deprecated.

The deprecated behavior is the following - in the case of success (i.e. the task finished successfully), it switches to displayable(s) supplied by setNextDisplayable() methods, in the case of failure, it switched to displaybles(s) supplied by setFailureDisplayable() methods. In the case there is not set failure displayable, WaitScreen even in the case of failure switches to displayables specified by the setNextDisplayable() method. In the case there is even no next displayable specified, after the task is finished, WaitScreen switches back to the screen it was previously visible on the display.


Field Summary
static javax.microedition.lcdui.Command FAILURE_COMMAND
          Command fired when the background task failed (threw exception)
static javax.microedition.lcdui.Command SUCCESS_COMMAND
          Command fired when the background task was finished succesfully
 
Fields inherited from class javax.microedition.lcdui.Canvas
DOWN, FIRE, GAME_A, GAME_B, GAME_C, GAME_D, KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_POUND, KEY_STAR, LEFT, RIGHT, UP
 
Constructor Summary
WaitScreen(javax.microedition.lcdui.Display display)
          Creates a new instance of WaitScreen for given Display object.
 
Method Summary
 CancellableTask getTask()
          Gets the background task.
 void setFailureDisplayable(javax.microedition.lcdui.Alert failureAlert, javax.microedition.lcdui.Displayable failureDisplayble)
          Deprecated. - use FAILURE_COMMAND in CommandListener.commandAction() to handle failure event
 void setFailureDisplayable(javax.microedition.lcdui.Displayable failureDisplayble)
          Deprecated. - use FAILURE_COMMAND in CommandListener.commandAction() to handle failure event
 void setTask(CancellableTask task)
          Sets the task to be run on the background.
protected  void showNotify()
          starts the supplied task
 
Methods inherited from class org.netbeans.microedition.lcdui.AbstractInfoScreen
getColorSchema, getCommandListener, getDisplay, getImage, getNextAlert, getNextDisplayable, getText, getTextFont, paint, setColorSchema, setCommandListener, setImage, setNextDisplayable, setNextDisplayable, setText, setTextFont, sizeChanged, switchToDisplayable, switchToNextDisplayable
 
Methods inherited from class javax.microedition.lcdui.Canvas
getGameAction, getKeyCode, getKeyName, hasPointerEvents, hasPointerMotionEvents, hasRepeatEvents, hideNotify, isDoubleBuffered, keyPressed, keyReleased, keyRepeated, pointerDragged, pointerPressed, pointerReleased, repaint, repaint, serviceRepaints, setFullScreenMode
 
Methods inherited from class javax.microedition.lcdui.Displayable
addCommand, getHeight, getTicker, getTitle, getWidth, isShown, removeCommand, setTicker, setTitle
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SUCCESS_COMMAND

public static final javax.microedition.lcdui.Command SUCCESS_COMMAND
Command fired when the background task was finished succesfully


FAILURE_COMMAND

public static final javax.microedition.lcdui.Command FAILURE_COMMAND
Command fired when the background task failed (threw exception)

Constructor Detail

WaitScreen

public WaitScreen(javax.microedition.lcdui.Display display)
           throws java.lang.IllegalArgumentException
Creates a new instance of WaitScreen for given Display object.

Parameters:
display - A non-null display object.
Throws:
java.lang.IllegalArgumentException - when the supplied argument is null
Method Detail

setFailureDisplayable

public void setFailureDisplayable(javax.microedition.lcdui.Displayable failureDisplayble)
Deprecated. - use FAILURE_COMMAND in CommandListener.commandAction() to handle failure event

Sets the displayable to be used to switch to in the case of the background task failure.

Parameters:
failureDisplayble - displayable, or null if the component should switch to nextDisplayable even in the case of failure.

setFailureDisplayable

public void setFailureDisplayable(javax.microedition.lcdui.Alert failureAlert,
                                  javax.microedition.lcdui.Displayable failureDisplayble)
                           throws java.lang.IllegalArgumentException
Deprecated. - use FAILURE_COMMAND in CommandListener.commandAction() to handle failure event

Requests that the specified Alert is going to be shown in the case of failure, and failureDisplayable be made current after the Alert is dismissed.

The failureDisplayable parameter cannot be Alert and in the case failureAlert is not null, it also cannot be null.

Parameters:
failureAlert - alert to be shown, or null if the component should always switch to nextDisplayable
failureDisplayble - a displayable to be shown after the alert is being dismissed. This displayable cannot be null if the failureAlert is not null and it also cannot be Alert.
Throws:
java.lang.IllegalArgumentException - If the failureAlert is not null and failureDisplay is null at the same time, or if the failureDisplayable is instance of Alert

setTask

public void setTask(CancellableTask task)
Sets the task to be run on the background.

Parameters:
task - task to be executed

getTask

public CancellableTask getTask()
Gets the background task.

Returns:
task being executed in background while this component is being shown on the screen

showNotify

protected void showNotify()
starts the supplied task

Overrides:
showNotify in class AbstractInfoScreen