net.rim.device.api.ui
Interface UiEngine

All Known Implementing Classes:

JILWidgetApplication, UiApplication

public interface UiEngine

Defines functionality for a user interface engine applications can use for their UI operations.

A UI engine 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 users of a UI engine 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
static int	GLOBAL_MODAL For pushGlobalScreen().
static int	GLOBAL_QUEUE For pushGlobalScreen().
static int	GLOBAL_SHOW_LOWER For pushGlobalScreen().

Method Summary
void	dismissStatus(Screen screen) Deprecated. Use popScreen(Screen)
Screen	getActiveScreen() Retrieves handle for the active screen.
int	getScreenCount() Retrieves the number of screens currently on the display stack.
boolean	isPaintingSuspended() Determines if repainting is currently suspended.
void	popScreen(Screen screen) Removes a screen from the display stack, and updates the display.
void	pushGlobalScreen(Screen screen, int priority, boolean inputRequired) Deprecated. Use pushGlobalScreen(Screen, int, int)
void	pushGlobalScreen(Screen screen, int priority, int flags) Adds a screen to the queue of displayed global status screens.
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 with pending graphics operations.

Field Detail

GLOBAL_MODAL

static final int GLOBAL_MODAL

For pushGlobalScreen(). If true, the method should block until the screen closes.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

GLOBAL_QUEUE

static final int GLOBAL_QUEUE

For pushGlobalScreen(). If true, the screen will be inserted below global screens of equal priority. Otherwise, it will be inserted above them.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

GLOBAL_SHOW_LOWER

static final int GLOBAL_SHOW_LOWER

For pushGlobalScreen(). If false, pushing the screen will suppress the display of any global screens of lower priority.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

Method Detail

dismissStatus

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).

Parameters:

screen - Global Screen to remove from the queue.

getActiveScreen

Screen getActiveScreen()

Retrieves handle for the active screen.

getScreenCount

int getScreenCount()

Retrieves the number of screens currently on the display stack.

Returns:

Number of screens on the display stack.

isPaintingSuspended

boolean isPaintingSuspended()

Determines if repainting is currently suspended.

Returns:

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

pushGlobalScreen

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

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.

This method should be used instead of the old versions of pushGlobalScreen or queueStatus. All variants can be obtained using the appropriate combination of flags:

GLOBAL_MODAL -- block until the screen closes
GLOBAL_QUEUE -- insert the screen underneath global screens of equal priority
GLOBAL_SHOW_LOWER -- don't suppress the display of global screens with lower priority

Parameters:

screen - A screen to enqueue.

priority - Priority of queued screen.

flags - One or more of GLOBAL_MODAL, GLOBAL_QUEUE, and GLOBAL_SHOW_LOWER

Since:

BlackBerry API 4.2.0

pushScreen

void pushScreen(Screen screen)

Pushes a screen onto the display stack and paints it.

This causes a layout and paint, so add required controls to the screen before pushing it. This method does not block.

Call UiEngine.popScreen(net.rim.device.api.ui.Screen) to remove the screen.

Parameters:

screen - Screen to push.

pushModalScreen

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 UiEngine.popScreen(net.rim.device.api.ui.Screen). You must invoke this method on the event thread.

Parameters:

screen - Screen to push.

popScreen

void popScreen(Screen screen)

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

Parameters:

screen - Screen to remove.

Throws:

IllegalArgumentException - If your screen is not on the stack.

queueStatus

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.

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

Parameters:

screen - Bitmap-based screen to enqueue.

priority - Priority of queued screen.

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

repaint

void repaint()

Repaints entire display.

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

relayout

void relayout()

Updates the layout of all screens and repaints.

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

pushGlobalScreen

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.

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 3.7.0, 4.0

suspendPainting

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.

Parameters:

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

Throws:

IllegalStateException - if painting is reenabled without previously being disabled.

updateDisplay

void updateDisplay()

Updates the display with pending graphics operations. This method flushes any queued graphics operations and updates the contents of the front buffer with the back buffer, making the contents of the back buffer to appear on the handheld's physical display. This technique allows applications to perform multiple operations on the back buffer and then flush all changes at once to the front buffer. This is done automatically after a paint, but an application may choose to do it explicitly when performing animations.

Drawing on the back buffer is done with methods on the Graphics object returned from Screen.getGraphics(), and these will be clipped to the extent of the screen. Note that Screen.getGraphics() may in some circumstances return an off-screen buffer.