net.rim.device.api.ui
Class UiEngineInstance

java.lang.Object
  extended by net.rim.device.api.ui.UiEngineInstance

public abstract class UiEngineInstance
extends Object

User interface (UI) engine instance associated with an application or process, acquired by calling Ui.getUiEngineInstance(). See UiApplication and UiEngine.

Since:
BlackBerry API 4.7.0

Field Summary
static int GLOBAL_MODAL
          For pushGlobalScreen().
static int GLOBAL_QUEUE
          For pushGlobalScreen().
static int GLOBAL_SHOW_LOWER
          For pushGlobalScreen().
static int TRIGGER_POP
          Value for the trigger argument in UiEngineInstance.setTransition(net.rim.device.api.ui.Screen, net.rim.device.api.ui.Screen, int, net.rim.device.api.ui.TransitionContext) indicating that an animation occurs when a screen is popped off the display.
static int TRIGGER_PUSH
          Value for the trigger argument in UiEngineInstance.setTransition(net.rim.device.api.ui.Screen, net.rim.device.api.ui.Screen, int, net.rim.device.api.ui.TransitionContext) indicating that an animation occurs when a screen is pushed onto the display.
 
Method Summary
abstract  TransitionContext getTransition(Screen fromScreen, Screen toScreen, int trigger)
          Retrieve the animation previously set for the fromScreen/toScreen/trigger combination.
abstract  void setAcceptableDirections(int directions)
          This function allows the setting of acceptable directions for the application, relative to the LCD.
abstract  void setTransition(Screen fromScreen, Screen toScreen, int trigger, TransitionContext transition)
          Register the animation in the specified TransitionContext to be executed when fromScreen transitions to toScreen as the result of toScreen being pushed (trigger = TRIGGER_PUSH) or the fromScreen being popped (trigger = TRIGGER_POP).
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

TRIGGER_PUSH

public static final int TRIGGER_PUSH
Value for the trigger argument in UiEngineInstance.setTransition(net.rim.device.api.ui.Screen, net.rim.device.api.ui.Screen, int, net.rim.device.api.ui.TransitionContext) indicating that an animation occurs when a screen is pushed onto the display.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

TRIGGER_POP

public static final int TRIGGER_POP
Value for the trigger argument in UiEngineInstance.setTransition(net.rim.device.api.ui.Screen, net.rim.device.api.ui.Screen, int, net.rim.device.api.ui.TransitionContext) indicating that an animation occurs when a screen is popped off the display.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

GLOBAL_MODAL

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

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.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.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Method Detail

setAcceptableDirections

public abstract void setAcceptableDirections(int directions)
This function allows the setting of acceptable directions for the application, relative to the LCD. The acceptable values for directions relative to the smartphone's LCD are Display.DIRECTION_NORTH, Display.DIRECTION_EAST, Display.DIRECTION_WEST, Display.DIRECTION_LANDSCAPE, Display.DIRECTION_PORTRAIT, or some bit-wise ORed combination thereof, including 0. Other values result in an IllegalArgumentException being thrown. Invoking this method with a direction parameter different from the current device direction does not automatically change the screen direction. The screen direction only changes once the device is rotated to a direction supported by the provided direction parameter.

Parameters:
directions - The acceptable values for directions relative to the smartphone's LCD.
Since:
BlackBerry API 4.7.0

setTransition

public abstract void setTransition(Screen fromScreen,
                                   Screen toScreen,
                                   int trigger,
                                   TransitionContext transition)
Register the animation in the specified TransitionContext to be executed when fromScreen transitions to toScreen as the result of toScreen being pushed (trigger = TRIGGER_PUSH) or the fromScreen being popped (trigger = TRIGGER_POP). If fromScreen, toScreen, or both are omitted, any screen is assumed (similar to a wildcard) and a general rule is used that will respectively match "fromScreen to any", "any to toScreen", or "any to any". If a previous transition was registered for the same fromScreen/toScreen/trigger combination, it is replaced with the new transition. If transition is null it will clear any previously set transition for the fromScreen/toScreen/trigger combination.

A transition that defines both fromScreen and toScreen takes precedence over a transition than defines only one screen which in turn takes precedence over a transition that defines neither screen. Also, a transition defined by this API will take precedence over a conflicting transition defined in the theme. The following search order defines how a transition is chosen when screen A is incoming and screen B is outgoing:

  1. Is a transition set for fromScreen = B and toScreen = A?
  2. Is the none transition set for fromScreen = null and toScreen = A?
  3. Is the none transition set for fromScreen = B and toScreen = null?
  4. Is a transition set for fromScreen = null and toScreen = A?
  5. Is a transition set for fromScreen = B and toScreen = null?
  6. Is a transition set for fromScreen = null and toScreen = null?
  7. Is a transition defined in the theme?

This method will retain a reference to the screen objects passed into it until the application terminates. To ensure screens are properly garbage collected when they are no longer needed, an application must also clear any transitions previously set for them. All transitions set by an application are cleared when the application terminates.

Parameters:
fromScreen - The outgoing screen that causes the transition or null to specify any screen.
toScreen - The incoming screen that causes the transition or null to specify any screen.
trigger - The change in the screen stack that causes the transition. Valid values are TRIGGER_PUSH and TRIGGER_POP.
transition - The context which uniquely describes the animation to execute.
Throws:
IllegalArgumentException - Thrown if the transition type or trigger is not supported.
Since:
BlackBerry API 5.0.0

getTransition

public abstract TransitionContext getTransition(Screen fromScreen,
                                                Screen toScreen,
                                                int trigger)
Retrieve the animation previously set for the fromScreen/toScreen/trigger combination. If fromScreen, toScreen, or both are omitted, any screen is assumed (similar to a wildcard) and a general rule is used that will respectively match "fromScreen to any", "any to toScreen", or "any to any".

Parameters:
fromScreen - The outgoing screen that causes the transition or null to specify any screen.
toScreen - The incoming screen that causes the transition or null to specify any screen.
trigger - The change in the screen stack that causes the transition. Valid values are TRIGGER_PUSH and TRIGGER_POP.
Returns:
The context which uniquely describes the animation to execute.
Throws:
IllegalArgumentException - Thrown if the trigger is not supported.
Since:
BlackBerry API 5.0.0





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.