NavigationUI
object NavigationUI
Class which hooks up elements typically in the 'chrome' of your application such as global navigation patterns like a navigation drawer or bottom nav bar with your NavController
.
Summary
Public methods |
|
---|---|
static final boolean |
navigateUp(@NonNull NavController navController, Openable openableLayout) Handles the Up button by delegating its behavior to the given NavController. |
static final boolean |
navigateUp( Handles the Up button by delegating its behavior to the given NavController. |
static final boolean |
onNavDestinationSelected( Attempt to navigate to the |
static final @NavigationUiSaveStateControl boolean |
onNavDestinationSelected( Attempt to navigate to the |
static final void |
setupActionBarWithNavController( Sets up the ActionBar returned by |
static final void |
setupActionBarWithNavController( Sets up the ActionBar returned by |
static final void |
setupWithNavController( Sets up a |
static final void |
setupWithNavController( Sets up a |
static final void |
setupWithNavController( Sets up a |
static final void |
setupWithNavController( Sets up a |
static final void |
setupWithNavController( Sets up a |
static final @NavigationUiSaveStateControl void |
setupWithNavController( Sets up a |
static final void |
setupWithNavController( Sets up a |
static final @NavigationUiSaveStateControl void |
setupWithNavController( Sets up a |
Public methods
navigateUp
public static final boolean navigateUp(@NonNull NavController navController, Openable openableLayout)
Handles the Up button by delegating its behavior to the given NavController. This should generally be called from AppCompatActivity.onSupportNavigateUp
.
If you do not have a Openable
layout, you should call NavController.navigateUp
directly.
Parameters | |
---|---|
@NonNull NavController navController |
The NavController that hosts your content. |
Openable openableLayout |
The Openable layout that should be opened if you are on the topmost level of the app. |
Returns | |
---|---|
boolean |
True if the |
navigateUp
public static final boolean navigateUp(
@NonNull NavController navController,
@NonNull AppBarConfiguration configuration
)
Handles the Up button by delegating its behavior to the given NavController. This is an alternative to using NavController.navigateUp
directly when the given AppBarConfiguration
needs to be considered when determining what should happen when the Up button is pressed.
In cases where no Up action is available, the AppBarConfiguration.fallbackOnNavigateUpListener
will be called to provide additional control.
Parameters | |
---|---|
@NonNull NavController navController |
The NavController that hosts your content. |
@NonNull AppBarConfiguration configuration |
Additional configuration options for determining what should happen when the Up button is pressed. |
Returns | |
---|---|
boolean |
True if the |
onNavDestinationSelected
public static final boolean onNavDestinationSelected(
@NonNull MenuItem item,
@NonNull NavController navController
)
Attempt to navigate to the NavDestination
associated with the given MenuItem. This MenuItem should have been added via one of the helper methods in this class.
Importantly, it assumes the menu item id
matches a valid action id
or destination id
to be navigated to.
By default, the back stack will be popped back to the navigation graph's start destination. Menu items that have android:menuCategory="secondary"
will not pop the back stack.
Parameters | |
---|---|
@NonNull MenuItem item |
The selected MenuItem. |
@NonNull NavController navController |
The NavController that hosts the destination. |
Returns | |
---|---|
boolean |
True if the |
onNavDestinationSelected
@NavigationUiSaveStateControl
public static final boolean onNavDestinationSelected(
@NonNull MenuItem item,
@NonNull NavController navController,
boolean saveState
)
Attempt to navigate to the NavDestination
associated with the given MenuItem. This MenuItem should have been added via one of the helper methods in this class.
Importantly, it assumes the menu item id
matches a valid action id
or destination id
to be navigated to.
By default, the back stack will be popped back to the navigation graph's start destination. Menu items that have android:menuCategory="secondary"
will not pop the back stack.
Parameters | |
---|---|
@NonNull MenuItem item |
The selected MenuItem. |
@NonNull NavController navController |
The NavController that hosts the destination. |
boolean saveState |
Whether the NavController should save the back stack state. This must always be |
Returns | |
---|---|
boolean |
True if the |
setupActionBarWithNavController
public static final void setupActionBarWithNavController(
@NonNull AppCompatActivity activity,
@NonNull NavController navController,
Openable openableLayout
)
Sets up the ActionBar returned by AppCompatActivity.getSupportActionBar
for use with a NavController
.
By calling this method, the title in the action bar will automatically be updated when the destination changes (assuming there is a valid label
).
The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the ActionBar will show the drawer icon if the given Openable layout is non null. On all other destinations, the ActionBar will show the Up button. Call navigateUp
to handle the Up button.
Destinations that implement androidx.navigation.FloatingWindow
will be ignored.
Parameters | |
---|---|
@NonNull AppCompatActivity activity |
The activity hosting the action bar that should be kept in sync with changes to the NavController. |
@NonNull NavController navController |
The NavController whose navigation actions will be reflected in the title of the action bar. |
Openable openableLayout |
The Openable layout that should be toggled from the home button |
See also | |
---|---|
setupActionBarWithNavController |
setupActionBarWithNavController
public static final void setupActionBarWithNavController(
@NonNull AppCompatActivity activity,
@NonNull NavController navController,
@NonNull AppBarConfiguration configuration
)
Sets up the ActionBar returned by AppCompatActivity.getSupportActionBar
for use with a NavController
.
By calling this method, the title in the action bar will automatically be updated when the destination changes (assuming there is a valid label
).
The AppBarConfiguration
you provide controls how the Navigation button is displayed. Call navigateUp
to handle the Up button.
Destinations that implement androidx.navigation.FloatingWindow
will be ignored.
Parameters | |
---|---|
@NonNull AppCompatActivity activity |
The activity hosting the action bar that should be kept in sync with changes to the NavController. |
@NonNull NavController navController |
The NavController whose navigation actions will be reflected in the title of the action bar. |
@NonNull AppBarConfiguration configuration |
Additional configuration options for customizing the behavior of the ActionBar |
setupWithNavController
public static final void setupWithNavController(
@NonNull Toolbar toolbar,
@NonNull NavController navController,
Openable openableLayout
)
Sets up a Toolbar
for use with a NavController
.
By calling this method, the title in the Toolbar will automatically be updated when the destination changes (assuming there is a valid label
).
The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the Toolbar will show the drawer icon if the given Openable layout is non null. On all other destinations, the Toolbar will show the Up button. This method will call navigateUp
when the Navigation button is clicked.
Destinations that implement androidx.navigation.FloatingWindow
will be ignored.
Parameters | |
---|---|
@NonNull Toolbar toolbar |
The Toolbar that should be kept in sync with changes to the NavController. |
@NonNull NavController navController |
The NavController whose navigation actions will be reflected in the title of the Toolbar. |
Openable openableLayout |
The Openable layout that should be toggled from the Navigation button |
See also | |
---|---|
setupWithNavController |
setupWithNavController
public static final void setupWithNavController(
@NonNull Toolbar toolbar,
@NonNull NavController navController,
@NonNull AppBarConfiguration configuration
)
Sets up a Toolbar
for use with a NavController
.
By calling this method, the title in the Toolbar will automatically be updated when the destination changes (assuming there is a valid label
).
The AppBarConfiguration
you provide controls how the Navigation button is displayed and what action is triggered when the Navigation button is tapped. This method will call navigateUp
when the Navigation button is clicked.
Destinations that implement androidx.navigation.FloatingWindow
will be ignored.
Parameters | |
---|---|
@NonNull Toolbar toolbar |
The Toolbar that should be kept in sync with changes to the NavController. |
@NonNull NavController navController |
The NavController whose navigation actions will be reflected in the title of the Toolbar. |
@NonNull AppBarConfiguration configuration |
Additional configuration options for customizing the behavior of the Toolbar |
setupWithNavController
public static final void setupWithNavController(
@NonNull CollapsingToolbarLayout collapsingToolbarLayout,
@NonNull Toolbar toolbar,
@NonNull NavController navController,
Openable openableLayout
)
Sets up a CollapsingToolbarLayout
and Toolbar
for use with a NavController
.
By calling this method, the title in the CollapsingToolbarLayout will automatically be updated when the destination changes (assuming there is a valid label
).
The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the Toolbar will show the drawer icon if the given Openable layout is non null. On all other destinations, the Toolbar will show the Up button. This method will call navigateUp
when the Navigation button is clicked.
Destinations that implement androidx.navigation.FloatingWindow
will be ignored.
Parameters | |
---|---|
@NonNull CollapsingToolbarLayout collapsingToolbarLayout |
The CollapsingToolbarLayout that should be kept in sync with changes to the NavController. |
@NonNull Toolbar toolbar |
The Toolbar that should be kept in sync with changes to the NavController. |
@NonNull NavController navController |
The NavController whose navigation actions will be reflected in the title of the Toolbar. |
Openable openableLayout |
The Openable layout that should be toggled from the Navigation button |
setupWithNavController
public static final void setupWithNavController(
@NonNull CollapsingToolbarLayout collapsingToolbarLayout,
@NonNull Toolbar toolbar,
@NonNull NavController navController,
@NonNull AppBarConfiguration configuration
)
Sets up a CollapsingToolbarLayout
and Toolbar
for use with a NavController
.
By calling this method, the title in the CollapsingToolbarLayout will automatically be updated when the destination changes (assuming there is a valid label
).
The AppBarConfiguration
you provide controls how the Navigation button is displayed and what action is triggered when the Navigation button is tapped. This method will call navigateUp
when the Navigation button is clicked.
Destinations that implement androidx.navigation.FloatingWindow
will be ignored.
Parameters | |
---|---|
@NonNull CollapsingToolbarLayout collapsingToolbarLayout |
The CollapsingToolbarLayout that should be kept in sync with changes to the NavController. |
@NonNull Toolbar toolbar |
The Toolbar that should be kept in sync with changes to the NavController. |
@NonNull NavController navController |
The NavController whose navigation actions will be reflected in the title of the Toolbar. |
@NonNull AppBarConfiguration configuration |
Additional configuration options for customizing the behavior of the Toolbar |
setupWithNavController
public static final void setupWithNavController(
@NonNull NavigationView navigationView,
@NonNull NavController navController
)
Sets up a NavigationView
for use with a NavController
. This will call onNavDestinationSelected
when a menu item is selected. The selected item in the NavigationView will automatically be updated when the destination changes.
If the NavigationView
is directly contained with an Openable
layout, it will be closed when a menu item is selected.
Similarly, if the NavigationView
has a BottomSheetBehavior
associated with it (as is the case when using a com.google.android.material.bottomsheet.BottomSheetDialog
), the bottom sheet will be hidden when a menu item is selected.
Parameters | |
---|---|
@NonNull NavigationView navigationView |
The NavigationView that should be kept in sync with changes to the NavController. |
@NonNull NavController navController |
The NavController that supplies the primary and secondary menu. Navigation actions on this NavController will be reflected in the selected item in the NavigationView. |
setupWithNavController
@NavigationUiSaveStateControl
public static final void setupWithNavController(
@NonNull NavigationView navigationView,
@NonNull NavController navController,
boolean saveState
)
Sets up a NavigationView
for use with a NavController
. This will call onNavDestinationSelected
when a menu item is selected. The selected item in the NavigationView will automatically be updated when the destination changes.
If the NavigationView
is directly contained with an Openable
layout, it will be closed when a menu item is selected.
Similarly, if the NavigationView
has a BottomSheetBehavior
associated with it (as is the case when using a com.google.android.material.bottomsheet.BottomSheetDialog
), the bottom sheet will be hidden when a menu item is selected.
Parameters | |
---|---|
@NonNull NavigationView navigationView |
The NavigationView that should be kept in sync with changes to the NavController. |
@NonNull NavController navController |
The NavController that supplies the primary and secondary menu. |
boolean saveState |
Whether the NavController should save the back stack state. This must always be Navigation actions on this NavController will be reflected in the selected item in the NavigationView. |
setupWithNavController
public static final void setupWithNavController(
@NonNull NavigationBarView navigationBarView,
@NonNull NavController navController
)
Sets up a NavigationBarView
for use with a NavController
. This will call onNavDestinationSelected
when a menu item is selected. The selected item in the NavigationBarView will automatically be updated when the destination changes.
Parameters | |
---|---|
@NonNull NavigationBarView navigationBarView |
The NavigationBarView ( |
@NonNull NavController navController |
The NavController that supplies the primary menu. Navigation actions on this NavController will be reflected in the selected item in the NavigationBarView. |
setupWithNavController
@NavigationUiSaveStateControl
public static final void setupWithNavController(
@NonNull NavigationBarView navigationBarView,
@NonNull NavController navController,
boolean saveState
)
Sets up a NavigationBarView
for use with a NavController
. This will call onNavDestinationSelected
when a menu item is selected. The selected item in the NavigationBarView will automatically be updated when the destination changes.
Parameters | |
---|---|
@NonNull NavigationBarView navigationBarView |
The NavigationBarView ( |
@NonNull NavController navController |
The NavController that supplies the primary menu. |
boolean saveState |
Whether the NavController should save the back stack state. This must always be Navigation actions on this NavController will be reflected in the selected item in the NavigationBarView. |