net.rim.device.api.ui
Class UiApplication

java.lang.Object
  |
  +--net.rim.device.api.system.Application
        |
        +--net.rim.device.api.ui.UiApplication

All Implemented Interfaces:

UiEngine

public abstract class UiApplication

extends Application

implements UiEngine

Base class for all device applications that provide a user interface.

A UI application maintains a stack of Screen objects. As it pushes screens onto the stack, it draws them on top of any other screens already on the stack. When the application pops a screen off the stack, it redraws the underlying screens as necessary. Only the screen on the top of the stack receives input events.

Each screen may appear only once in the display stack. The application throws a runtime exception if you attempt to push a single screen onto the stack more than once.

Note that a UI application must follow rules similar to those of traditional Swing applications. In particular

• Only one thread at a time (generally, the event-dispatching thread) may gain access to an interface component at once.

• If you need access to the UI from outside event-handling or drawing code, then you can use the invokeLater() or invokeAndWait() methods.

Alternatively, a worker thread can synchronize on the event lock (returned by Application.getEventLock() to ensure serialized access to the UI. Note that you should only hold this lock for short periods of time.

Code on the event thread should not block or execute for long periods of time: the system will not dispatch messages, and the event queue can therefore overflow. You can use background threads for long processing.

Constructor Summary

protected

UiApplication() Constructs a new UI application.

Method Summary

protected boolean	acceptsForeground() Determines if this application can function in the foreground.
void	dismissStatus(Screen screen) Dismisses or removes a global status screen from the queue.
Screen	getActiveScreen() Retrieves active displayed screen.
int	getScreenCount() Retrieves the number of screens currently on the display stack.
static UiApplication	getUiApplication() Retrieves this UI application object.
boolean	isPaintingSuspended() Determines if repainting is currently suspended.
void	popScreen(Screen screen) Removes a screen from the display stack, and updates the screen.
void	pushModalScreen(Screen screen) Pushes a modal screen onto the display and paints it.
void	pushScreen(Screen screen) Pushes a screen onto the display stack and paints it.
void	queueStatus(Screen screen, int priority, boolean inputRequired) Adds a screen to the queue of displayed global status screens.
void	relayout() Updates the layout of all screens and repaints.
void	repaint() Repaints entire display.
void	suspendPainting(boolean suspend) Suspends painting of the UI.
void	updateDisplay() Updates the display for all the screens in this application.

Methods inherited from class net.rim.device.api.system.Application

activate, addAlertListener, addGlobalEventListener, addHolsterListener, addIOPortListener, addKeyListener, addPeripheralListener, addRadioListener, addRealtimeClockListener, addSystemListener, addTrackwheelListener, cancelInvokeLater, deactivate, enableKeyUpEvents, enterEventDispatcher, getAppEventLock, getApplication, getEventLock, getProcessId, hasEventThread, invokeAndWait, invokeLater, invokeLater, isEventDispatchThread, isEventThread, isForeground, isHandlingEvents, removeAlertListener, removeGlobalEventListener, removeHolsterListener, removeIOPortListener, removeKeyListener, removePeripheralListener, removeRadioListener, removeRealtimeClockListener, removeSystemListener, removeTrackwheelListener, requestBackground, requestForeground, setAcceptEvents

Methods inherited from class java.lang.Object

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

Constructor Detail

UiApplication

protected UiApplication()

Constructs a new UI application.

This default constructor is called by UiApplication subclasses.

Method Detail

suspendPainting

public final void suspendPainting(boolean suspend)

Suspends painting of the UI.

Normally, whenever a message is handled the screen gets repainted; you can invoke this method to prevent this.

Specified by:

suspendPainting in interface UiEngine

Parameters:

suspend - Specify true to suspend repainting; specify false to re-enable repainting.

Throws:

IllegalStateException - if painting is reenabled without previously being disabled.

Since:

JDE 3.7.0

isPaintingSuspended

public final boolean isPaintingSuspended()

Determines if repainting is currently suspended.

Specified by:

isPaintingSuspended in interface UiEngine

Returns:

True if painting is currently suspended; otherwise, returns false.

updateDisplay

public final void updateDisplay()

Updates the display for all the screens in this application.

Specified by:

updateDisplay in interface UiEngine

pushScreen

public final void pushScreen(Screen screen)

Pushes a screen onto the display stack and paints it.

This method is non-blocking, and returns immediately; the screen remains on the stack. This will cause a layout and paint, so be sure to add all the controls to the screen before pushing it.

Specified by:

pushScreen in interface UiEngine

Parameters:

screen - Screen to push.

Since:

JDE 3.7.0

pushModalScreen

public final void pushModalScreen(Screen screen)

Pushes a modal screen onto the display and paints it.

Invoke this method to push a modal screen on to the stack and paint it. This method does not return until you invoke popScreen(Screen). You must invoke this method on the event thread.

Specified by:

pushModalScreen in interface UiEngine

Parameters:

screen - Screen to push.

Since:

JDE 3.7.0

popScreen

public final void popScreen(Screen screen)

Removes a screen from the display stack, and updates the screen.

Specified by:

popScreen in interface UiEngine

Parameters:

screen - Screen to remove.

Throws:

IllegalArgumentException - If your screen is not on the stack.

Since:

JDE 3.7.0

getScreenCount

public final int getScreenCount()

Retrieves the number of screens currently on the display stack.

Specified by:

getScreenCount in interface UiEngine

Returns:

Number of screens on the display stack.

repaint

public final void repaint()

Repaints entire display.

Invoke this method to repaint the entire display. It invalidates, and then paints, each screen on the display stack.

Specified by:

repaint in interface UiEngine

relayout

public final void relayout()

Updates the layout of all screens and repaints.

You can invoke this method when, for example, global UI settings change.

Specified by:

relayout in interface UiEngine

getActiveScreen

public final Screen getActiveScreen()

Retrieves active displayed screen.

Invoke this method to retrieve the topmost screen on the display stack (the currently active screen).

Specified by:

getActiveScreen in interface UiEngine

Returns:

Active screen; otherwise, if the display stack has no screens, null.

queueStatus

public final void queueStatus(Screen screen,
                              int priority,
                              boolean inputRequired)

Adds a screen to the queue of displayed global status screens.

Global status screens appear on top of all other screens on the device, even if the current application is not in the foreground.

If no other status screens are currently displayed, your provided screen appears immediately.

If a status screen is currently displayed, or the queue contains other screens, this method uses your provided priority parameter to determine when to display your screen.

This method ensures that your provided screen is bitmap-based.

Specified by:

queueStatus in interface UiEngine

Parameters:

screen - Bitmap-based screen to enqueue.

priority - Priority of queued screen. Lower values indicate a higher priority.

inputRequired - True if queued screen requires user input; otherwise, if the system will automatically dismiss your screen, false.

Since:

JDE 3.7.0

dismissStatus

public final void dismissStatus(Screen screen)

Dismisses or removes a global status screen from the queue.

If this screen is currently showing, this method dismisses the screen, replacing it with the next screen in the queue (if one exists). If the screen is not currently showing, this method simply removes it from the queue.

The invoking application must be the same application which enqueued the screen (the application displaying the screen).

Specified by:

dismissStatus in interface UiEngine

Parameters:

screen - Status screen to remove from the status queue.

Since:

JDE 3.7.0

acceptsForeground

protected boolean acceptsForeground()

Determines if this application can function in the foreground.

Note that, since all UI applications should be able to interact with the user, this method simply returns true.

Overrides:

acceptsForeground in class Application

Returns:

True if this application can be pushed into the foreground; otherwise, false.

getUiApplication

public static final UiApplication getUiApplication()

Retrieves this UI application object.

Returns:

This UI application.