net.rim.device.api.ui
Class TransitionContext

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

public final class TransitionContext
extends Object

The TransitionContext class contains all the necessary data to uniquely describe a transition animation between two screens. An instance of this class represents one of the following five types of standard animations: TransitionContext.TRANSITION_FADE, TransitionContext.TRANSITION_SLIDE, TransitionContext.TRANSITION_WIPE, TransitionContext.TRANSITION_ZOOM, and TransitionContext.TRANSITION_NONE.

Each animation type supports a set of attributes that allow its behavior to be customized. More animation types or attributes may be exposed in the future. The following table lists the attributes supported by each type of animation, their valid values, and their default values:

Transition Attribute Value Default
TransitionContext.TRANSITION_FADE TransitionContext.ATTR_DURATION time in milliseconds (max = 1000) 250
TransitionContext.ATTR_KIND TransitionContext.KIND_IN or TransitionContext.KIND_OUT TransitionContext.KIND_IN
TransitionContext.TRANSITION_SLIDE TransitionContext.ATTR_DURATION time in milliseconds (max = 1000) 250
TransitionContext.ATTR_KIND TransitionContext.KIND_IN or TransitionContext.KIND_OUT TransitionContext.KIND_IN
TransitionContext.ATTR_DIRECTION TransitionContext.DIRECTION_LEFT, TransitionContext.DIRECTION_RIGHT, TransitionContext.DIRECTION_UP, or TransitionContext.DIRECTION_DOWN TransitionContext.DIRECTION_LEFT
TransitionContext.ATTR_STYLE TransitionContext.STYLE_PUSH or TransitionContext.STYLE_OVER TransitionContext.STYLE_PUSH
TransitionContext.TRANSITION_WIPE TransitionContext.ATTR_DURATION time in milliseconds (max = 1000) 250
TransitionContext.ATTR_KIND TransitionContext.KIND_IN or TransitionContext.KIND_OUT TransitionContext.KIND_IN
TransitionContext.ATTR_DIRECTION TransitionContext.DIRECTION_LEFT, TransitionContext.DIRECTION_RIGHT, TransitionContext.DIRECTION_UP, or TransitionContext.DIRECTION_DOWN TransitionContext.DIRECTION_LEFT
TransitionContext.TRANSITION_ZOOM TransitionContext.ATTR_DURATION time in milliseconds (max = 1000) 250
TransitionContext.ATTR_KIND TransitionContext.KIND_IN or TransitionContext.KIND_OUT TransitionContext.KIND_IN
TransitionContext.ATTR_SCALE percentage of orignal size to zoom to/from (max = 200) 0
TransitionContext.TRANSITION_NONE none none none

A fade-in transition (TransitionContext.ATTR_KIND = TransitionContext.KIND_IN) animates a screen from 0% opacity to 100% opacity. A fade-out transition (TransitionContext.ATTR_KIND = TransitionContext.KIND_OUT) animates a screen from 100% opacity to 0% opacity.

A slide-in transition (TransitionContext.ATTR_KIND = TransitionContext.KIND_IN) starts with the screen outside the bounds of the display and moves it into view. A slide-out transition (TransitionContext.ATTR_KIND = TransitionContext.KIND_OUT) starts with the screen at its current position and moves it off the display. The direction attribute controls which path the screen takes as it enters or leaves the display. The style attribute indicates if the incoming screen slides over the outgoing screen (TransitionContext.ATTR_STYLE = TransitionContext.STYLE_OVER) or if it displaces the outgoing screen as it moves so they both animate (TransitionContext.ATTR_STYLE = TransitionContext.STYLE_PUSH).

A wipe-in transition (TransitionContext.ATTR_KIND = TransitionContext.KIND_IN) starts with the screen hidden and animates the clipping region to fully reveal it. A wipe-out transition (TransitionContext.ATTR_KIND = TransitionContext.KIND_OUT) starts with the screen being visible and collapses the clipping region until the screen is completely hidden. The direction attribute controls which way the clipping region expands/contracts.

A zoom-in transition (TransitionContext.ATTR_KIND = TransitionContext.KIND_IN) scales the screen image from a size greater/less than 100% to 100%. A zoom-out transition (TransitionContext.ATTR_KIND = TransitionContext.KIND_OUT) scales the screen image from 100% to a size greater/less than 100%. The scale attribute (TransitionContext.ATTR_SCALE) indicates the percentage of the screen's original size to zoom to/from.

The none transition indicates no animation should occur. It is useful because you can setup a screen transition rule that applies to several screens and use the none transition to exclude a particular screen from this rule.

Since:
BlackBerry API 5.0.0

Field Summary
static int ATTR_DIRECTION
          Attribute that indicates the path of movement for an animation.
static int ATTR_DURATION
          Attribute that controls the elapsed time of the transition animation in milliseconds.
static int ATTR_KIND
          Attribute that indicates whether the incoming or outgoing screen is animated.
static int ATTR_SCALE
          Attribute that controls the percentage of the screen's original size to zoom to/from.
static int ATTR_STYLE
          Attribute for the slide transition that controls whether the outgoing screen also animates or not.
static int DIRECTION_DOWN
          Value for the direction attribute indicating that movement should occur to downwards.
static int DIRECTION_LEFT
          Value for the direction attribute indicating that movement should occur to the left.
static int DIRECTION_RIGHT
          Value for the direction attribute indicating that movement should occur to the right.
static int DIRECTION_UP
          Value for the direction attribute indicating that movement should occur to upwards.
static int KIND_IN
          Value for the kind attribute that indicates the screen that is pushed or exposed is animated.
static int KIND_OUT
          Value for the kind attribute that indicates the screen that is popped or hidden is animated.
static int STYLE_OVER
          Value for the style attribute indicating that the incoming screen slides over the outgoing screen.
static int STYLE_PUSH
          Value for the style attribute indicating that the incoming screen pushes the outgoing screen off the display.
static int TRANSITION_FADE
          Constant for a fade transition.
static int TRANSITION_NONE
          Constant for no transition.
static int TRANSITION_SLIDE
          Constant for a slide transition.
static int TRANSITION_WIPE
          Constant for a wipe transition.
static int TRANSITION_ZOOM
          Constant for a zoom transition.
 
Constructor Summary
TransitionContext(int transitionId)
          Creates a new TransitionContext object that represents the specified transition type.
 
Method Summary
 void clearAllAttributes()
          Clears previously set values for all attributes.
 void clearAttribute(int attrId)
          Clears a previously set value for the specified attribute.
 IntEnumeration enumAttributes()
          Returns the id's of all attributes set for this transition.
 Object getAttribute(int attrId)
          Retrieves the value previously set for the specified attribute of this transition.
 int getAttributeCount()
          Returns the number of attributes set for this transition.
 int getIntAttribute(int attrId)
          Retrieves the integer value previously set for the specified attribute of this transition.
 int getTransitionId()
          Returns the transition type represented by this context.
 boolean isAttributeSet(int attrId)
          Checks if the specified attribute is set.
 void setAttribute(int attrId, Object attrValue)
          Sets a value for the specified attribute of the transition.
 void setIntAttribute(int attrId, int attrValue)
          Sets an integer value for the specified attribute of the transition.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

TRANSITION_FADE

public static final int TRANSITION_FADE
Constant for a fade transition. Valid attributes are TransitionContext.ATTR_DURATION and TransitionContext.ATTR_KIND.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

TRANSITION_SLIDE

public static final int TRANSITION_SLIDE
Constant for a slide transition. Valid attributes are TransitionContext.ATTR_DURATION, TransitionContext.ATTR_KIND, TransitionContext.ATTR_DIRECTION, and TransitionContext.ATTR_STYLE.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

TRANSITION_WIPE

public static final int TRANSITION_WIPE
Constant for a wipe transition. Valid attributes are TransitionContext.ATTR_DURATION, TransitionContext.ATTR_KIND, and TransitionContext.ATTR_DIRECTION.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

TRANSITION_ZOOM

public static final int TRANSITION_ZOOM
Constant for a zoom transition. Valid attributes are TransitionContext.ATTR_DURATION, TransitionContext.ATTR_KIND, and TransitionContext.ATTR_SCALE.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

TRANSITION_NONE

public static final int TRANSITION_NONE
Constant for no transition. No attributes are valid.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

ATTR_DURATION

public static final int ATTR_DURATION
Attribute that controls the elapsed time of the transition animation in milliseconds. Value is as an integer. The maximum allowed value is 1000 ms. If a value is specified that exceeds the max, it will be clamped.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

ATTR_KIND

public static final int ATTR_KIND
Attribute that indicates whether the incoming or outgoing screen is animated. Valid values are: TransitionContext.KIND_IN and TransitionContext.KIND_OUT.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

ATTR_DIRECTION

public static final int ATTR_DIRECTION
Attribute that indicates the path of movement for an animation. Valid values are: TransitionContext.DIRECTION_LEFT, TransitionContext.DIRECTION_RIGHT, TransitionContext.DIRECTION_UP, and TransitionContext.DIRECTION_DOWN.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

ATTR_STYLE

public static final int ATTR_STYLE
Attribute for the slide transition that controls whether the outgoing screen also animates or not. Valid values are: TransitionContext.STYLE_PUSH and TransitionContext.STYLE_OVER.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

ATTR_SCALE

public static final int ATTR_SCALE
Attribute that controls the percentage of the screen's original size to zoom to/from. Value is as percentage expressed as an integer (i.e. 100 = 100%). The maximum allowed value is 200. If a value is specified that exceeds the max, it will be clamped.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

KIND_IN

public static final int KIND_IN
Value for the kind attribute that indicates the screen that is pushed or exposed is animated.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

KIND_OUT

public static final int KIND_OUT
Value for the kind attribute that indicates the screen that is popped or hidden is animated.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DIRECTION_LEFT

public static final int DIRECTION_LEFT
Value for the direction attribute indicating that movement should occur to the left.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DIRECTION_RIGHT

public static final int DIRECTION_RIGHT
Value for the direction attribute indicating that movement should occur to the right.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DIRECTION_UP

public static final int DIRECTION_UP
Value for the direction attribute indicating that movement should occur to upwards.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

DIRECTION_DOWN

public static final int DIRECTION_DOWN
Value for the direction attribute indicating that movement should occur to downwards.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

STYLE_PUSH

public static final int STYLE_PUSH
Value for the style attribute indicating that the incoming screen pushes the outgoing screen off the display.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

STYLE_OVER

public static final int STYLE_OVER
Value for the style attribute indicating that the incoming screen slides over the outgoing screen.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Constructor Detail

TransitionContext

public TransitionContext(int transitionId)
Creates a new TransitionContext object that represents the specified transition type. Valid values are: TransitionContext.TRANSITION_FADE, TransitionContext.TRANSITION_SLIDE, TransitionContext.TRANSITION_WIPE, TransitionContext.TRANSITION_ZOOM, and TransitionContext.TRANSITION_NONE.

Parameters:
transitionId - The id of the transition this context should represent.
Since:
BlackBerry API 5.0.0


Method Detail

getTransitionId

public int getTransitionId()
Returns the transition type represented by this context.

Returns:
The id of the transition this context represents.
Since:
BlackBerry API 5.0.0

getAttributeCount

public int getAttributeCount()
Returns the number of attributes set for this transition. If no attributes are overridden from their default values, zero is returned.

Returns:
The number of overridden attributes in the transition.
Since:
BlackBerry API 5.0.0

enumAttributes

public IntEnumeration enumAttributes()
Returns the id's of all attributes set for this transition.

Returns:
An enumeration of the all the attribute id's set for the context.
Since:
BlackBerry API 5.0.0

isAttributeSet

public boolean isAttributeSet(int attrId)
Checks if the specified attribute is set.

Parameters:
attrId - The unique id of the attribute to check.
Returns:
True if a value was previously set for the attribute; false otherwise (default value used).
Since:
BlackBerry API 5.0.0

getAttribute

public Object getAttribute(int attrId)
Retrieves the value previously set for the specified attribute of this transition.

Parameters:
attrId - The unique id of the attribute to retrieve.
Returns:
The value of the attribute.
Throws:
IllegalArgumentException - Thrown if no value was previously set.
Since:
BlackBerry API 5.0.0

getIntAttribute

public int getIntAttribute(int attrId)
Retrieves the integer value previously set for the specified attribute of this transition.

Parameters:
attrId - The unique id of the attribute to retrieve.
Returns:
The integer value of the attribute.
Throws:
IllegalArgumentException - Thrown if no value was previously set or the value is not an integer.
Since:
BlackBerry API 5.0.0

setAttribute

public void setAttribute(int attrId,
                         Object attrValue)
Sets a value for the specified attribute of the transition. No validation occurs for attributes. Invalid attributes or values are simply ignored. Each type of transition has its own set of valid attributes. See the table above for details. If the attribute was previously set, its value is replaced.

Parameters:
attrId - The unique id of the attribute to set.
attrValue - The value to set for the attribute.
Throws:
IllegalArgumentException - Thrown if value is null.
Since:
BlackBerry API 5.0.0

setIntAttribute

public void setIntAttribute(int attrId,
                            int attrValue)
Sets an integer value for the specified attribute of the transition. No validation occurs for attributes. Invalid attributes or values are simply ignored. Each type of transition has its own set of valid attributes. See the table above for details. If the attribute was previously set, its value is replaced.

Parameters:
attrId - The unique id of the attribute to set.
attrValue - The integer value to set for the attribute.
Since:
BlackBerry API 5.0.0

clearAttribute

public void clearAttribute(int attrId)
Clears a previously set value for the specified attribute. The default value will be used instead.

Parameters:
attrId - The unique id of the attribute to clear.
Since:
BlackBerry API 5.0.0

clearAllAttributes

public void clearAllAttributes()
Clears previously set values for all attributes. Default values will be used for all instead.

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.