| 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;

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();

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!


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!

| Comments

As I spent time last week updating my Callisto library for Windows 8.1 I realized it was a long time between the last release.  Well, I’ve finally updated it for Windows 8.1 release which is now available.  This is a major, yet minor release…allow me to explain.

Windows 8 Support

As of the Callisto 1.4.0 release, Windows 8 support ends.  Support in the non-commercial Open Source world is a bit of a funny term as the support has always been provided by myself and Morten.  I wrestled for a few days trying to keep a source code base, NuGet packages and Extension SDKs in sync with minimal impact.  After that exercise I realized this was just not going to be worth it.  Windows 8.1 developer platform has way more to offer and I just want to move forward.  I’ve locked the Windows 8 release at 1.3.1 (last one) and kept archives of the NuGet/Extension SDK bits on my GitHub project.  The latest code and packages are for Windows 8.1 only.  If you are working on a Windows 8 app and see a notification of a NuGet/SDK update, you should NOT update to 1.4.0.  The tools should block you here, but in case it doesn’t you will be broken in some cases.  I realize this may be an inconvenience to some, but I just couldn’t justify the extra support time for me in this regard.

Windows 8.1 version – first release

So what’s new in the Windows 8.1 version of Callisto?  Well, to be honest, not much.  This primarily is a release to get it on the platform, produce supported bits for Windows 8.1 and .NET Framework 4.5.1 for apps moving forward.  There actually are no new controls in this release but it does bring some minor updates.

Morten was able to check-in our first iteration of Designer support for the controls.  You’ll see all custom properties represented in property panes, have a better drag-and-drop experience, and be able to re-template using Edit Template.  I’ll have a principle moving forward that new controls should have this as the minimum bar for designer support.  Unni has been a tremendous help in motivating Callisto to do this as well as rapid-response help in working through some kinks.  The designer support is only provided in the Extension SDK installation as designer metadata and toolbox usage is not supported in NuGet.

As a new feature in Windows 8.1, XAML now compiles to XAML Binary Format (XBF).  XBF brings performance gains to startup of your application.  As a result of this I’ve prioritized your apps’ performance over developer convenience in some areas.  What this means is that the SDKs ship the XBF version of the toolkit’s generic.xaml.  This gets packaged in your application and helps app startup performance.  For NuGet, what this means is that you don’t get “Edit Template” support in Visual Studio.  If you are using the NuGet package and want to re-template one of the controls, you’d need to grab the template from source and copy it into your project.  This may be an inconvenience but few people re-template Callisto controls and the performance benefits of XBF are prioritized here.  There may be a time in Visual Studio’s release where they will support generating the XBF from the NuGet package, but that is not currently supported.  For the Extension SDK version, I ship the design-time generic.xaml for the control so this is not a problem…and you still get the XBF benefits when your package is built.

In addition to this designer goodness and basic platform support, the 1.4.0 release deprecates a few controls.


Yes, as a part of Windows 8.1, new controls were provided in the base XAML platform and Callisto versions aren’t necessary.  The list of deprecated Callisto controls include:

  • Flyout – now provided in Windows.UI.Xaml.Controls.Flyout
  • Menu – now provided in Windows.UI.Xaml.Controls.MenuFlyout
  • SettingsFlyout – now provided in Windows.UI.Xaml.Controls.SettingsFlyout
  • DynamicTextBlock – now provided by the TextTrimming=”CharacterEllipsis” in Windows 8.1
  • WatermarkTextBox – now provided by the PlaceholderText property provided in Windows 8.1 on input controls

It is a sad day when some of your most-used and proud controls aren’t used anymore, but this is a good thing for developers.  The XAML team worked hard to address the feedback and close the gap in these areas.  As a part of this, some of the planned work around Date/Time pickers was stopped as those are also now provided in Windows 8.1 (and global calendars supported!).  The bugs that exist in the deprecated controls won’t be addressed.

How do I migrate from the Callisto deprecated controls?

Great question!  In a follow-up series of blog posts I’ll show how to migrate off of these Callisto controls to the included ones for Windows 8.1.  Please subscribe to this blog or follow me on Twitter for notification of when I send out the migration articles.  Here are the migration guides for the deprecated controls:

Please help me and others by posting comments if you find more migration gotchas that people should know about!

What is Callisto’s future then Tim?

It is bright.  I love development and I love helping people.  In my view there are still some compelling needs that I see app developers having that are higher level than what the platform provides.  I’ll be still driving forward with Pivot and DataGrid (under testing right now) as well as looking at some other interesting helpers to existing controls by way of some clever attached properties.  If you have suggestions, please log a suggestion on the GitHub site for consideration!

I have a lot of fun doing community/Open Source development and will continue to do so.  I hope this post helps understand the Callisto roadmap!

| Comments

In my working with Windows Store apps, I’ve become increasingly fond/aware of the advantages for app localization.  There are a lot of resources out there for you to localize your app using a good-better-best approach as well.  I’ve previously written about localizing a Windows Store app using some of these methods and what the WinRT platform supports to make this easier in most cases.

Now that you’ve localized your app, you may be faced with the question of how you might want to respond to language choice changes by the user.  Remember that the Windows Store app model is that it honors the user’s language choice preferences matching that with the available languages the app indicates it supports.  This may not always map to the user’s installed OS language.  For instance I can have an English OS install but prefer German in my apps and set my language preference to: de-DE, en-US.  If a Windows Store app was localized in German, then I would see that version instead of English because my preferences say so, regardless of my OS install.

Language switching problem

Now, I’m not as proficient in German as I’d like to be, so there may be times where I need to flip back to English to understand certain areas of an app.  I can do this easily by going to the languages panel and switching my order of preference:

But when I go back to my app, it is still in German…until I terminate/restart the app.  Let’s say I started the app and it honors my language preference:

Now I go and change back to English and click the button to take me to page 2.  It is still in German even though my language preference list is now: en-US; de-DE.

The XAML framework doesn’t automatically re-evaluate the resource cache in response to these changes.  This is something the developer has to manage and luckily there are some easy steps you can do to make this experience better for your users.

We should point out that this is likely a rare case that a user of your app is constantly switching languages and switching back to your app, but having your app support this is a delighter for your users when it does happen.

Solution: listening to qualifier updates

There are APIs to the rescue here!  When you switch your language preferences, the system actually is aware of it, however the context that your app already had at launched has been cached…and thus it will still be delivering the original context-aware resources.  Good for us is that the APIs can let us know when this happens and we can respond.

Since most apps have only a single Window object and since this change is likely rare, we should manage this call and not put it on every Page load, for example, but rather higher up in the App because it will likely be rare that it happens.  In our activation code path we can listen for the resource context to change

   1: protected override void OnLaunched(LaunchActivatedEventArgs args)
   2: {
   3:     ...
   4:     ResourceManager.Current.DefaultContext.QualifierValues.MapChanged += QualifierValues_MapChanged;
   5:     ...
   6: }

In this snippet we are using the default ResourceContext and listening for when its qualifier map changes.  The qualifier map is the set of context for resources like language, but also scale, phonetics (for Japanese), high contrast, etc.  Once that map changes we can force a refresh of the cache essentially:

   1: void QualifierValues_MapChanged(IObservableMap<string, string> sender, IMapChangedEventArgs<string> @event)
   2: {
   3:     ResourceManager.Current.DefaultContext.Reset();
   4: }

This simple flow basically says “hey, when a qualifier has changed, reset the context map so that I get the new data” and our app in subsequent calls to the resources will get the updated resources.

Here’s a video demonstrating the completed before/after approach.

There is a big caveat to this approach.  The change doesn’t automatically affect your current view.  So your page has rendered and is in German.  If I go and change it to English, then go back to my page…it isn’t automatically in English.  Subsequent view loads (and even going back to this page) will get the new resources, but already-rendered ones do not.  The developer can, of course, implement way more logic to refresh the view, traverse the tree, etc. to manage this, but that experience is up to the app developer to determine what is most appropriate for the app itself.

This is a little subtle but helpful tip in enabling your localized apps to be flexible to these types of changes by users when that happens.

Hope this helps!

| Comments

As someone who uses a few iOS devices around the house, I’ve become fond of visiting sites and seeing a little banner that lets me know that a native app is available for the web app I’m using.  This concept was introduced in iOS 6 and called “Smart App Banners” in the developer documentation.  You may have seen them as well

Smart App Banner example

I wanted to provide the same affordance for Windows Store apps and recalled there are already two ways to integrate the web app browsing experience with the native app in the Windows Store:

In iOS, this is implemented a bit natively in mobile Safari, not through any additional JavaScript files/functions.  As with any random idea I have, I always set out to search if it has been done before (often it already has).  I couldn’t find something like this specifically for Windows Store apps, however I did find an implementation for pre-iOS6 browsers as well as Android.  It was from Arnold Daniels and hosted on GitHub, so what’s a guy to do?  Fork it!

And that’s what I did: https://github.com/timheuer/jquery.smartbanner

With a few more conditional checks, if you put this in your web app/site now you’ll get it automatically linked to your Windows Store app if you have the correct meta tags.  For the implementation for Windows Store apps I’ve made some assumptions about the meta tags used.  The following would get you a good experience:

   1: <html>
   2:   <head>
   3:     <title>Hulu Plus</title>
   4:     <meta name="author" content="Hulu LLC"/>
   5:     <meta name="msApplication-ID" content="App" />
   6:     <meta name="msApplication-PackageFamilyName" content="HuluLLC.HuluPlus_fphbd361v8tya" />
   7:     <link rel="stylesheet" href="jquery.smartbanner.css" type="text/css" media="screen"/>
   8:     <meta name="msapplication-TileImage" content="http://wscont1.apps.microsoft.com/winstore/1x/c8ac8bab-d412-4981-8f31-2d163815afe4/Icon.6809.png" />
   9:   </head>
  10:   <body>
  11:         <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8/jquery.min.js"></script>
   2:         <script src="jquery.smartbanner.js">
   1: </script>
   2:         <script type="text/javascript">
   3:             $(function () { $.smartbanner() })
  12:   </body>
  13: </html>

If you have the combination of linking your app using the msApplication-ID and msApplication-PackageFamilyName values and the pinned sites high fidelity msApplication-TileImage value to deliver the combined experience.  If you have all these, then the banner “just works” for you.

NOTE: Because the Microsoft documentation mixes msApplication and msapplication (note the casing on the “A”), you should use the capitalization (which is more consistent in the documentation) for ensuring it all works smoothly. 

Now some may use a different pinned site TileImage than that of what they may use for the app tile, however this can also be overridden in the options:

   1: $(function () { $.smartbanner({ icon:'http://some/url/to/tile/image.png' }) })

When done the web app/site would display a dismissable banner (using Hulu as an example here) on a machine running Windows 8:

Hulu smart app banner example

So adding one reference, 2 files and an initialization and you’ll help give your app a bit more promotional flare for those viewing in browsers other than the ‘modern’ IE view.  As you can see the screenshot above is from the desktop version which doesn’t take advantage of the other msApplication-** attribute usage in desktop mode.  The one thing it doesn’t do that the iOS system-level banner does is detect if the app is installed and change “view” to “open” however there isn’t a mechanism to easily detect if the app is installed using JavaScript from a web app.

NOTE: While the ‘View in Store’ button works in IE, Safari and Firefox it does not work in Chrome.  I’m not sure what any timeframe it would be for Chrome to support the store launch protocol.

Anyhow, I thought this might be a useful addition to app developers web apps that have a Windows Store app counterpart (and perhaps already have an iOS and Androi counterpart as well).  I’ve submitted a pull request to the project I forked from, but you can get it from my GitHub repository for jquery.smartbanner.

Hope this helps!