Part 1 - Replacing the Action Bar

PDF for offline use:
Related Samples:
Related APIs:
Related SDKs:

Let us know how you feel about this.


0/250
Thanks for the feedback!

last updated: 2016-07

One of the most common uses for the Toolbar is to replace the default action bar with a custom Toolbar (when a new Android project is created, it uses the default action bar). Because the Toolbar provides the ability to add branded logos, titles, menu items, navigation buttons, and even custom views to the app bar section of an Activity's UI, it offers a significant upgrade over the default action bar.

To replace an app's default action bar with a Toolbar:

  1. Create a new custom theme and modify the app's properties so that it uses this new theme.

  2. Disable the windowActionBar attribute in the custom theme and enable the windowNoTitle attribute.

  3. Define a layout for the Toolbar.

  4. Include the Toolbar layout in the Activity's Main.axml layout file.

  5. Add code to the Activity's OnCreate method to locate the Toolbar and call SetActionBar to install the ToolBar as the action bar.

The following sections explain this process in detail. A simple app is created and its action bar is replaced with a customized Toolbar.

Start an App Project

Create a new Android project called ToolbarFun (see Hello, Android for more information about creating a new Android project). After this project is created, set the target and minimum Android API levels to Android 5.0 (API Level 21 - Lollipop). For more information about setting Android version levels, see Understanding Android API Levels. When the app is built and run, it displays the default action bar as seen in this screenshot:

Create a Custom Theme

Open the Resources/values directory and a create a new file called styles.xml. Replace its contents with the following XML:

<?xml version="1.0" encoding="utf-8" ?>
<resources>
  <style name="MyTheme" parent="@android:style/Theme.Material.Light.DarkActionBar">
    <item name="android:windowNoTitle">true</item>
    <item name="android:windowActionBar">false</item>
    <item name="android:colorPrimary">#5A8622</item>
  </style>
</resources>

This XML defines a new custom theme called MyTheme that is based on the Theme.Material.Light.DarkActionBar theme in Lollipop. The windowNoTitle attribute is set to true to hide the title bar:

<item name="android:windowNoTitle">true</item>

To display the custom toolbar, the default ActionBar must be disabled:

<item name="android:windowActionBar">false</item>

An olive-green colorPrimary setting is used for the background color of the toolbar:

<item name="android:colorPrimary">#5A8622</item>

Edit Properties/AndroidManifest.xml and add the following android:theme attribute to the <application> element so that the app uses the MyTheme custom theme:

<application android:label="ToolbarFun" android:theme="@style/MyTheme"></application>

For more information about applying a custom theme to an app, see Using Custom Themes.

Define a Toolbar Layout

In the Resources/layout directory, create a new file called toolbar.xml. Replace its contents with the following XML:

<?xml version="1.0" encoding="utf-8"?>
<Toolbar xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/toolbar"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:minHeight="?android:attr/actionBarSize"
    android:background="?android:attr/colorPrimary"
    android:theme="@android:style/ThemeOverlay.Material.Dark.ActionBar"/>

This XML defines the custom Toolbar that replaces the default action bar. The minimum height of the Toolbar is set to the size of the action bar that it replaces:

android:minHeight="?android:attr/actionBarSize"

The background color of the Toolbar is set to the olive-green color defined earlier in styles.xml:

android:background="?android:attr/colorPrimary"

Beginning with Lollipop, the android:theme attribute can be used to style an individual view. The ThemeOverlay.Material themes introduced in Lollipop make it possible to overlay the default Theme.Material themes, overwriting relevant attributes to make them either light or dark. In this example, the Toolbar uses a dark theme so that its contents are light in color:

android:theme="@android:style/ThemeOverlay.Material.Dark.ActionBar"

This setting is used so that menu items contrast with the darker background color.

Include the Toolbar Layout

Edit the layout file Resources/layout/Main.axml and replace its contents with the following XML:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <include
        android:id="@+id/toolbar"
        layout="@layout/toolbar" />
    <Button
        android:id="@+id/MyButton"
        android:layout_below="@+id/toolbar"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/Hello" />
</RelativeLayout>

This layout includes the Toolbar defined in toolbar.xml and uses a RelativeLayout to specify that the Toolbar is to be placed at the very top of the UI (above the button).

Find and Activate the Toolbar

Edit MainActivity.cs and add the following lines of code to the end of the OnCreate method:

var toolbar = FindViewById<Toolbar>(Resource.Id.toolbar);
SetActionBar(toolbar);
ActionBar.Title = "My Toolbar";

This code finds the Toolbar and calls SetActionBar so that the Toolbar will take on default action bar characteristics. The title of the Toolbar is changed to My Toolbar. As seen in this code example, the ToolBar can be directly referenced as an action bar. Compile and run this app – the customized Toolbar is displayed in place of the default action bar:

Notice that the Toolbar is styled independently of the Theme.Material.Light.DarkActionBar theme that is applied to the remainder of the app.

Add Menu Items

In this section, menus are added to the Toolbar. The upper right area of the ToolBar is reserved for menu items – each menu item (also called an action item) can perform an action within the current activity or it can perform an action on behalf of the entire app.

To add menus to the Toolbar:

  1. Add menu icons (if required) to the drawable- folders of the app project. Google provides a set of free menu icons on the Material icons page.

  2. Define the contents of the menu items by adding a new menu resource file under Resources/menu.

  3. Implement the OnCreateOptionsMenu method of the Activity – this method inflates the menu items.

  4. Implement the OnOptionsItemSelected method of the Activity – this method performs an action when a menu item is tapped.

The following sections demonstrate this process in detail by adding Edit and Save menu items to the customized Toolbar.

Install Menu Icons

Continuing with the ToolbarFun example app, add menu icons to the app project. Download toolbar-icons.zip and unzip it. Copy the extracted drawable- folders to the project under ToolbarFun/Resources and include these folders in the project:

Define a Menu Resource

Create a new menu subdirectory under Resources. In the menu subdirectory, create a new menu resource file called top_menus.xml and replace its contents with the following XML:

<?xml version="1.0" encoding="utf-8" ?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
  <item
       android:id="@+id/menu_edit"
       android:icon="@drawable/ic_action_content_create"
       android:showAsAction="ifRoom"
       android:title="Edit" />
  <item
       android:id="@+id/menu_save"
       android:icon="@drawable/ic_action_content_save"
       android:showAsAction="ifRoom"
       android:title="Save" />
  <item
       android:id="@+id/menu_preferences"
       android:showAsAction="never"
       android:title="Preferences" />
</menu>

This XML creates three menu items:

  • An Edit menu item that uses the ic_action_content_create.png icon (a pencil).

  • A Save menu item that uses the ic_action_content_save.png icon (a diskette).

  • A Preferences menu item that does not have an icon.

The showAsAction attributes of the Edit and Save menu items are set to ifRoom – this setting causes these menu items to appear in the Toolbar if there is sufficient room for them to be displayed. The Preferences menu item sets showAsAction to never – this causes the Preferences menu to appear in the overflow menu (three vertical dots).

Implement OnCreateOptionsMenu

Add the following method to MainActivity.cs:

public override bool OnCreateOptionsMenu(IMenu menu)
{
    MenuInflater.Inflate(Resource.Menu.top_menus, menu);
    return base.OnCreateOptionsMenu(menu);
}

Android calls the OnCreateOptionsMenu method so that the app can specify the menu resource for an activity. In this method, the top_menus.xml resource is inflated into the passed menu. This code causes the new Edit, Save, and Preferences menu items to appear in the Toolbar.

Implement OnOptionsItemSelected

Add the following method to MainActivity.cs:

public override bool OnOptionsItemSelected(IMenuItem item)
{
    Toast.MakeText(this, "Action selected: " + item.TitleFormatted, 
        ToastLength.Short).Show();
    return base.OnOptionsItemSelected(item);
}

When a user taps a menu item, Android calls the OnOptionsItemSelected method and passes in the menu item that was selected. In this example, the implementation just displays a toast to indicate which menu item was tapped.

Build and run ToolbarFun to see the new menu items in the toolbar. The Toolbar now displays three menu icons as seen in this screenshot:

When a user taps the Edit menu item, a toast is displayed to indicate that the OnOptionsItemSelected method was called:

When a user taps the overflow menu, the Preferences menu item is displayed. Typically, less-common actions should be placed in the overflow menu – this example uses the overflow menu for Preferences because it is not used as often as Edit and Save:

For more information about Android menus, see the Android Developer Menus topic.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.