net.rim.device.api.ui
Class UiApplication

java.lang.Object
  extended by net.rim.device.api.system.Application
      extended by 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

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, addMediaActionHandler, addPeripheralListener, addRadioListener, addRadioListener, addRealtimeClockListener, addSystemListener, addTrackwheelListener, cancelInvokeLater, deactivate, enableKeyUpEvents, enterEventDispatcher, getAppEventLock, getApplication, getEventLock, getProcessId, 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
 
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.

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





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.