Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

NavUtils

class NavUtils
kotlin.Any
   ↳ androidx.core.app.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 String

Public methods

static Intent?
getParentActivityIntent(@NonNull sourceActivity: Activity)

Obtain an Intent that will launch an explicit target activity specified by sourceActivity's PARENT_ACTIVITY <meta-data> element in the application's manifest.

static Intent?
getParentActivityIntent(@NonNull context: Context, @NonNull sourceActivityClass: Class<*>)

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

static Intent?
getParentActivityIntent(@NonNull context: Context, @NonNull componentName: ComponentName)

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

static String?
getParentActivityName(@NonNull sourceActivity: Activity)

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

static 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 <meta-data> element within the activity element in the application's manifest.

static Unit
navigateUpFromSameTask(@NonNull sourceActivity: Activity)

Convenience method that is equivalent to calling navigateUpTo(sourceActivity, getParentActivityIntent (sourceActivity)).

static Unit
navigateUpTo(@NonNull sourceActivity: Activity, @NonNull upIntent: Intent)

Navigate from sourceActivity to the activity specified by upIntent, finishing sourceActivity in the process.

static Boolean
shouldUpRecreateTask(@NonNull sourceActivity: Activity, @NonNull targetIntent: Intent)

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

Constants

PARENT_ACTIVITY

static val PARENT_ACTIVITY: String
Value: "android.support.PARENT_ACTIVITY"

Public methods

getParentActivityIntent

@Nullable static fun getParentActivityIntent(@NonNull sourceActivity: Activity): Intent?

Obtain an Intent that will launch an explicit target activity specified by sourceActivity's PARENT_ACTIVITY <meta-data> element in the application's manifest. If the device is running Jellybean or newer, the android:parentActivityName attribute will be preferred if it is present.

Parameters
sourceActivity Activity: Activity to fetch a parent intent for
Return
Intent?: a new Intent targeting the defined parent activity of sourceActivity

getParentActivityIntent

@Nullable static fun getParentActivityIntent(@NonNull context: Context, @NonNull sourceActivityClass: Class<*>): Intent?

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

Parameters
context Context: Context for looking up the activity component for sourceActivityClass
sourceActivityClass Context: java.lang.Class object for an Activity class
Return
Intent?: a new Intent targeting the defined parent activity of sourceActivity
Exceptions
NameNotFoundException if the ComponentName for sourceActivityClass is invalid

getParentActivityIntent

@Nullable static fun getParentActivityIntent(@NonNull context: Context, @NonNull componentName: ComponentName): Intent?

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

Parameters
context Context: Context for looking up the activity component for the source activity
componentName Context: ComponentName for the source Activity
Return
Intent?: a new Intent targeting the defined parent activity of sourceActivity
Exceptions
NameNotFoundException if the ComponentName for sourceActivityClass is invalid

getParentActivityName

@Nullable static fun getParentActivityName(@NonNull sourceActivity: Activity): String?

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

Parameters
sourceActivity Activity: Activity to fetch a parent class name for
Return
String?: The fully qualified class name of sourceActivity's parent activity or null if it was not specified

getParentActivityName

@Nullable static fun getParentActivityName(@NonNull context: Context, @NonNull componentName: ComponentName): String?

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

Parameters
context Context: Context for looking up the activity component for the source activity
componentName Context: ComponentName for the source Activity
Return
String?: The fully qualified class name of sourceActivity's parent activity or null if it was not specified

navigateUpFromSameTask

static fun navigateUpFromSameTask(@NonNull sourceActivity: Activity): Unit

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(Activity, Intent).

Parameters
sourceActivity Activity: The current activity from which the user is attempting to navigate up

navigateUpTo

static fun navigateUpTo(@NonNull sourceActivity: Activity, @NonNull upIntent: Intent): Unit

Navigate from sourceActivity to the activity specified by upIntent, finishing sourceActivity in the process. upIntent will have the flag Intent#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(Activity, Intent).

Parameters
sourceActivity Activity: The current activity from which the user is attempting to navigate up
upIntent Activity: An intent representing the target destination for up navigation

shouldUpRecreateTask

static fun shouldUpRecreateTask(@NonNull sourceActivity: Activity, @NonNull targetIntent: Intent): Boolean

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(Activity, Intent) 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
sourceActivity Activity: The current activity from which the user is attempting to navigate up
targetIntent Activity: An intent representing the target destination for up navigation
Return
Boolean: true if navigating up should recreate a new task stack, false if the same task should be used for the destination