net.rim.device.api.ui
Interface UiEngine

All Known Implementing Classes:
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

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()
          Update the LCD display for all the screens in this application.
 

Field Detail

GLOBAL_MODAL

public static final int GLOBAL_MODAL
For pushGlobalScreen(). If true, the method should block until the screen closes.
Since:
JDE 4.2.0

GLOBAL_QUEUE

public static final int GLOBAL_QUEUE
For pushGlobalScreen(). If true, the screen will be inserted below screens of equal priority. Otherwise, it will be inserted above them.
Since:
JDE 4.2.0

GLOBAL_SHOW_LOWER

public static final int GLOBAL_SHOW_LOWER
For pushGlobalScreen(). If true, pushing the screen will suppress the display of any screens of lower priority.
Since:
JDE 4.2.0
Method Detail

dismissStatus

public 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

public Screen getActiveScreen()
Retrieves handle for the active screen.


getScreenCount

public int getScreenCount()
Retrieves the number of screens currently on the display stack.

Returns:
Number of screens on the display stack.

isPaintingSuspended

public boolean isPaintingSuspended()
Determines if repainting is currently suspended.
Returns:
True if painting is currently suspended; otherwise, returns false.

popScreen

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

pushGlobalScreen

public 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:
4.0

pushGlobalScreen

public 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:
JDE 4.2.0

pushModalScreen

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

Parameters:
screen - Screen to push.

pushScreen

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

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

Parameters:
screen - Screen to push.

queueStatus

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

relayout

public void relayout()
Updates the layout of all screens and repaints.

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


repaint

public void repaint()
Repaints entire display.

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


suspendPainting

public 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

public void updateDisplay()
Update the LCD display for all the screens in this application.



Copyright 1999-2007 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.