Callisto Migration Tip: Flyouts

This is another post in my series of providing migration tips from certain Callisto controls to using Windows 8.1 features. I previously demonstrated probably the most popular Callisto control, the SettingsFlyout. Coming in a very close second in popularity is the Flyout control. The Flyout is a concept of a non-modal small dialog for information and commands.

The primary use case for a lot of Flyouts was something from Button areas, namely the AppBar. Getting the experience right was not intuitively easy using a Popup primitive as you had to handle the right UI guidelines for animation, positioning and dismiss logic. Callisto provided most of this in the Flyout class but also left some people wanting a bit more flexibility. This post will aim to help you migrate existing Callisto Flyout code to the new Windows 8.1 Flyout class.

API Differences

As I did with showing some of the more prominent API differences in SettingsFlyout, I’m presenting some of the important differences for Flyout here. You should read this table as Callisto API==old, Windows 8.1 API==new and what you should use.

Changing your code – an example

Similar to previous examples, I’m going to use the Callisto test app examples here. Flyout in Callisto was another control that didn’t work well in markup. This section will show how you would change your existing code if you were using the Callisto method to use the new Flyout in Windows 8.1. After this section I’ll explain a better way to do this for most cases and the preferred way to use the control. However again I want to provide a “least code change” mechanism to migrate and will do so here.

In Callisto, you most likely wrote code to trigger opening a Flyout. Here’s an example taken from the test app (this was from a Button click event):

private void ShowFlyoutMenu2(object sender, RoutedEventArgs e)
{
    Callisto.Controls.Flyout f = new Callisto.Controls.Flyout();
 
    // content code removed for brevity
    // assume "b" variable here represents a visual tree or a user control
    f.Content = b;
 
    f.Placement = PlacementMode.Top;
    f.PlacementTarget = sender as UIElement;
    
    f.IsOpen = true;
}

The code here basically requires you to wire this up in an event handler and provide the UIElement as the PlacementTarget so it knows where to position the Flyout.

To change this here is what it would look like in Windows 8.1:

private void ShowFlyoutMenu2(object sender, RoutedEventArgs e)
{
    Flyout f = new Flyout();
 
    // again for brevity sake assume "b" here represents content
    f.Content = b;
 
    Flyout.SetAttachedFlyout(sender as FrameworkElement, f);
    Flyout.ShowAttachedFlyout(sender as FrameworkElement);
}

The key here is the SetAttachedFlyout/ShowAttachedFlyout method calls. You must first attach the Flyout to the FrameworkElement (again in this case this is on a Button). Then you show it. I’ve omitted the Placement here to allow for the new default (top) to occur. You could have also added Placement to the change as well. Placement will attempt to fit in this order: Top, Bottom, Left, Right.

The above is meant to demonstrate how to quickly change from Callisto code with minimal impact. The next section actually shows a preferred way of using the control and what a lot of Callisto users were actually asking for.

A better way to use Flyout

As demonstrated the Flyout can still be called from code after attaching it to a FrameworkElement. You are then responsible for calling the ShowAttachedFlyout method to open it. The Windows 8.1 Flyout was designed for the primary use case of ButtonBase elements and will automatically show for you when used in those cases. Let’s assume an example where I have a Button in my AppBar (btw, you should use the new AppBarButtons in Windows 8.1) and I want to show a Flyout when the user clicks on the button. I could do the event model above, but my MVVM friends are cringing a bit. Here’s an alternate and the most likely way you would use Flyout:

<AppBarButton Icon="Add" Label="Add File">
    <AppBarButton.Flyout>
        <Flyout>
            <!-- content here -->
        </Flyout>
    </AppBarButton.Flyout>
</AppBarButton>

As you can see here, on Button we’ve provided an attached property to put the Flyout element and its content. The framework will handle the showing of the Flyout when automatically attached to the Button like this. If you don’t want to use the Button method and perhaps you have to launch a Flyout from some other UIElement, you would use the ShowAttachedFlyout method as demonstrated above.

Summary

As one of the more popular controls this migration may take you down the quick route first and then give you more time to think about using the declarative way to really change later. I recommend using the new Flyout here as you will get all the proper behavior as well as better performance, accessibility and interaction with the software keyboard. We also have a new Windows 8.1 Flyout SDK Sample that walks through this usage and some other scenarios you can examine for your needs.

Hope this helps!