| 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

With the announcement of the Windows 8 Release Preview and matching Visual Studio 2012 RC I’m pleased to share some work that has been a result of my own personal app building, collaborating with some friends during their app building as well as porting some helpful projects that I’ve found helpful in my development.

Disclosure: At the time of this writing I do work for Microsoft, but this has been a personal effort from my own app development and during my own time (late nights and weekends).  I am not able to upload apps to the store at this time to share apps that I’ve written and receive no preferential treatment as a Microsoft employee.

Introducing Callisto, a toolkit of sorts for XAML Metro style apps.  When starting my own app building for the Consumer Preview, I realized there were some experiences and common things that I wanted to implement that weren’t existing controls in a way that I could easily re-use my efforts across app to app that I was building.  The foundation building blocks in the platform were there of course, as was a few existing Open Source projects that I could leverage (yay Open Source!).  I refactored the combination of these things into a single toolkit that I’ve been using for my apps.

Kitchen Sink?

My approach has been mostly pragmatic for me.  This was extracted out of app needs versus being designed as a toolkit from the beginning.  As such, it might feel like a ‘kitchen sink’ approach as there are things that you may never use.  For me, I wanted one thing I could add to my project and get all the goodness that I desired.  This is what led to a single project/toolkit rather than any modular approach.  For example, I originally had included the sqlite-net project in mine because I didn’t want to keep adding it to each project I was using the SQLite database engine.  This is one that I’ve removed since the changes I needed were contributed back to the project and I’ve wrapped them up in a nice easy NuGet package for that portion.

What is it?

Well, it is a toolkit!  It is a combination of some helper libraries as well as some controls.  Some original, some contributed, some ports from existing toolkits.  If you look at the project page you’ll see that it currently has:

  • Helpers: some attached property helpers for web content bindings, converters (i.e., for time relativeness)
  • Extensions: Tilt effect and some helpers for doing some things like OAuth 1.0 (adapted from RestSharp)
  • Controls: Flyout, SettingsFlyout, Menu, LiveTile

Menu flyout example

sample menu flyout from an AppBar

And more to come as I have time.  I’ve had the help of some folks in the community as well as being able to draw off things like the Silverlight Toolkit for some inspiration and some code as well! 

Settings flyout sample

sample settings flyout

The source project comes with a little crappy sample app that I’ve been using as my UI test harness. 

I fully plan to clean this up to a better sample app, but it serves a simple purpose for now.  You can see specific uses in that sample app for some of the controls.  Otherwise feel free to email me directly for some help and I’ll try to point you in the right direction.

How do I get it?

In addition to the source for those who would want that, you can get it in 2 ways: via NuGet or via the Visual Studio Gallery.  Incidentally you can install it both of these ways from within Visual Studio 2012 Express itself!  If using the gallery VSIX installer, then the toolkit will be available for you to use across multiple projects.  The NuGet approach is per-project (as it is with any NuGet package).  After installing the VSIX – if you use that approach – simply choose Add Reference in your project and navigate to the Windows…Extensions section and you’ll see it there.  It is implemented as an Extension SDK for Visual Studio.

Live tile sample

sample live tile (as best you can show in a static screenshot – imagine animation :-))

I plan on submitting regular updates as I refine things, fix bugs and add new controls.  Using the NuGet or VSIX approach for installing will help you keep updated as you’ll receive notifications of updates as long as you are using Visual Studio.

I found an issue/have an idea

Great, I’m sure there are some.  Again, it has been a few folks on our spare time working on this.  Please feel free to log a bug so that we can track the request.  The only place to log a bug is the Issues link on the project page.  No other mechanism will be a good feedback mechanism.

Alternatively, it is Open Source, so feel free to fork and fix.  Ideally you’d contribute your fix back to the project…we’d appreciate it.

Summary

At present the toolkit is for managed code Metro style apps only.  This isn’t because I don’t like C++ developers, but rather that this has been an extraction from my own app building and not designed from the start as any WinRT toolkit.

NOTE: There are a lot of things out there calling themselves WinRT toolkits for XAML.  So far I’ve actually seen none of them that are WinRT, but all are just regular .NET class libraries…just like Callisto.  These are all going to be restricted to use within a managed code XAML app.  If I can get assistance translating this all to WinRT native code, then I could easily see this being more valuable to others.

There are a lot of great APIs in WinRT available to developers.  The SDK samples also provide some helpful code for app developers as well you should ensure you look at (if you are doing ANYTHING with tiles, you should look at the Tiles SDK sample and pay attention to NotificationExtensions).  I hope that Callisto helps you as well in some small areas.

Hope this helps!