Callisto Migration Tip: Use Windows 8.1 SettingsFlyout

As a part of my promise from my previous post talking about migrating to new Windows 8.1 controls instead of some Callisto ones, I’ll talk about how to leverage the new SettingsFlyout control provided by the framework.

Without a doubt one of the two most popular Callisto controls is the SettingsFlyout. This is a marquee experience for Windows Store apps to provide the “charm” area for managing settings for your application. This control provides the animations, near pixel-perfect UI and behavior for handling the software keyboard movement. Like everything in Callisto, it is simple but powerful and popular. This post is to help you migrate to the platform-provided control if you are currently using the Callisto SettingsFlyout.

API Differences

In the Windows 8.1 implementation there are a few subtle differences that I will call out before walking through an example. I will not be talking about inherited API properties in general (that are provided from the base ContentControl derivation) but rather the specific differences in mappings to how you would have been using Callisto. You should read this table as Callisto API==old, Windows 8.1 API==new and what you should use.

Changing your code – an example

Now that we have a basic overview of the differences I’ll show you how you were likely using this in your app.

NOTE: Perhaps one of Callisto’s biggest feedback was that these flyout-based controls couldn’t be used well in markup. This was due to some design decisions made really early in Callisto development. You may use the new SettingsFlyout differently, but I’ll be pointing out here how to port code with minimal impact, which would still be no markup.

I’ll use the Callisto test app as the example here. When you wanted to have a settings experience you would use the SettingsPane series of APIs to create a SettingsCommand and then do what you want in your code. This is how the Callisto test app does it (this code is in the CommandsRequested event handler):

SettingsCommand cmd = new SettingsCommand("sample", "Sample Custom Setting", (x) =>
{
    // create a new instance of the flyout
    Callisto.Controls.SettingsFlyout settings = new Callisto.Controls.SettingsFlyout();
 
    // set the desired width.  If you leave this out, you will get Narrow (346px)
    settings.FlyoutWidth = (Callisto.Controls.SettingsFlyout.SettingsFlyoutWidth)Enum.Parse(typeof(Callisto.Controls.SettingsFlyout.SettingsFlyoutWidth), settingswidth.SelectionBoxItem.ToString());
    
    // if using Callisto's AppManifestHelper you can grab the element from some member var you held it in
    settings.HeaderBrush = new SolidColorBrush(App.VisualElements.BackgroundColor);
    settings.HeaderText = string.Format("{0} Custom Settings", App.VisualElements.DisplayName);
 
    // provide some logo (preferrably the smallogo the app uses)
    BitmapImage bmp = new BitmapImage(App.VisualElements.SmallLogoUri);
    settings.SmallLogoImageSource = bmp;
 
    // set the content for the flyout
    settings.Content = new SettingsContent();
 
    // open it
    settings.IsOpen = true;
});
 
args.Request.ApplicationCommands.Add(cmd);

Please note that “SettingsContent” class here is a UserControl with some example content.

Fairly simple and the IsOpen would show the settings experience when the user clicked the setting (in this case “AppName Custom Settings”). Now lets look at the modifications you would change using the Windows 8.1 API:

SettingsCommand cmd = new SettingsCommand("sample2", "Sample 2", (x) =>
{
    Windows.UI.Xaml.Controls.SettingsFlyout settings = new Windows.UI.Xaml.Controls.SettingsFlyout();
    settings.Width = 500;
    settings.HeaderBackground = new SolidColorBrush(App.VisualElements.BackgroundColor);
    settings.HeaderForeground = new SolidColorBrush(Colors.Black);
    settings.Title = string.Format("{0} Custom 2", App.VisualElements.DisplayName);
    settings.IconSource = new BitmapImage(Windows.ApplicationModel.Package.Current.Logo);
    settings.Content = new SettingsContent();
    settings.Show();
});
 
args.Request.ApplicationCommands.Add(cmd);

As you can see this is pretty dang close to the same. If you had special “back” logic you could wire-up the BackClick event handler and do what you need to do. Otherwise Back will be handled to you to show the SettingsPane again (or none at all if ShowIndependent was used).

The SettingsFlyout does the same “light dismiss” functionality as Callisto and the rest of the operating system, this is all handled for you.

Callisto’s AppSettings Manager

One of the great feelings in Open Source is when people contribute to your projects in meaningful ways. That was the case when Scott Dorman added a helper class to automatically register SettingsFlyout controls in App.xaml through a static method. We called this AppSettings and had an AddCommand method. For Callisto for Windows 8.1 support I added two new overloads to that method to account for the change from FlyoutWidth (enum) to Width (double). This is the only change and the internal functions remain the same and do the correct wire-up with the SettingsPane/Commands. Here is the old:

AppSettings.Current.AddCommand<SettingsContent>("App Registered", Callisto.Controls.SettingsFlyout.SettingsFlyoutWidth.Wide);

And the change for using the Windows 8.1 platform control:

AppSettings.Current.AddCommand<SettingsContent>("App Registered 2", 500);

Again the SettingsContent class here is my UserControl that represents my content. That’s it and a small change helps keep this really helpful class around!

Summary

Again this was an extremely widely used control in Callisto and as you can see there are only a few subtle changes to your code to use the Windows-supported control. In doing so you get better support for orientation/rotation/software keyboard handling/accessibility and performance. The SettingsFlyout in Windows 8.1 can actually be used as a UserControl itself (and should). The Application Settings SDK Sample shows this in Scenario 3 on how to use the new control in this manner.

I hope this helps you to migrate to the new control!