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

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

WHAT?!

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 the late nights when I have time to work on Callisto (my Windows 8 XAML toolkit), I often am making changes that I really wish I could either pair with someone on or at a minimum solicit some feedback.  Primarily single-person open source projects are lonely :-).

Last night was no different.  I had a user of Callisto having a problem with a specific code path.  While my testing of the fix was fine, I didn’t want to rush it without him understanding the simple fix.  I had no good way of showing him a combined diff to comment on at the time.  My problem was, what I thought, simple: how do I quickly share a diff from a GitHub project without requiring them to have a fork?

I set out to the best place to have an argument, Twitter.  I asked the same question and got a lot of different responses, but almost all of them pointing to what appears to be the typical git flow in this matter is to use pull requests for code reviews and sharing potential updates.  This really frustrated me as I thought it was unnatural to the goal I was trying to accomplish.  Lots of folks told me this was the way to do it and that I was thinking about it wrong.  To them I say this is broken.  I didn’t want to pollute pull requests to be a mix of legitimate pull requests to “in-flight” code changes that shouldn’t be even considered for merge yet.  I simply wanted a quick, light-weight way to share a diff graph.

Paul Betts (as he has always awesomely helped with my GitHub questions) pointed me to the thing I was ultimately looking for:

   1: git diff > current.diff

This gave me the output that I needed and Gist understands color coding for this data so I just needed to post it there.  Good thing is that GitHub has an API that is relatively simple to understand.  Since I’ve been using poshgit as my shell lately I set out to create a CmdLet for my flow.  I wanted one command that would grab the diff and post to a Gist and give me the URL.  I’ve never touched a line of PowerShell programming before and set out to start.

Honestly, it was painful to understand PowerShell for me in this simple task.  The PowerShell “IDE” is slow to help with any really good flow.  I wanted some VS experience to bootstrap me and I knew I didn’t want a full-on assembly approach.  A PowerShell script should do me just fine.  I scoured many sites online and started out with my script.  After a few hours of searching/trying I was almost there but still not successful.  I ended the night posting back to Twitter with a Gist of my attempt.

It was late, I went to bed.  As is how most things happen on the interwebs, I awoke to some pointers to where someone has already done most of the work!  Despite my searching I never found something that basically took me 90% there already.  This was in the form of PsGist.  Boom!  This is exactly what I needed.  I just needed to modify the input from a literal file to the source of the diff.  I spent an unnecessary hour fighting with an unauthorized error on the GitHub API due to some unexpected value being in the string captured after entering credentials, but after that was solved I was done.  I decided to merge this back to PsGist and submit a pull request for the new command.  A few minutes later and after a few questions/quick modification, it was merged.  I now have a simple/fast flow to quickly say “hey, here’s what I’m working on, what do you think?” to anyone without having to do any different branching that isn’t currently in my flow.

   1: New-DiffGist -Description "SettingsFlyout fix" -Public

After the module is imported the above command will perform a diff, and immediately post that to Gist and give you the URL (and optionally launch in browser if you use the –Launch param).  I know it may sound trivial, but it helps my flow and is the simple thing that I was looking for.  Thanks Ryan for the PsGist starting point (and for merging my new CmdLet)!

Hope this helps someone!

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