AppBarHelper for Windows Phone

NuGet package ID: CodeBits.WP.AppBarHelper

The AppBarHelper is a set of classes to help you simplify the handling of the application bar, especially when it is used in a Pivot or Panorama view and the app bar has to dynamically change based in the selected pivot or panorama.

Note: The AppBarHelper does not provide data binding support for the application bar. If that is what you want, then you can try BindableApplicationBar.

Getting started

In the page that contains the appbar, create an instance of AppBarHelper in the Loaded event, passing in the reference to the appbar (which can typically be accessed using the page's ApplicationBar property).
The constructor also accepts an optional second parameter that specifies the root folder for all the images to be used in the appbar. If you don't specify this parameter, you must specify the full path to each image when defining the appbar icon buttons.

var aph = new AppBarHelper(ApplicationBar, "/Images/");

Defining icon buttons

Next, define each appbar icon button as an instance of the AppBarIconButton class. The AppBarIconButton constructor accepts three parameters:
  1. The caption to display for the icon button
  2. The path to the image for the icon button
  3. The event handler that is called when the button is clicked (of type EventHandler).

var saveButton = new AppBarIconButton("save", "Save.png", OnSaveClicked);
var openButton = new AppBarIconButton("open", "Open.png", OnOpenClicked);
var helpButton = new AppBarIconButton("help", "Help.png", OnHelpClicked);

Defining menu items

The next step is to define the menu items that can appear in the appbar. This is done using the AppBarMenuItem class, which accepts two parameters in it's constructor:
  1. The caption to display for the menu item.
  2. The event handler that is called when the menu item is clicked (of type EventHandler).

var settingsItem = new AppBarMenuItem("settings", OnSettingsClicked);
var refreshItem = new AppBarMenuItem("refresh", OnRefreshClicked);

Registering appbar groups

Now that we've defined the icon buttons and menu items for the appbar, we now need to assign them to each panorama/pivot item and define their behaviors.

Before this can be done, we must assign a name (x:Name) to each pivot/panorama item.

Then we call the AppBarHelper's RegisterGroup method for each pivot/panorama item, passing it the icon buttons and menu items that will be displayed for that item. The RegisterGroup method accepts the following parameters:
  1. The pivot/panorama item (which is why we have to give it a name)
  2. The collection of icon buttons for the specified pivot/panorama item. This parameter is optional if there are no icon buttons for the specified pivot/panorama item.
  3. The collection of menu items for the specified pivot/panorama item. This parameter is also optional if there are no menu items for the specified pivot/panorama item.
  4. An initializer delegate, of type Action<AppBarGroup> that can specify additional behaviors for the appbar when the specified pivot/panorama item is activated. This is discussed later.

Let's assume that we have a Panorama with three panorama items named panorama1, panorama2 and panorama3.
panorama1 will display icon buttons saveButton and helpButton, and menu item settingsItem.
panorama2 will display icon buttons openButton and helpButton, and menu items settingsItem and refreshItem.
panorama3 will only display the settingsItem menu item and will not have any icon buttons.

abh.RegisterGroup(panorama1,
    new[] { saveButton, helpButton },
    new[] { settingsItem });
abh.RegisterGroup(panorama2,
    new[] { openButton, helpButton },
    new[] { settingsItem, refreshItem });
abh.RegisterGroup(panorama3,
    menuItems: new[] { settingsItem });

Controlling appbar behavior

For each group (pivot/panorama item), we can control additional behaviors of the appbar. The AppBarGroup class contains properties to customize the following aspects of the appbar:
  • Opacity: The opacity of the appbar, on a range from 0 to 1, where 1 is opaque and 0 is transparant.
  • Mode: The appbar mode. This could be one of the following values:
    • ApplicationBarMode.Default: The appbar is displayed at it's default height.
    • ApplicationBarMode.Minimized: The appbar is displayed minimized.
    • null (the default value): The appbar is displayed in whatever size it was set in the XAML.
  • OnActivated: A delegate that is called whenever the pivot/panorama item is activated.

To set these properties, we use the initializer parameter of the AppBarHelper.RegisterGroup method.

So, in the above example, let's say we want to refresh the screen whenever parorama2 is activated, and the appbar should be minimized and transparent whenever panorama3 is activated.
The above code becomes:

abh.RegisterGroup(panorama1,
    new[] { saveButton, helpButton },
    new[] { settingsItem });
abh.RegisterGroup(panorama2,
    new[] { openButton, helpButton },
    new[] { settingsItem, refreshItem },
    group => {
        group.OnActivated = groupId  => RefreshPage();
    });
abh.RegisterGroup(panorama3,
    menuItems: new[] { settingsItem },
    initializer: group => {
        group.Opacity = 0.5d;
        group.Mode = ApplicationBarMode.Minimized;
    });

Wiring it all up

Now that we've defined the properties of the appbar, we need to wire it up to the Pivot or Panorama control. To do this, the framework provides an extension method on the Pivot and Panorama classes called WireupAppBarHelper that accepts the instance of the AppBarHelper class that we just created.

myPivot.WireupAppBarHelper(aph);
myPanorama.WireupAppBarHelper(aph);

Last edited Jul 14, 2012 at 5:22 AM by jeevanjj, version 12

Comments

No comments yet.