| Comments

I’m continuing in my series of helping to provide Callisto migration tips to use new Windows 8.1 features. In a recent post I talked about the Flyout control and provided the path to the platform-provided features. In Callisto, the Menu control was provided as sort of a prescribed content for the Flyout control. In fact you really couldn’t use Menu without Flyout.

Menu control sample image

This guide will help you change to the platform-provided MenuFlyout now available in Windows 8.1.

API Differences

On the public surface area, there aren’t actually many changes here. Windows 8.1 MenuFlyout provides more functionality as it derives from FlyoutBase, which is the base for Flyout as well. So you get the same ShowAttachedFlyout capability that you have there. Both have an Items property that is a collection of the menu items you’d put in there. For these purposes I’m not detailing out the minutiae of differences between FlyoutBase and Menu here as it isn’t relevant to migration but is useful later as I’ll demonstrate. The main reason is that as I noted earlier, you actually can’t use Menu in Callisto without using Flyout, hence the lack of a significant delta here at the Menu level.

Change to the MenuFlyout

As with the other examples, I’m going to use the Callisto test app code here to show migration. Since Menu needed Flyout, you had more of a code-focused approach in ideal Callisto usage. We believe that the main use cases for Menus are also in Button invoke scenarios. Here’s an example of showing a Menu in Callisto:

private void ShowFlyoutMenu(object sender, RoutedEventArgs e)
{
    Callisto.Controls.Flyout f = new Callisto.Controls.Flyout();
    f.PlacementTarget = sender as UIElement;
    f.Placement = PlacementMode.Top;
    f.Closed += (x, y) =>
    {
        LogEvent("Event: Closed");
    };
 
    Menu menu = new Menu();
 
    MenuItem mi = new MenuItem();
    mi.Tag = "Easy";
    mi.Tapped += ItemClicked;
    mi.Text = "Easy Game";
    mi.MenuTextMargin = new Thickness(28, 10, 28, 12);
 
    MenuItem mi2 = new MenuItem();
    mi2.Text = "Medium Game";
    mi2.Tag = "Medium";
    mi2.Tapped += ItemClicked;
    mi2.MenuTextMargin = new Thickness(28, 10, 28, 12);
 
    ToggleMenuItem tmi = new ToggleMenuItem();
    tmi.Text = "Enable Logging";
    tmi.IsChecked = chk;
    tmi.Tapped += (a, b) =>
        {
            chk = !chk;
        };
 
    menu.Items.Add(mi);
    menu.Items.Add(mi2);
    menu.Items.Add(new MenuItemSeparator());
    menu.Items.Add(new MenuItem() { Text = "Foobar something really long", Tag = "Long menu option", MenuTextMargin = new Thickness(28,10,28,12) });
    menu.Items.Add(tmi);
 
    f.HostMargin = new Thickness(0); // on menu flyouts set HostMargin to 0
    f.Content = menu;
    f.IsOpen = true;
}

You will have to understand some of the events and variables are examples here (LogEvent and chk). Notice how you have to create a Flyout first, then put the Menu in it with all the items. Here is how you would migrate that code to provide immediate migration to the platform control:

private void ShowMenuFlyout3(object sender, RoutedEventArgs e)
{
    MenuFlyout mf = new MenuFlyout();
    MenuFlyout.SetAttachedFlyout(sender as FrameworkElement, mf);
    mf.Closed += (x, y) =>
        {
            LogEvent("Event: Closed");
        };
 
    MenuFlyoutItem mi = new MenuFlyoutItem();
    mi.Tag = "Easy";
    mi.Tapped += ItemClicked;
    mi.Text = "Easy Game";
 
    MenuFlyoutItem mi2 = new MenuFlyoutItem();
    mi2.Text = "Medium Game";
    mi2.Tag = "Medium";
    mi2.Tapped += ItemClicked;
 
    ToggleMenuFlyoutItem tmi = new ToggleMenuFlyoutItem();
    tmi.Text = "Enable Logging";
    tmi.IsChecked = chk;
    tmi.Tapped += (a, b) =>
        {
            chk = !chk;
        };
 
    mf.Items.Add(mi);
    mf.Items.Add(mi2);
    mf.Items.Add(new MenuFlyoutSeparator());
    mf.Items.Add(tmi);
 
    MenuFlyout.ShowAttachedFlyout(sender as FrameworkElement);
}

Now notice how the shape of the items is similar so helping with some migration. You create a MenuFlyout, MenuFlyoutItems (notice the separator and ToggleMenuFlyoutItem), then add them to the MenuFlyout and show it. But just like Flyout in Windows 8.1 we believe there was an easier way we could provide creating and using MenuFlyout.

A better way to use MenuFlyout

Much like Flyout we believe the primary use case for MenuFlyout will be from ButtonBase invocations. Let’s look at the declarative approach to the code above:

<AppBarButton Icon="Add" Label="New Game">
     <AppBarButton.Flyout>
         <MenuFlyout>
             <MenuFlyoutItem Tag="Easy" Text="Easy Game" Tapped="ItemClicked" />
             <MenuFlyoutItem Tag="Medium" Text="Medium Game" Tapped="ItemClicked" />
             <MenuFlyoutSeparator />
             <ToggleMenuFlyoutItem Text="Enable Logging" IsChecked="True" />
         </MenuFlyout>
     </AppBarButton.Flyout>
 </AppBarButton>

This allows us to provide an automatic way to show the menu when the button is clicked. If we aren’t using a Button we can still use the Set/ShowAttachedFlyout method as demonstrated above.

Summary

Moving to the new MenuFlyout control will again gain you better performance, compliance with UI guidelines, declarative model and accessibility features. As you can see there is a short-term migration approach using the the ShowAttachedFlyout method to allow you to very quickly take advantage of the new control if you were using the Callisto code method. Your app can then decide if it makes sense to move to the declarative model. Either way, the new control is great and you should use it! We also have a Windows 8.1 MenuFlyout SDK Sample that you can examine to play around with the API.

Hope this helps!

| Comments

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.

Flyout sample image

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.

Callisto APIWindows 8.1 APIComments
HorizontalOffset/VerticalOffsetn/aNot really needed in almost all default cases. If you really needed to adjust the default logic, you could provide a template for FlyoutPresenter and change the margin there.
HostMarginn/aNot needed
HostPopupn/aNot needed
IsOpenShowAttachedFlyoutSee explanation below
PlacementPlacementSame concept, different enum
PlacementTargetShowAttachedFlyoutSee explanation below
ClosedClosed
n/aOpenedNew event
n/aOpeningNew event

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!

| Comments

Continuing on my tips in migrating from Callisto for platform-supported Windows 8.1 APIs, I’ll cover another simple, but helpful text control in this post: WatermarkTextBox.

WatermarkTextBox sample image

When writing an app that provides input from customers, providing some “hint” when there is no text is a valuable thing to add. Here’s how to change to the platform-supported APIs.

Change back to TextBox

When using Callisto, you had to use a specific control that derived from TextBox. Simple enough:

<callisto:WatermarkTextBox Watermark="Enter some text..." />

In Windows 8.1 the concept of watermark text was added to controls for text input, including PasswordBox (one of the requests Callisto frequently got in this area). This support is added via the PlaceholderText property on these controls. The use is simple and to change from Callisto, simply move back to TextBox control and use the property:

<TextBox PlaceholderText="Enter some text..." />
<PasswordBox PlaceholderText="Enter your password" />

There are some subtle UI differences here in that the PlaceholderText in Windows 8.1 is not italic (something I personally prefer to better differentiate), but that’s about it. The same functionality of when it shows and doesn’t exists.

Summary

A quick change to your code will yield you yet another gain of removing a sub-classed control with it’s own template and take advantage of platform-supported text goodness and performance. Make the change my friends, make the change! Be sure to check out the other Callisto migration tips when moving your app to Windows 8.1!

Hope this helps!

| Comments

Frankly I’m going to be honest and say I’m not sure why it took us so long to add this capability to TextBlock, especially given that the support in Callisto provided via DynamicTextBlock was originally done in Silverlight 2. O_O. Well, Robby can rest well now knowing that we no longer have to depend on his contributions to Callisto.

DynamicTextBlock sample image

Example of use DynamicTextBlock on bottom

Here’s the quick migration tip.

Change back to TextBlock

The DynamicTextBlock served one purpose, to provide trimming at the character level rather than the word level. The implementation of DynamicTextBlock was done using a ContentControl which, frankly, was probably too heavy handed for the usage here. However since TextBlock is sealed this was necessary. The usage for having this was simple:

<callisto:DynamicTextBlock Text="Some long text here" TextWrapping="NoWrap" />

And changing this to provide platform-supported trimming is simple as well:

<TextBlock Text="Some long text here" TextTrimming="CharacterEllipsis" />

Yep, that’s it.

Summary

This migration should be quick and painless. Using the platform’s TextBlock will allow you to benefit from the new typography settings provided in Windows 8.1 (like TextTrimming=”Clip” as well) in conjunction with this as well as better global text support. I’m thankful we were able to add this into the platform finally.

Hope this helps!

| Comments

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.

SettingsFlyout example image

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.

Callisto APIWindows 8.1 APIComments
ContentBackgroundBrushBackgroundContentBackground brush was a temporary workaround to an initial poor implementation in the Callisto template
ContentForegroundBrushForegroundSame as above
FlyoutWidthWidthThe new UI guidelines don’t specify hard widths for ‘narrow’ or ‘wide’ but recommend a maximum of 500px width. Here you can set your value.
HeaderBrushHeaderBackgroundNaming difference, they do the same thing
HeaderTextTitleNaming difference, they do the same thing…this is the title of the settings area
ColorContrastConverterHeaderForegroundAllows you to specify the foreground color for the title text. In Callisto, this was automatically interpreted for you based on the background color and determined to be light/dark based on a contrast calculation
HostPopupN/Anot needed
IsOpenShow/ShowIndependent/HideMethods for showing/hiding the SettingsFlyout. If ShowIndependent is used it interacts with the back button differently.
SmallLogoImageSourceIconSourceYou can still use AppManifestHelper from Callisto to get this for you
BackClickedBackClickSame functionality

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!