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 PRIORITY_HIGH
          Priority for High priority application global status screens.
static int PRIORITY_LOW
          Priority for Low priority application global status screens.
static int PRIORITY_MAX
          Maximum priority for global status screens that applications may use.
static int PRIORITY_MIN
          Minimum priority for global status screens that applications may use.
static int PRIORITY_NORMAL
          Priority for Normal priority application global status screens.
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  void addInputSettings(InputSettings settings)
          Applies attributes in the specified InputSettings object to this UiEngineInstance.
abstract  void clearInputSettings()
          Removes all custom input settings this UiEngineInstance and revert to defaults.
abstract  void getInputSettings(InputSettings settings)
          Retrieves the values for the attributes in the specified InputSettings object for this screen.
abstract  TransitionContext getTransition(Screen fromScreen, Screen toScreen, int trigger)
          Retrieve the animation previously set for the fromScreen/toScreen/trigger combination.
abstract  void removeInputSettings(InputSettings settings)
          Removes attributes in the specified InputSettings object from this UiEngineInstance.
abstract  void setAcceptableDirections(int directions)
          Sets the acceptable display directions for your application, which is relative to the location of the BlackBerry logo.
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 global 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 false, pushing the screen will suppress the display of any global screens of lower priority.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

PRIORITY_HIGH

public static final int PRIORITY_HIGH

Priority for High priority application global status screens.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PRIORITY_LOW

public static final int PRIORITY_LOW

Priority for Low priority application global status screens.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PRIORITY_MAX

public static final int PRIORITY_MAX

Maximum priority for global status screens that applications may use.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PRIORITY_MIN

public static final int PRIORITY_MIN

Minimum priority for global status screens that applications may use.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

PRIORITY_NORMAL

public static final int PRIORITY_NORMAL

Priority for Normal priority application global status screens.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Method Detail

setAcceptableDirections

public abstract void setAcceptableDirections(int directions)
Sets the acceptable display directions for your application, which is relative to the location of the BlackBerry logo.

This method prevents the device from orienting the application in an unacceptable direction, but it does not actually rotate the application. It works independently of the accelerometer, so you can use it for devices that do not have an accelerometer (for example, display an application in landscape view on a BlackBerry® Pearl™ smartphone). When you invoke this method with a direction parameter that is different from the device's current orientation, the screen direction does not automatically change. When the device is rotated (even to a direction that is not supported), the display orientation is re-evaluated, and a rotation occurs to a direction that is supported by the provided parameter.

The direction is north when the top of the drawable area is the screen side closest to the BlackBerry logo; the direction is west when the top of the drawable area is to the left of the BlackBerry logo; the direction is east when the top of the drawable area is to the right of the BlackBerry logo. If a user holds the BlackBerry device with the BlackBerry logo at the top, the screen is in portrait orientation. If the user rotates the device 90 degrees to the left or right, the screen is in landscape orientation.

Parameters:
directions - The acceptable values for directions relative to the location of the BlackBerry logo. The values can be the following:
Throws:
IllegalArgumentException - if a directions value other than the accepted values is used.
Since:
BlackBerry API 4.7.0

addInputSettings

public abstract void addInputSettings(InputSettings settings)
Applies attributes in the specified InputSettings object to this UiEngineInstance. May be invoked multiple times to apply additional input settings. Does nothing if the specified InputSettings object is not associated with a supported input device. Note that the settings are applied when an input screen within this UiEngineInstance gains focus or immediately if already in focus. Note also that this only *adds* settings. If a particular setting is ommitted from the InputSettings list it is not removed/reverted. To remove one or more settings (reverting them to defaults), use removeInputSettings().

Parameters:
settings - InputSettings object to be applied to this UiEngineInstance.
Throws:
IllegalArgumentException - If settings is null or associated with an unrecognized input device (see net.rim.device.api.ui.input for a list of available (recognized) input devices.
Since:
BlackBerry API 6.0.0

removeInputSettings

public abstract void removeInputSettings(InputSettings settings)
Removes attributes in the specified InputSettings object from this UiEngineInstance. May be invoked multiple times to remove input settings. Does nothing if the specified attributes do not exist or InputSettings object is not associated with a supported input device. Note that the updated settings are applied when an input screen within this UiEngineInstance gains focus or immediately if already in focus.

Parameters:
settings - InputSettings object to be removed from this UiEngineInstance.
Throws:
IllegalArgumentException - If settings is null or associated with an unrecognized input device (see net.rim.device.api.ui.input for a list of available (recognized) input devices.
Since:
BlackBerry API 6.0.0

clearInputSettings

public abstract void clearInputSettings()
Removes all custom input settings this UiEngineInstance and revert to defaults. Does nothing if no custom input settings exist. Note that default settings are applied when an input screen within this UiEngineInstance gains focus or immediately if already in focus.

Since:
BlackBerry API 6.0.0

getInputSettings

public abstract void getInputSettings(InputSettings settings)
Retrieves the values for the attributes in the specified InputSettings object for this screen. The values can be obtained by invoking InputSettings.get(int) once the method returns. Does nothing if this screen does not accept input and/or the specified attributes do not exist or InputSettings object is not associated with a supported input device.

Parameters:
settings - InputSettings object to be populated with values.
Throws:
IllegalArgumentException - If settings is null or associated with an unrecognized input device (see net.rim.device.api.ui.input for a list of available (recognized) input devices.
Since:
BlackBerry API 6.0.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-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal