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

Direct Known Subclasses:

JILWidgetApplication

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.

Field Summary

Fields inherited from interface net.rim.device.api.ui.UiEngine

GLOBAL_MODAL, GLOBAL_QUEUE, GLOBAL_SHOW_LOWER

Constructor Summary
protected	UiApplication() Constructs a new UI application.

Method Summary
protected boolean	acceptsForeground() Determines if this application can function in the foreground.
void	activate() Handles foregrounding event.
void	dismissStatus(Screen screen) Deprecated. Use popScreen(Screen)
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.
UiEngineInstance	getUiEngineInstance() Gets the instance of the UiEngine.
boolean	isPaintingSuspended() Determines if repainting is currently suspended.
void	popScreen(Screen screen) Removes a screen from the display stack, and updates the screen.
void	pushGlobalScreen(Screen screen, int priority, boolean inputRequired) Deprecated. Use pushGlobalScreen(Screen, int, int)
void	pushGlobalScreen(Screen screen, int priority, int flags) Push a global 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) Deprecated. Use pushGlobalScreen(Screen, int, int)
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

acceptsKeyUpEvents, addAlertListener, addFileSystemJournalListener, addFileSystemListener, addGlobalEventListener, addHolsterListener, addIOPortListener, addKeyListener, addKeyListener, addMediaActionHandler, addPeripheralListener, addRadioListener, addRadioListener, addRealtimeClockListener, addSystemListener, addTrackwheelListener, cancelInvokeLater, deactivate, enableKeyUpEvents, enterEventDispatcher, getAppEventLock, getApplication, getEventLock, getProcessId, getServiceMode, hasEventThread, invokeAndWait, invokeLater, invokeLater, isAlive, isEventDispatchThread, isEventThread, isForeground, isHandlingEvents, isInTouchCompatibilityMode, removeAlertListener, removeFileSystemJournalListener, removeFileSystemListener, removeGlobalEventListener, removeHolsterListener, removeIOPortListener, removeKeyListener, removeMediaActionHandler, removePeripheralListener, removeRadioListener, removeRealtimeClockListener, removeSystemListener, removeTrackwheelListener, requestBackground, requestClose, requestForeground, setAcceptEvents, setServiceMode, setServiceModeImpl, shouldAppearInApplicationSwitcher, suggestServiceMode

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

getUiEngineInstance

public UiEngineInstance getUiEngineInstance()

Gets the instance of the UiEngine. This has been added so that new methods can more easily be added. The old technique with an interface meant this was awkward and also resulted in performance degredation.

Since:

BlackBerry API 5.0.0

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.

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

See Also:

UiEngine.updateDisplay()

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.

pushGlobalScreen

public final void pushGlobalScreen(Screen screen,
                                   int priority,
                                   int flags)

Push a global screen. This method replaces pushGlobalScreen(Screen, int, boolean), and pushGlobalScreen(Screen, int, boolean), which are deprecated.

Specified by:

pushGlobalScreen in interface UiEngine

Parameters:

screen - The global screen to display

priority - The screen's priority (lower value = higher priority)

flags - One or more of GLOBAL_MODAL (block until dismissed), GLOBAL_QUEUE (insert below screens of the same priority), and GLOBAL_SHOW_LOWER (don't block the display of lower-priority global screens).

Since:

BlackBerry API 4.2.0

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.

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 UiApplication.popScreen(Screen). You must invoke this method on the event thread.

Specified by:

pushModalScreen in interface UiEngine

Parameters:

screen - Screen to push.

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)

Deprecated. Use pushGlobalScreen(Screen, int, int)

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 to determine when to display your screen. If the priority of the currently displayed screen is strictly greater than the newly pushed screen then the new screen will be shown.

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.

pushGlobalScreen

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

Deprecated. Use pushGlobalScreen(Screen, int, int)

Adds a screen to the set of displayed global screens.

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

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

If a global screen is currently displayed, or the set contains other global screens, this method uses your provided priority to determine when to display your screen. If the priority of the currently displayed screen is greater than or equal to the newly pushed screen then the new screen will be shown.

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

Specified by:

pushGlobalScreen in interface UiEngine

Parameters:

screen - Bitmap-based screen to enqueue.

priority - Priority of global screen.

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

Since:

BlackBerry API 4.0.0, 4.0

dismissStatus

public final void dismissStatus(Screen screen)

Deprecated. Use popScreen(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 - Global Screen to remove from the status queue.

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.

See Also:

UiApplication

getUiApplication

public static final UiApplication getUiApplication()

Retrieves this UI application object. Note that calling this method from a non-UI application will result in a ClassCastException.

Returns:

This UI application.

activate

public void activate()

Handles foregrounding event.

The system invokes this method when it brings this application to the foreground. By default, this method does nothing. Override this method to perform additional processing when being brought to the foreground.

Overrides:

activate in class Application

Since:

BlackBerry API 4.2.1