net.rim.device.api.ui
Class TransitionContext

java.lang.Object
  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