NavUtils

Added in 1.1.0

public final class NavUtils

NavUtils provides helper functionality for applications implementing recommended Android UI navigation patterns. For information about recommended navigation patterns see Tasks and Back Stack from the developer guide and Navigation from the design guide.

Summary

Constants
static final String
PARENT_ACTIVITY = "android.support.PARENT_ACTIVITY"

Public methods
static @Nullable Intent

Obtain an Intent that will launch an explicit target activity specified by sourceActivity's PARENT_ACTIVITY element in the application's manifest.
static @Nullable Intent
getParentActivityIntent(
    @NonNull Context context,
    @NonNull ComponentName componentName
)

Obtain an Intent that will launch an explicit target activity specified by sourceActivityClass's PARENT_ACTIVITY element in the application's manifest.
static @Nullable Intent
getParentActivityIntent(
    @NonNull Context context,
    @NonNull Class<Object> sourceActivityClass
)

Obtain an Intent that will launch an explicit target activity specified by sourceActivityClass's PARENT_ACTIVITY element in the application's manifest.
static @Nullable String

Return the fully qualified class name of sourceActivity's parent activity as specified by a PARENT_ACTIVITY element within the activity element in the application's manifest.
static @Nullable String
getParentActivityName(
    @NonNull Context context,
    @NonNull ComponentName componentName
)

Return the fully qualified class name of a source activity's parent activity as specified by a PARENT_ACTIVITY element within the activity element in the application's manifest.
static void

Convenience method that is equivalent to calling navigateUpTo(sourceActivity, getParentActivityIntent (sourceActivity)). sourceActivity will be finished by this call.
static void
@ReplaceWith(expression = "sourceActivity.navigateUpTo(upIntent)")
navigateUpTo(@NonNull Activity sourceActivity, @NonNull Intent upIntent)

This method is deprecated.

Call navigateUpTo directly.
static boolean
@ReplaceWith(expression = "sourceActivity.shouldUpRecreateTask(targetIntent)")
shouldUpRecreateTask(
    @NonNull Activity sourceActivity,
    @NonNull Intent targetIntent
)

This method is deprecated.

Call shouldUpRecreateTask directly.

Constants

PARENT_ACTIVITY

Added in 1.1.0
public static final String PARENT_ACTIVITY = "android.support.PARENT_ACTIVITY"

Public methods

getParentActivityIntent

Added in 1.1.0
public static @Nullable Intent getParentActivityIntent(@NonNull Activity sourceActivity)

Obtain an Intent that will launch an explicit target activity specified by sourceActivity's PARENT_ACTIVITY element in the application's manifest. The android:parentActivityName attribute will be preferred if it is present.

Parameters
@NonNull Activity sourceActivity

Activity to fetch a parent intent for
Returns
@Nullable Intent

a new Intent targeting the defined parent activity of sourceActivity

getParentActivityIntent

Added in 1.1.0
public static @Nullable Intent getParentActivityIntent(
    @NonNull Context context,
    @NonNull ComponentName componentName
)

Obtain an Intent that will launch an explicit target activity specified by sourceActivityClass's PARENT_ACTIVITY element in the application's manifest.

Parameters
@NonNull Context context

Context for looking up the activity component for the source activity
@NonNull ComponentName componentName

ComponentName for the source Activity
Returns
@Nullable Intent

a new Intent targeting the defined parent activity of sourceActivity
Throws
android.content.pm.PackageManager.NameNotFoundException

if the ComponentName for sourceActivityClass is invalid

getParentActivityIntent

Added in 1.1.0
public static @Nullable Intent getParentActivityIntent(
    @NonNull Context context,
    @NonNull Class<Object> sourceActivityClass
)

Obtain an Intent that will launch an explicit target activity specified by sourceActivityClass's PARENT_ACTIVITY element in the application's manifest.

Parameters
@NonNull Context context

Context for looking up the activity component for sourceActivityClass
@NonNull Class<Object> sourceActivityClass

java.lang.Class object for an Activity class
Returns
@Nullable Intent

a new Intent targeting the defined parent activity of sourceActivity
Throws
android.content.pm.PackageManager.NameNotFoundException

if the ComponentName for sourceActivityClass is invalid

getParentActivityName

Added in 1.1.0
public static @Nullable String getParentActivityName(@NonNull Activity sourceActivity)

Return the fully qualified class name of sourceActivity's parent activity as specified by a PARENT_ACTIVITY element within the activity element in the application's manifest.

Parameters
@NonNull Activity sourceActivity

Activity to fetch a parent class name for
Returns
@Nullable String

The fully qualified class name of sourceActivity's parent activity or null if it was not specified

getParentActivityName

Added in 1.1.0
public static @Nullable String getParentActivityName(
    @NonNull Context context,
    @NonNull ComponentName componentName
)

Return the fully qualified class name of a source activity's parent activity as specified by a PARENT_ACTIVITY element within the activity element in the application's manifest. The source activity is provided by componentName.

Parameters
@NonNull Context context

Context for looking up the activity component for the source activity
@NonNull ComponentName componentName

ComponentName for the source Activity
Returns
@Nullable String

The fully qualified class name of sourceActivity's parent activity or null if it was not specified
Throws
android.content.pm.PackageManager.NameNotFoundException
Added in 1.1.0
public static void navigateUpFromSameTask(@NonNull Activity sourceActivity)

Convenience method that is equivalent to calling navigateUpTo(sourceActivity, getParentActivityIntent (sourceActivity)). sourceActivity will be finished by this call.

Note: This method should only be used when sourceActivity and the corresponding parent are within the same task. If up navigation should cross tasks in some cases, see shouldUpRecreateTask.

Parameters
@NonNull Activity sourceActivity

The current activity from which the user is attempting to navigate up
Added in 1.1.0
Deprecated in 1.15.0
@ReplaceWith(expression = "sourceActivity.navigateUpTo(upIntent)")
public static void navigateUpTo(@NonNull Activity sourceActivity, @NonNull Intent upIntent)

Navigate from sourceActivity to the activity specified by upIntent, finishing sourceActivity in the process. upIntent will have the flag FLAG_ACTIVITY_CLEAR_TOP set by this method, along with any others required for proper up navigation as outlined in the Android Design Guide.

This method should be used when performing up navigation from within the same task as the destination. If up navigation should cross tasks in some cases, see shouldUpRecreateTask.

Parameters
@NonNull Activity sourceActivity

The current activity from which the user is attempting to navigate up
@NonNull Intent upIntent

An intent representing the target destination for up navigation

shouldUpRecreateTask

Added in 1.1.0
Deprecated in 1.15.0
@ReplaceWith(expression = "sourceActivity.shouldUpRecreateTask(targetIntent)")
public static boolean shouldUpRecreateTask(
    @NonNull Activity sourceActivity,
    @NonNull Intent targetIntent
)

Returns true if sourceActivity should recreate the task when navigating 'up' by using targetIntent.

If this method returns false the app can trivially call navigateUpTo using the same parameters to correctly perform up navigation. If this method returns true, the app should synthesize a new task stack by using TaskStackBuilder or another similar mechanism to perform up navigation.

Parameters
@NonNull Activity sourceActivity

The current activity from which the user is attempting to navigate up
@NonNull Intent targetIntent

An intent representing the target destination for up navigation
Returns
boolean

true if navigating up should recreate a new task stack, false if the same task should be used for the destination