universum.studios.android.transition

Class BaseNavigationalTransition<T extends BaseNavigationalTransition>

java.lang.Object

universum.studios.android.transition.BaseNavigationalTransition<T>

Direct Known Subclasses:

NavigationalTransition, NavigationalTransitionCompat

public abstract class BaseNavigationalTransition<T extends BaseNavigationalTransition>
extends Object

BaseNavigationalTransition represents a simple wrapper around window Transitions framework to simplify and also to made transitioning between two Activities independent from the current Android version, that is, to hide such transitions implementation from the context where it is used.

A specific navigational transition implementation may be associated with its corresponding activity class that can be supplied to BaseNavigationalTransition(Class) constructor. This class is used to create an instance of Intent that will be by default started whenever start(Activity) is invoked. Both onStart(Activity) and onFinish(Activity) methods cen be overridden by a specific transition implementations to match theirs specific needs.

Sample

 public abstract class DetailTransition extends BaseNavigationalTransition {

     DetailTransition() {
         super(DetailActivity.class);
     }

     @NonNull
     public static DetailTransition get() {
          return UiConfig.MATERIAL_SUPPORT ? new MaterialTransition() : new DefaultTransition();
     }

     @Override
     public Intent createIntent(@NonNull Activity caller) {
         final Intent intent = super.createIntent(caller);
         // ... put here any extras that need to be delivered to the called activity
         return intent;
     }

     static final class DefaultTransition extends DetailTransition {

          @Override
          protected void onStart(@NonNull Activity caller) {
              super.onStart(caller);
              // ... change activities with custom window animation
              WindowTransition.overrideStart(caller);
          }

          @Override
          protected void onFinish(@NonNull Activity caller) {
              super.onFinish(caller);
              // ... change activities without animation
              caller.overridePendingTransition(0, 0);
          }
     }

     // ... other implementations specific for a different platform versions

     static final class MaterialTransition extends DetailTransition {

          @Override
          protected void onStart(@NonNull Activity caller) {
              // ... made some modifications to the caller's UI (if necessary) before the transitions
              // ... are triggered.
              super.onStart(caller);
          }

          @Override
          protected void onFinish(@NonNull Activity caller) {
              super.onFinish(caller);
              // ... no need to override in most cases
          }
     }
 }
 

Author:

Martin Albedinsky

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	MATERIAL_SUPPORT Boolean flag indicating whether the current Android device can run Material Design like navigational transition (i.
protected Class<? extends Activity>	mClassOfTransitionActivity Class of activity that should be started as new Intent whenever this navigational transition is started via start(Activity).
static int	RC_NONE Flag determining that no request code has been specified for a specific navigational transition.

Constructor Summary

Constructors

Constructor and Description
BaseNavigationalTransition() Creates a new instance of NavigationalTransition without transition activity class.
BaseNavigationalTransition(Class<? extends Activity> classOfTransitionActivity) Creates a new instance of NavigationalTransition with the specified class of transition activity.

Method Summary

Modifier and Type	Method and Description
boolean	allowEnterTransitionOverlap() Returns boolean flag indicating whether enter transition may overlap or not.
T	allowEnterTransitionOverlap(boolean allow) Specifies a boolean flag to be set to a window of an incoming activity in order to indicate whether enter transition may overlap or not.
boolean	allowReturnTransitionOverlap() Returns boolean flag indicating whether return transition may overlap or not.
T	allowReturnTransitionOverlap(boolean allow) Specifies a boolean flag to be set to a window of an incoming activity in order to indicate whether return transition may overlap or not.
void	configureIncomingTransitions(Activity activity) Performs configuration of the given activity's window by attaching to it enter and return transitions (those for shared elements including) specified for this navigational transition.
void	configureOutgoingTransitions(Activity activity) Performs configuration of the given activity's window by attaching to it reenter and exit transitions (those for shared elements including) specified for this navigational transition.
void	configureTransitions(Activity activity) This method groups calls to configureIncomingTransitions(Activity) and configureOutgoingTransitions(Activity) into one call.
Intent	createIntent(Activity caller) Creates an intent that can be used to start activity for which is this transition created.
Transition	enterTransition() Returns enter transition for the incoming activity.
T	enterTransition(Transition transition) Specifies enter transition to be attached to a window of an incoming activity.
Transition	exitTransition() Returns exit transition for the outgoing activity.
T	exitTransition(Transition transition) Specifies exit transition to be attached to a window of an outgoing activity whenever start(Activity) is invoked.
void	finish(Activity caller) Finishes the given caller activity in order to run its exit transitions.
protected void	finishCaller(Activity caller) Finishes the specified caller activity either via Activity.finishAfterTransition() or via Activity.finish() depending on the current API capabilities.
protected void	finishCallerDelayed(Activity caller, long delay) Like finishCaller(Activity) but this will postpone the finishing by the requested delay.
Class<? extends Activity>	getActivityClass() Returns the class of activity specified for this navigational transition.
Transition	inflateTransition(Context context, int resource) Inflates a new instance of Transition from the specified resource.
TransitionManager	inflateTransitionManager(Context context, int resource, ViewGroup sceneRoot) Inflates a new instance of TransitionManager from the specified resource.
Bundle	intentExtras() Returns the bundle with extras for the incoming activity.
T	intentExtras(Bundle extras) Specifies a bundle with extras for the incoming activity.
ActivityOptions	makeSceneTransitionAnimation(Activity caller) Creates a new instance of ActivityOptions for the specified caller activity.
protected void	onFinish(Activity caller) Invoked whenever finish(Activity) is called.
protected void	onFinishCaller(Activity caller) Invoked whenever finishCaller(Activity) or finishCallerDelayed(Activity, long) is called.
protected void	onStart(Activity caller) Invoked whenever start(Activity) is called.
Transition	reenterTransition() Returns reenter transition for the outgoing activity.
T	reenterTransition(Transition transition) Specifies reenter transition to be attached to a window of an outgoing activity whenever start(Activity) is invoked.
int	requestCode() Returns the request code specified via requestCode(int).
T	requestCode(int requestCode) Specifies a request code that should be used to start activity specific for this navigational transition for result.
Transition	returnTransition() Returns return transition for the incoming activity.
T	returnTransition(Transition transition) Specifies return transition to be attached to a window of an incoming activity.
T	sharedElement(View element, String elementName) Adds shared element that should be transferred to the transitioning (called) activity via ActivityOptions as Bundle.
Transition	sharedElementEnterTransition() Returns shared element enter transition for the incoming activity.
T	sharedElementEnterTransition(Transition transition) Specifies enter transition for shared element to be attached to a window of an incoming activity.
Transition	sharedElementExitTransition() Returns shared element exit transition for the outgoing activity.
T	sharedElementExitTransition(Transition transition) Specifies exit transition for shared element to be attached to a window of an outgoing activity whenever start(Activity) is invoked.
Transition	sharedElementReenterTransition() Returns shared element reenter transition for the outgoing activity.
T	sharedElementReenterTransition(Transition transition) Specifies reenter transition for shared element to be attached to a window of an outgoing activity whenever start(Activity) is invoked.
Transition	sharedElementReturnTransition() Returns shared element return transition for the incoming activity.
T	sharedElementReturnTransition(Transition transition) Specifies return transition for shared element to be attached to a window of an incoming activity.
List<Pair<View,String>>	sharedElements() Returns a list of all shared elements specified for this navigational transition.
T	sharedElements(Pair<View,String>... elements) Bulk method for adding shared element pairs into this navigational transition.
boolean	sharedElementsUseOverlay() Returns boolean flag indicating whether shared elements should use overlay or not.
T	sharedElementsUseOverlay(boolean useOverlay) Specifies a boolean flag to be set to a window of an incoming or outgoing activity in order to indicate whether shared elements should use overlay or not.
Pair<View,String>	singleSharedElement() Returns the single shared element at the 0 position among the current shared elements.
void	start(Activity caller) Starts this navigational transition using the given caller activity with transitions and shared elements that are configured for the activity via configureOutgoingTransitions(Activity).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MATERIAL_SUPPORT

public static final boolean MATERIAL_SUPPORT

Boolean flag indicating whether the current Android device can run Material Design like navigational transition (i. e. with shared elements, ...) or not.

RC_NONE

public static final int RC_NONE

Flag determining that no request code has been specified for a specific navigational transition.

See Also:

Constant Field Values

mClassOfTransitionActivity

protected final Class<? extends Activity> mClassOfTransitionActivity

Class of activity that should be started as new Intent whenever this navigational transition is started via start(Activity).

Constructor Detail

BaseNavigationalTransition

public BaseNavigationalTransition()

Creates a new instance of NavigationalTransition without transition activity class.

BaseNavigationalTransition

public BaseNavigationalTransition(@NonNull
                                  Class<? extends Activity> classOfTransitionActivity)

Creates a new instance of NavigationalTransition with the specified class of transition activity.

Parameters:

classOfTransitionActivity - The activity class that should be used to create a new Intent that to be started whenever start(Activity) is called upon this navigational transition.

Method Detail

getActivityClass

@Nullable
public final Class<? extends Activity> getActivityClass()

Returns the class of activity specified for this navigational transition.

Returns:

This transitions's associated activity class or null if not activity class has been specified.

See Also:

BaseNavigationalTransition(Class)

intentExtras

public T intentExtras(@Nullable
                      Bundle extras)

Specifies a bundle with extras for the incoming activity. The given bundle will be attached to this transition's Intent via Intent.putExtras(Bundle) when it is created via createIntent(Activity).

Parameters:

extras - The desired bundle with extras. May be null to clear the current one.

Returns:

This transition to allow methods chaining.

See Also:

intentExtras()

intentExtras

@NonNull
public Bundle intentExtras()

Returns the bundle with extras for the incoming activity.

This will be either bundle specified via intentExtras(Bundle) or created by default when this method is called for the first time.

Returns:

The extras bundle for the incoming activity.

See Also:

intentExtras(Bundle)

requestCode

public T requestCode(int requestCode)

Specifies a request code that should be used to start activity specific for this navigational transition for result.

Default value: RC_NONE

Parameters:

requestCode - The desired request code. Can be RC_NONE to not start activity for result.

Returns:

This transition to allow methods chaining.

See Also:

requestCode(), Activity.startActivityForResult(Intent, int), Activity.startActivityForResult(Intent, int, Bundle), Fragment.startActivityForResult(Intent, int)

requestCode

public int requestCode()

Returns the request code specified via requestCode(int).

Returns:

Specified request code or RC_NONE by default.

enterTransition

public T enterTransition(@Nullable
                         Transition transition)

Specifies enter transition to be attached to a window of an incoming activity.

Returns:

This transition to allow methods chaining.

See Also:

enterTransition(), Window.setEnterTransition(Transition), inflateTransition(Context, int), configureIncomingTransitions(Activity)

enterTransition

@Nullable
public Transition enterTransition()

Returns enter transition for the incoming activity.

Returns:

Transition specified via enterTransition(Transition) or null by default.

reenterTransition

public T reenterTransition(@Nullable
                           Transition transition)

Specifies reenter transition to be attached to a window of an outgoing activity whenever start(Activity) is invoked.

Returns:

This transition to allow methods chaining.

See Also:

reenterTransition(), Window.setReenterTransition(Transition), inflateTransition(Context, int), configureOutgoingTransitions(Activity)

reenterTransition

@Nullable
public Transition reenterTransition()

Returns reenter transition for the outgoing activity.

Returns:

Transition specified via reenterTransition(Transition) or null by default.

returnTransition

public T returnTransition(@Nullable
                          Transition transition)

Specifies return transition to be attached to a window of an incoming activity.

Returns:

This transition to allow methods chaining.

See Also:

returnTransition(), Window.setReturnTransition(Transition), inflateTransition(Context, int), configureIncomingTransitions(Activity)

returnTransition

@Nullable
public Transition returnTransition()

Returns return transition for the incoming activity.

Returns:

Transition specified via returnTransition(Transition) or null by default.

exitTransition

public T exitTransition(@Nullable
                        Transition transition)

Specifies exit transition to be attached to a window of an outgoing activity whenever start(Activity) is invoked.

Returns:

This transition to allow methods chaining.

See Also:

exitTransition(), Window.setExitTransition(Transition), inflateTransition(Context, int), configureOutgoingTransitions(Activity)

exitTransition

@Nullable
public Transition exitTransition()

Returns exit transition for the outgoing activity.

Returns:

Transition specified via exitTransition(Transition) or null by default.

allowEnterTransitionOverlap

public T allowEnterTransitionOverlap(boolean allow)

Specifies a boolean flag to be set to a window of an incoming activity in order to indicate whether enter transition may overlap or not.

Default value: unspecified

Returns:

This transition to allow methods chaining.

See Also:

allowEnterTransitionOverlap(), Window.setAllowEnterTransitionOverlap(boolean), configureIncomingTransitions(Activity)

allowEnterTransitionOverlap

public boolean allowEnterTransitionOverlap()

Returns boolean flag indicating whether enter transition may overlap or not.

This method returns true if overlapping has not been specified, which is a default behaviour of Window.getAllowEnterTransitionOverlap().

Returns:

True if overlapping of enter transition is enabled, false otherwise.

allowReturnTransitionOverlap

public T allowReturnTransitionOverlap(boolean allow)

Specifies a boolean flag to be set to a window of an incoming activity in order to indicate whether return transition may overlap or not.

Default value: unspecified

Returns:

This transition to allow methods chaining.

See Also:

allowReturnTransitionOverlap(), Window.setAllowReturnTransitionOverlap(boolean), configureIncomingTransitions(Activity)

allowReturnTransitionOverlap

public boolean allowReturnTransitionOverlap()

Returns boolean flag indicating whether return transition may overlap or not.

This method returns true if overlapping has not been specified, which is a default behaviour of Window.getAllowReturnTransitionOverlap().

Returns:

True if overlapping of return transition is enabled, false otherwise.

sharedElementEnterTransition

public T sharedElementEnterTransition(@Nullable
                                      Transition transition)

Specifies enter transition for shared element to be attached to a window of an incoming activity.

Returns:

This transition to allow methods chaining.

See Also:

sharedElementEnterTransition(), Window.setSharedElementEnterTransition(Transition), inflateTransition(Context, int), configureIncomingTransitions(Activity)

sharedElementEnterTransition

@Nullable
public Transition sharedElementEnterTransition()

Returns shared element enter transition for the incoming activity.

Returns:

Transition for shared element specified via sharedElementEnterTransition(Transition) or null by default.

sharedElementReenterTransition

public T sharedElementReenterTransition(@Nullable
                                        Transition transition)

Specifies reenter transition for shared element to be attached to a window of an outgoing activity whenever start(Activity) is invoked.

Returns:

This transition to allow methods chaining.

See Also:

sharedElementReenterTransition(), Window.setSharedElementReenterTransition(Transition), inflateTransition(Context, int), configureOutgoingTransitions(Activity)

sharedElementReenterTransition

@Nullable
public Transition sharedElementReenterTransition()

Returns shared element reenter transition for the outgoing activity.

Returns:

Transition for shared element specified via sharedElementReenterTransition(Transition) or null by default.

sharedElementReturnTransition

public T sharedElementReturnTransition(@Nullable
                                       Transition transition)

Specifies return transition for shared element to be attached to a window of an incoming activity.

Returns:

This transition to allow methods chaining.

See Also:

sharedElementReturnTransition(), Window.setSharedElementReturnTransition(Transition), inflateTransition(Context, int), configureIncomingTransitions(Activity)

sharedElementReturnTransition

@Nullable
public Transition sharedElementReturnTransition()

Returns shared element return transition for the incoming activity.

Returns:

Transition for shared element specified via sharedElementReturnTransition(Transition) or null by default.

sharedElementExitTransition

public T sharedElementExitTransition(@Nullable
                                     Transition transition)

Specifies exit transition for shared element to be attached to a window of an outgoing activity whenever start(Activity) is invoked.

Returns:

This transition to allow methods chaining.

See Also:

sharedElementExitTransition(), Window.setSharedElementExitTransition(Transition), inflateTransition(Context, int)

sharedElementExitTransition

@Nullable
public Transition sharedElementExitTransition()

Returns shared element exit transition for the outgoing activity.

Returns:

Transition for shared element specified via sharedElementExitTransition(Transition) or null by default.

sharedElementsUseOverlay

public T sharedElementsUseOverlay(boolean useOverlay)

Specifies a boolean flag to be set to a window of an incoming or outgoing activity in order to indicate whether shared elements should use overlay or not.

Default value: unspecified

Returns:

This transition to allow methods chaining.

See Also:

sharedElementsUseOverlay(), Window.setSharedElementsUseOverlay(boolean), configureIncomingTransitions(Activity), configureOutgoingTransitions(Activity)

sharedElementsUseOverlay

public boolean sharedElementsUseOverlay()

Returns boolean flag indicating whether shared elements should use overlay or not.

This method returns true if usage of overlay has not been specified, which is a default behaviour of Window.getSharedElementsUseOverlay().

Returns:

True if shared elements will use overlay, false otherwise.

See Also:

sharedElementsUseOverlay(boolean)

inflateTransition

@Nullable
public Transition inflateTransition(@NonNull
                                              Context context,
                                              int resource)

Inflates a new instance of Transition from the specified resource.

Note, that for pre LOLLIPOP Android versions this method does nothing and returns null.

Parameters:

context - Context used to inflate the desired transition.

resource - Resource id of the desired transition to inflate.

Returns:

Inflated transition.

See Also:

inflateTransitionManager(Context, int, ViewGroup)

inflateTransitionManager

@Nullable
public TransitionManager inflateTransitionManager(@NonNull
                                                            Context context,
                                                            int resource,
                                                            @NonNull
                                                            ViewGroup sceneRoot)

Inflates a new instance of TransitionManager from the specified resource.

Note, that for pre LOLLIPOP Android versions this method does nothing and returns null.

Parameters:

context - Context used to inflate the desired transition.

resource - Resource id of the desired transition manager to inflater.

sceneRoot - Root view for the scene with which will the manager operate.

Returns:

Inflated transition manager.

See Also:

inflateTransition(Context, int)

sharedElements

@SafeVarargs
public final T sharedElements(@NonNull
                                           Pair<View,String>... elements)

Bulk method for adding shared element pairs into this navigational transition.

Parameters:

elements - The desired shared elements pairs.

Returns:

This transition to allow methods chaining.

See Also:

sharedElement(View, String)

sharedElement

public T sharedElement(@NonNull
                       View element,
                       @NonNull
                       String elementName)

Adds shared element that should be transferred to the transitioning (called) activity via ActivityOptions as Bundle.

All shared elements and their names added into this navigational transition will be bundled from ActivityOptions created via makeSceneTransitionAnimation(Activity) and transferred to the called activity whenever start(Activity) is called.

Note, that each shared element must have a unique name.

Parameters:

element - The view to be shared via transition.

elementName - The name of the shared element.

Returns:

This transition to allow methods chaining.

See Also:

sharedElements(Pair[]), makeSceneTransitionAnimation(Activity)

sharedElements

@Nullable
public List<Pair<View,String>> sharedElements()

Returns a list of all shared elements specified for this navigational transition.

Returns:

List of shared elements or null if there are no shared elements specified.

See Also:

sharedElements(Pair[]), sharedElement(View, String), singleSharedElement()

singleSharedElement

@Nullable
public Pair<View,String> singleSharedElement()

Returns the single shared element at the 0 position among the current shared elements.

This method may be used to obtain a single shared element when there is specified only one for this navigational transition.

Returns:

Single shared element or null if there are no shared elements specified.

See Also:

sharedElements(), sharedElement(View, String)

start

public void start(@NonNull
                  Activity caller)

Starts this navigational transition using the given caller activity with transitions and shared elements that are configured for the activity via configureOutgoingTransitions(Activity).

Parameters:

caller - The activity that will be used to create and start an Intent created via createIntent(Activity).

onStart

protected void onStart(@NonNull
                       Activity caller)

Invoked whenever start(Activity) is called.

Default implementation starts an Intent created via createIntent(Activity) using the given caller activity via Activity.startActivity(Intent) for the pre LOLLIPOP Android versions and for the post LOLLIPOP via Activity.startActivity(Intent, Bundle) where will be passed Bundle created from ActivityOptions that has been requested via makeSceneTransitionAnimation(Activity).

If there was specified some requestCode() the intent will be started via Activity.startActivityForResult(Intent, int) for the pre LOLLIPOP Android versions and for the post LOLLIPOP via Activity.startActivityForResult(Intent, int, Bundle).

Note, that the specified caller activity has already attached transitions to its window, that has been specified for this navigational transition via one of set...Transition(...) methods.

Parameters:

caller - The caller activity that requested start of this navigational transition.

See Also:

onFinish(Activity)

finishCallerDelayed

protected void finishCallerDelayed(@NonNull
                                   Activity caller,
                                   long delay)

Like finishCaller(Activity) but this will postpone the finishing by the requested delay.

Parameters:

caller - The caller activity to finish.

delay - The desired delay after which to finish the caller activity.

finishCaller

protected void finishCaller(@NonNull
                            Activity caller)

Finishes the specified caller activity either via Activity.finishAfterTransition() or via Activity.finish() depending on the current API capabilities.

Parameters:

caller - The caller activity to finish.

onFinishCaller

protected void onFinishCaller(@NonNull
                              Activity caller)

Invoked whenever finishCaller(Activity) or finishCallerDelayed(Activity, long) is called.

Default implementation finishes the caller activity either via Activity.finishAfterTransition() or via Activity.finish() depending on the current API capabilities.

Parameters:

caller - The caller activity to finish.

configureTransitions

public void configureTransitions(@NonNull
                                 Activity activity)

This method groups calls to configureIncomingTransitions(Activity) and configureOutgoingTransitions(Activity) into one call.

Parameters:

activity - The activity of which window transitions to configure.

configureIncomingTransitions

public void configureIncomingTransitions(@NonNull
                                         Activity activity)

Performs configuration of the given activity's window by attaching to it enter and return transitions (those for shared elements including) specified for this navigational transition. Also the configuration related to transitions overlapping will be performed here.

This method should be called from Activity.onCreate(Bundle) by the activity to which is the calling activity transitioning. See also configureOutgoingTransitions(Activity).

Note, that for pre LOLLIPOP Android versions this method does nothing.

Parameters:

activity - The activity of which window transitions to configure.

See Also:

Window.setEnterTransition(Transition), Window.setReturnTransition(Transition), Window.setSharedElementEnterTransition(Transition), Window.setSharedElementReturnTransition(Transition), Window.setAllowEnterTransitionOverlap(boolean), Window.setAllowReturnTransitionOverlap(boolean)

configureOutgoingTransitions

public void configureOutgoingTransitions(@NonNull
                                         Activity activity)

Performs configuration of the given activity's window by attaching to it reenter and exit transitions (those for shared elements including) specified for this navigational transition.

This method is by default invoked whenever start(Activity) is called for this navigational transition. Its counterpart, configureIncomingTransitions(Activity), should be called by the activity to which is the calling activity transitioning.

Note, that for pre LOLLIPOP Android versions this method does nothing.

Parameters:

activity - The activity of which window transitions to configure.

See Also:

Window.setReenterTransition(Transition), Window.setExitTransition(Transition), Window.setSharedElementReenterTransition(Transition), Window.setSharedElementExitTransition(Transition)

makeSceneTransitionAnimation

@Nullable
public ActivityOptions makeSceneTransitionAnimation(@NonNull
                                                              Activity caller)

Creates a new instance of ActivityOptions for the specified caller activity.

Note, that for pre LOLLIPOP Android versions this method does nothing and returns null.

Parameters:

caller - The activity for which to create the ActivityOptions.

Returns:

Activity options with or without attached shared elements that has been added into this navigational transition (if any).

createIntent

@NonNull
public Intent createIntent(@NonNull
                                    Activity caller)

Creates an intent that can be used to start activity for which is this transition created.

Parameters:

caller - Activity to be used as context when creating the requested intent.

Returns:

New Intent or null it this navigational transition has no class of transition activity specified.

finish

public void finish(@NonNull
                   Activity caller)

Finishes the given caller activity in order to run its exit transitions.

Parameters:

caller - The activity that should be finished and of which exit transitions should be started.

See Also:

start(Activity)

onFinish

protected void onFinish(@NonNull
                        Activity caller)

Invoked whenever finish(Activity) is called.

Default implementation finishes the given caller activity for the pre LOLLIPOP Android versions via Activity.finish() and for the post LOLLIPOP via Activity.finishAfterTransition().

Derived classes can override this method in order to run custom window transitions for the pre LOLLIPOP Android versions via Activity.overridePendingTransition(int, int).

Parameters:

caller - The activity that requested its finish via this navigational transition.

See Also:

onStart(Activity)