Titlebars, toolbars and app bars

Article
10/14/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Here's how to migrate from using iOS UIToolbar to Windows 8 Appbar controls.

The following video compares toolbars in iOS apps to app bars in Windows Store apps.

As you know, most iOS apps use a toolbar: a bar at the top or the bottom of the screen used to host context sensitive navigation buttons and actions.

Windows Store apps use a control called the Appbar which you can also put at the top or bottom of the page, or both. App bars are hidden by default and can be shown with simple user actions such as swipes from top or bottom of the page, or a right mouse button click, or by pressing the Windows key and Z . They can also be shown programmatically when the user interacts with the app.

We're going to compare the Windows 8 app bar with the iOS toolbar, and show an example of how a toolbar is used in both iOS and Windows Store apps. Then we'll look the steps needed to implement toolbars on both platforms, and provide step-by-step guidance on how to implement an app bar in your Windows Store app.

In iOS a toolbar is typically contained in a navigation controller which manages the display hierarchy of views. Toolbars have many uses, including:

Providing a set of actions in the current context.
Providing frequently used commands that are appropriate in the current context.
Enabling different app modes by using segmented control or tabs.
Providing access to different aspects of the app data.

Toolbars in Windows Store apps

The Windows 8 controls library provides the app bar control. Here is an example of an app bar in a Windows Store app.

In the this example, we show an app bar split between top and bottom of the page. The top part of the app bar shows the navigation button whereas the bottom app bar shows various actions available to the user.

App bar actions can be context sensitive as shown below. Here, the app bar is shown automatically when an item is selected, and disappears when a dialog opens in response.

Comparing toolbars in iOS and Windows Store apps

If you have been using UIToolbar for implementing a toolbar in iOS, you will find that similar functionality is provided by the app bar control in Windows Store apps. Here is how the process compares between platforms:

Steps	iOS	Windows 8
Create the toolbar and add necessary controls	Use the UIToolbar control. Add UIToolbarButtonItem controls to the toolbar for commands.	Use the app bar control and add various controls, such as button, checkbox, radiobutton, to the app bar control. For more info, see Commanding design for Windows Store apps, Quickstart: adding app bars andQuickstart: Adding controls and handling events
Optional: Define the look and feel of the toolbar	Use setBackgroundImage, shadowImageForToolbarPosition methods, set the properties barStyle, tintColor and translucent, or use UIAppearance.	Set the styles of the layout panel used in the app bar. Various styling properties such as BackGround may be used to set the look and feel. See Quickstart: Defining layouts.
Optional: Define the look and feel of the controls used in the toolbar.	Use custom icon and title using methods such as initWithTitle:image:tag: or initWithTitle:style:target:action:	Various properties such as Foreground, Border and Font may be used for custom look and feel. See Quickstart: styling controls and Quickstart: Styling app bar buttons
Handle toolbar events	Set the action and target properties of the UIBarButtonItem button. Implement the method corresponding to the selector held by the action property in the appropriate controller.	Implement an event handler with void method(object sender, RoutedEventArgs e) signature in the code-behind file and set method as the Click property of each control. For handling control events, see Quickstart: Adding controls and handling events.

Sample app

Here is an example which demonstrates building a Windows Store app which uses the app bar.

Note Windows 8.1 updates the way you define app bars. Please see the blog posting What's New for the AppBar in Windows 8.1 for more details.

1. Create the app. In this sample, we are going to create our app using the C# Blank App template.

Open Microsoft Visual Studio, and create a new Visual Studio C# > Windows App > Blank App (XAML) project.
Open MainPage.xaml from the Solution Explorer. Click on horizontal split button to open the XAML view if it not already visible.

In the MainPage.xaml, between the opening <Grid ..> and closing </Grid> add this XAML code:

// Windows 8
<Grid.RowDefinitions>
        <RowDefinition Height="70"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <TextBlock Text="Appbar Sample" Style="{StaticResource PageHeaderTextStyle}"  Grid.Row="0" Margin="20,0,0,10"/>

// Windows 8.1
<Grid.RowDefinitions>
        <RowDefinition Height="70"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <TextBlock Text="Appbar Sample" Style="{StaticResource HeaderTextBlockStyle}"  Grid.Row="0" Margin="20,0,0,10"/>

Add an app bar control to the page, and Button controls to the app bar.

Open MainPage.xaml file from the Solution Explorer.

Just before the closing </page> tag, add the following code:

// Windows 8 
<Page.BottomAppBar>
        <AppBar x:Name="bottomAppBar" Padding="10,0,10,0" Background="Gray">
            <Grid>
                <StackPanel Orientation="Horizontal" HorizontalAlignment="Left">
                    <Button Style="{StaticResource EditAppBarButtonStyle}" />
                    <Button Style="{StaticResource RemoveAppBarButtonStyle}" />
                    <Button Style="{StaticResource AddAppBarButtonStyle}" />
                </StackPanel>
            </Grid>
        </AppBar>
    </Page.BottomAppBar>

// Windows 8.1 
 <Page.BottomAppBar>
        <CommandBar>
            <CommandBar.PrimaryCommands>
                <AppBarButton Icon="Edit" Label="Edit"/>
                <AppBarButton Icon="Remove" Label="Remove"/>
                <AppBarButton Icon="Add" Label="Add" />
            </CommandBar.PrimaryCommands>
        </CommandBar>
    </Page.BottomAppBar>

If developing for Windows 8, you will need to open Common > StandardStyles.xaml. Search for "EditAppBarButtonStyle", "RemoveAppBarButtonStyle", or "AddAppBarButtonStyle" and uncomment the section in which they are defined. Remove  surrounding the section in which they are defined. This step is not required for Windows 8.1 apps.
Click Debug > Start Debugging or F5 to execute the application. Swipe from the top of the screen or press Windows key and Z to open the app bar.

Handle app bar button events.

Stop the debugger by clicking Debug > Stop Debugging (or press Shift+F5).

In MainPage.xaml, update

//Windows 8
<Button Style="{StaticResource EditAppBarButtonStyle}" />
// Windows 8.1
<AppBarButton Icon="Edit" Label="Edit"/>

with the following XAML code

//Windows 8
<Button Style="{StaticResource EditAppBarButtonStyle}" Click="EditButton_Click" />
// Windows 8.1
<AppBarButton Icon="Edit" Label="Edit" Click="EditButton_Click" />

This specifies that EditButton_Click event handler will be called when the app bar Edit button is clicked.

Add the following code at the top of MainPage.xaml:
```
using Windows.UI.Popups;
```

Add the following code between the opening and closing bracket of in the MainPage partial class:

private async void EditButton_Click(object sender, RoutedEventArgs e)
{
    MessageDialog dlg = new MessageDialog("Edit clicked");
    await dlg.ShowAsync();
}

Press F5 to run the application again. Swipe from the top of the screen to display the app bar. If you click the Edit button a MessageDialog is displayed.