Today the Bing team announced the release of their WinRT Bing Maps control (BETA) for XAML applications.  First the goods:

• Read their announcement here: Bing Maps for Metro style apps
• Download the bits: Bing Maps SDK for Metro style apps (VSIX)
• Read the reference API docs: Bing Maps SDK

If you are familiar with the Silverlight control, it is similar in nature to how you would use it in your XAML Metro style app.  Here’s some helpful tips that are in the docs but just wanted to elevate them because we have a tendency not to read docs :-).

Installing

Installing is simple for Visual Studio.  Download the VSIX file and double-click it.  If you have both Express and Ultimate installed it will prompt you to install it for both installations.  That’s it…you are done.  If you had VS running while you did this, it would be a good idea to restart VS.

Creating a .NET XAML application with maps

Once you restart VS, you can create a new C# Metro style application.  Once you have this, just right click on the project and choose Add Reference and then navigate to the Windows\Extensions section and you will see Bing Maps:

When you do this you will also want to add a reference to the VCLibs Extension at this time.  Why?  Well, the Map control is a native control.  Adding the VCLibs dependency at this time will add the necessary information in your app’s package manifest noting the dependency and it will install any required package dependencies from the store when your user’s install it.

If you compile your application immediately you will notice an exception during build:

   1: 1>------ Build started: Project: Application17, Configuration: Debug Any CPU ------

   2: 1>C:\Windows\Microsoft.NET\Framework\v4.0.30319\Microsoft.Common.targets(1667,5): error MSB3774: Could not find SDK "Microsoft.VCLibs, Version=11.0".

   3: 1>C:\Windows\Microsoft.NET\Framework\v4.0.30319\Microsoft.Common.targets(1667,5): error MSB3778: "APPX" attributes were found in the SDK manifest file however none of the attributes matched the targeted configuration and architecture and no "APPX" attribute without configuration and architecture could be found. If an appx is required then the project will fail at runtime.

   4: ========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

This is because by default the managed applications are “AnyCPU” configuration and the native control doesn’t have that configuration.  Change your app to be either x86 or amd64 and your build will succeed.  This means that yes, you will want to create multiple architecture-specific packages for your app.  The good thing is during package creation, the tools in Visual Studio make this easy for you.

Creating a C++ XAML application with maps

For C++ the step is to just reference the Bing Maps extension SDK and you are done.  C++ projects are always architecture-specific so you don’t have the AnyCPU situation here.

Using the Map control

You’ll need to get set up with an API key, which the getting started docs inform you about.  Once you have that you are ready to use the control.  I’m a fan of putting the API key in my App.xaml as a resource:

   1: <Application.Resources>

   2:     <ResourceDictionary>

   3:         <ResourceDictionary.MergedDictionaries>

   4:             <ResourceDictionary Source="Common/StandardStyles.xaml"/>

   5:         </ResourceDictionary.MergedDictionaries>

   6:         <x:String x:Key="BingMapsApiKey">YOUR KEY HERE</x:String>

   7:     </ResourceDictionary>

   8: </Application.Resources>

And then in my Map control I can just refer to it:

   1: <Page

   2:     x:Class="Application17.BlankPage"

   3:     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

   4:     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

   5:     xmlns:local="using:Application17"

   6:     xmlns:d="http://schemas.microsoft.com/expression/blend/2008"

   7:     xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"

   8:     xmlns:bing="using:Bing.Maps"

   9:     mc:Ignorable="d">

  10:  

  11:     <Grid Background="{StaticResource ApplicationPageBackgroundBrush}">

  12:         <bing:Map x:Name="MyMap" Width="640" Height="480" 

  13:             Credentials="{StaticResource BingMapsApiKey}" />

  14:     </Grid>

  15: </Page>

Once I have those pieces in place, I’m done and can run my app and get full map interactivity.  Notice the xmlns declaration in my Page with the “using:Bing.Maps” notation.  Now when I run:

I can quickly add location to my app by setting the capability in the Package.appxmanifest and then wiring up the map to center on my current location…

   1: async protected override void OnNavigatedTo(NavigationEventArgs e)

   2: {

   3:     Geolocator geo = new Geolocator();

   4:     geo.DesiredAccuracy = PositionAccuracy.Default;

   5:     var currentPosition = await geo.GetGeopositionAsync();

   6:  

   7:     Location loc = new Location() { Latitude = currentPosition.Coordinate.Latitude, 

   8:         Longitude = currentPosition.Coordinate.Longitude };

   9:  

  10:     MyMap.SetView(

  11:         loc, // location

  12:         13, // zoom level

  13:         true); //show animations)

  14:  

  15: }

I’m excited about what the Bing team has done here and you should go grab it, read the docs and start incorporating location visualization into your Metro style XAML apps today!

Hope this helps!

So you’ve started to kick the tires of the Windows 8 Consumer Preview and now you are building an app.  You’ve read all the UX design guidelines and started looking at some great apps on the store.   Perhaps you’ve also viewed the online documentation and some samples?  And you’ve likely read about the contract implementations and other charms items like custom settings. 

UPDATE: Take a look at Callisto: a XAML toolkit which has a SettingsFlyout control

What is Settings?

When I refer to Settings here I’m referring to that consistent experience in Metro style apps when the user invokes the charms bar and chooses settings.  By default every application will respond to that Settings charm.  If you do nothing you will get the default experience that you may have seen:

The text items underneath your app title are referred to as commands.  Each application will always get the Permissions command.  When the user clicks this they will get some “about” information on your app (name, version, publisher) as well as the permissions the app has requested.  As an app developer, you have to do nothing to get this experience.  In addition to that the Settings pane shows some OS-level options like volume, Wi-Fi, brightness, etc. that the user can manipulate.  But you, my fellow app developer, can also implement custom settings options in your app.

The custom SettingsCommand

The first thing you have to do to customize your experience is implement a custom SettingsCommand.  These are implemented by first listening to when the SettingsPane will request if there are any additional commands for the current view.  Settings can be global if you have something like a “master” page setup in your XAML application, but can also be specific to a currently viewed XAML page.  It is not an either/or but a both.  I’ll leave the exercise up to you and your app on when you need which (or both).

First thing you have to do is listen for the event.  You would likely do this in your XAML view’s constructor:

   1: public BlankPage()

   2: {

   3:     this.InitializeComponent();

   4:  

   5:     _windowBounds = Window.Current.Bounds;

   6:  

   7:     Window.Current.SizeChanged += OnWindowSizeChanged;

   8:  

   9:     SettingsPane.GetForCurrentView().CommandsRequested += BlankPage_CommandsRequested;

  10: }

Notice the SettingsPane.GetForCurrentView().CommandsRequested event handler that I am using.  This will get triggered whenever the user invokes the Settings charm while on this view.  It is your opportunity to add more commands to that experience.  In your method for this you would create your new SettingsCommand and add them to the ApplicationCommands:

   1: void BlankPage_CommandsRequested(SettingsPane sender, SettingsPaneCommandsRequestedEventArgs args)

   2: {

   3:     ResourceLoader rl = new ResourceLoader();

   4:  

   5:     SettingsCommand cmd = new SettingsCommand("sample", 

   6:         rl.GetString("SoundOptionCommandText"), (x) =>

   7:         {

   8:             // more in a minute

   9:         });

  10:  

  11:     args.Request.ApplicationCommands.Add(cmd);

  12: }

You are able to add the text-based commands to the SettingsPane at this time.  The second argument I provided above will be the text that will display as the menu.  Notice how here I’m using ResourceLoader to get the string value for the text to be displayed.  This is a best practice to ensure you give your user’s the best experience.  Even though you may not localize now, setting this up in the beginning makes it way easier to just drop in localized strings and not have to change code.  The “SoundOptionCommandText” exists as a key/value pair in a file in my project located at en/Resources.resw.

Now that I have this enabled and my CommandsRequested wired up, when I invoke the charm while my app is running you see my new command:

Yippee!  Your custom commands will show before the Permissions one.  The next step is to actually add something valuable to the user when they click on this new command…and that means some UI.

The custom Settings UI

When your user clicks your new shiny command you want them to see some shiny, but relevant UI.  If you were using HTML/JS you would use the WinJS.UI.SettingsFlyout control to do a lot of this for you.  There is a sample of this for comparison located in the Windows 8 developer samples.  In XAML there isn’t the literal ‘SettingsFlyout’ control equivalent, but a set of primitives for you to create the experience.  There are a few pieces you will need in place.

First I create a few member variable helpers to store some items away:

• _windowBounds – this is the Rect of the current Window size.  I will need this for proper placement
• _settingsWidth – The UX guidelines suggest either a 346 or 646 wide settings flyout
• _settingsPopup – the Popup that will actually host my settings UI

The Popup is the important piece here.  It is the primitive that provides us with the “light dismiss” behavior that you see a lot in the Windows 8 experience.  This is where you have a menu/dialog and you simply tap away and it dismisses.  Popup.IsLightDismissEnabled gives us that functionality in our control that we will need in XAML.  Now let us go back to where we created our custom SettingsCommand and add back in the creation of our Popup and custom UI:

   1: SettingsCommand cmd = new SettingsCommand("sample", rl.GetString("SoundOptionCommandText"), (x) =>

   2: {

   3:     _settingsPopup = new Popup();

   4:     _settingsPopup.Closed += OnPopupClosed;

   5:     Window.Current.Activated += OnWindowActivated;

   6:     _settingsPopup.IsLightDismissEnabled = true;

   7:     _settingsPopup.Width = _settingsWidth;

   8:     _settingsPopup.Height = _windowBounds.Height;

   9:  

  10:     // more to come still

  11: });

Notice that we are creating the Popup, setting the width to the value specified in _settingsWidth and the height to whatever the current height of the active Window is at this time.  We are also listening to the Activated event on the Window to ensure that when our Window may be de-activated for something that a user may not have done via touch/mouse interaction (i.e., some other charm invocation, snapping an app, etc.) that we dismiss the Popup correctly.  here is the OnWindowActivated method definition:

   1: private void OnWindowActivated(object sender, Windows.UI.Core.WindowActivatedEventArgs e)

   2: {

   3:     if (e.WindowActivationState == Windows.UI.Core.CoreWindowActivationState.Deactivated)

   4:     {

   5:         _settingsPopup.IsOpen = false;

   6:     }

   7: }

   8:  

   9: void OnPopupClosed(object sender, object e)

  10: {

  11:     Window.Current.Activated -= OnWindowActivated;

  12: }

Notice we are also listening for the Popup.Closed event.  This is so that we can remove the OnWindowActivated method to avoid any reference leaks lying around.  Great, now let’s put some UI into our Popup.

For my example here I’m using a UserControl that I created to exhibit my settings needs.  Your use may vary and you may just need some simple things.  As we know in XAML there is more than one way to implement it in this flexible framework and this is just an example.  Going back to our custom SettingsCommand we now create an instance of my UserControl and set it as the Child of the Popup, setting appropriate Width/Height values as well:

   1: SettingsCommand cmd = new SettingsCommand("sample", rl.GetString("SoundOptionCommandText"), (x) =>

   2: {

   3:     _settingsPopup = new Popup();

   4:     _settingsPopup.Closed += OnPopupClosed;

   5:     Window.Current.Activated += OnWindowActivated;

   6:     _settingsPopup.IsLightDismissEnabled = true;

   7:     _settingsPopup.Width = _settingsWidth;

   8:     _settingsPopup.Height = _windowBounds.Height;

   9:  

  10:     SimpleSettingsNarrow mypane = new SimpleSettingsNarrow();

  11:     mypane.Width = _settingsWidth;                    

  12:     mypane.Height = _windowBounds.Height;

  13:  

  14:     _settingsPopup.Child = mypane;

  15:     _settingsPopup.SetValue(Canvas.LeftProperty, _windowBounds.Width - _settingsWidth);

  16:     _settingsPopup.SetValue(Canvas.TopProperty, 0);

  17:     _settingsPopup.IsOpen = true;

  18: });

Now when the user clicks the “Sound Options” they will see my custom UI:

And if the user taps/clicks away from the dialog then it automatically dismisses itself.  You now have the fundamentals on how to create your custom UI for settings.

Some guiding principles

While this is simple to implement, there are some key guiding principles that make this key for your user’s experience.  First and foremost, this should be a consistent and predictable experience for your users.  Don’t get crazy with your implementation and stay within the UX design guidelines to ensure your app gives the user confidence when using it.  Additionally, here are some of my other tips.

Header Elements

You’ll notice above that the header of the custom UI is specific and contains a few elements.  The title should be clear (and again be ideally localized) in what the settings is doing.  The background color would match your app’s branding and likely be the same as the value of BackgroundColor in your app’s package manifest.  Putting your logo (use the same image you use for your SmallLogo setting in your package manifest) helps re-enforce this is the setting only for this app and not for the system.  Additionally providing a “back” button so the user can navigate back to the root SettingsPane and not have to invoke the charm again if they wanted to change other app settings.  In my example, the button simply just calls the SettingsPane APIs again to show it:

   1: private void MySettingsBackClicked(object sender, RoutedEventArgs e)

   2: {

   3:     if (this.Parent.GetType() == typeof(Popup))

   4:     {

   5:         ((Popup)this.Parent).IsOpen = false;

   6:     }

   7:     SettingsPane.Show();

   8: }

You may be curious to see the XAML used for my custom UI and I’ve included that in the download at the end here as not to take up viewing area here on the key areas.

Immediate Action

Unlike some modal dialog experiences, the Settings experience should create immediate change to your application.  Don’t put confirmation/save/cancel buttons in your UI but rather have the changes take effect immediately.  For instance in my sound example, if the user invokes the Settings charm, clicks/taps on my Sound Options and toggles the Sound Effects option on/off, then the sound should immediately turn on/off.  Now implementing this philosophy may change the way you create your custom UI and/or UserControl, but take that into account when designing.

Light Dismiss

This concept of light dismiss is about honoring the user’s action and not requiring interruption.  This is why we use the Popup.IsLightDismissEnabled option as we get this capability for free.  By using this if the user taps away to another part of the application or Window, then the Popup simply dismisses.  Don’t hang confirmation dialogs in there to block the user from doing what they want, but rather honor the context change for them.

Summary

The Windows platform has afforded us developers a lot of great APIs to create very predictable and consistent user experiences for the common things our apps will need.  Settings is one of those simple, yet effective places to create confidence in your application and a consistent Windows experience for your users.  Stick to the principles:

• Set up custom commands that make sense for the context of the view and/or for the app as a whole
• Create and show your UI according to the UX design guidelines
• Have your settings immediately affect the application
• Ensure that you use the dismiss model

Combine all these and you will be set.  Everything I talk about above is supported in XAML and WinRT.  My example is in C# because I’m most proficient in that language.  But this 100% equally applies in C++ as well and should be identical in practice.

You may be saying to yourself wouldn’t this make a great custom control?  Ah, stay tuned and subscribe here :-)!

Hope this helps!

Download Sample: download removed...see Callisto

An old colleague of mine and now HTML extraordinaire, Adam Kinney, just recently posted on his spelunking of some styling in both WinJS and XAML runtimes with regard to icons/buttons to use in a Metro style app and the AppBar.

Adam has two posts:

• (WinJS) Windows 8 AppBarIcons enumerated and visualized
• (XAML) Windows 8 AppBarButtonStyles enumerated and visualized

Basically what these do is define a set of styles, both in CSS and XAML, that map back to unicode values in the Segoe UI Symbol font.  This contains a set of glyphs that are well-suited for use within an AppBar.  As an example in WinJS you would use:

   1: <button data-win-control="WinJS.UI.AppBarCommand" 

   2:         data-win-options="{icon:'back', label:'Back'}"><button>

And in XAML you would use:

   1: <Button Style="{StaticResource PreviousAppBarButtonStyle}" />

One thing that Adam points out is that WinJS includes definitions for a LOT of styles while the included StandardStyles.xaml file (provided for you when you create a new project in Visual Studio) defines a much smaller subset.  When determining what styles to include in the XAML set, we opted for choosing the most common rather than to bloat the ResourceDictionary with things you may not use.

NOTE: Even within the provided one, you should always make it a best practice to REMOVE styles/templates that you aren’t using so the parser doesn’t have to worry about them.

Adam also notes that he likes the style of defining the WinJS ones a bit better as he mentions the XAML syntax feels heavy.  I commented on his blog that WinJS is doing a lot of work for him here that has already defined the style.  If WinJS didn’t exist, surely it would be ‘heavy’ in defining them.  I’m still not sure why the XAML one feels heavy (once you just assume that a definition has been made for you in the ResourceDictionary provided – especially when I look above, they basically both look the same…but I digress.

One thing that I wanted to point out was how the tools, Visual Studio and Blend, help make it way easy to choose and quickly visualize these styles on the design surface.  For HTML/JS apps you need to use Blend for this as VS doesn’t support this feature at this time.  When in Blend in your HTML/JS app you can open up the control palette and see a helper for AppBar Command Button:

And this produces a generic button definition much like above:

   1: <button data-win-control="WinJS.UI.AppBarCommand" 

   2:         data-win-options="{label:'Button', type:'button'}"></button>

What you can’t do from now (that I could see) is quickly pick from a set of those data-win-options to choose which one you want…so you still have to know what the definition is that you want for the icon/label.  Let’s contrast that with the XAML experience with strongly-defined styles.  In VS or Blend I can use the resource picker to pick from a set of styles that apply to my control type, in this case button:

I can quickly change and see the option on the design surface.  Now again, if you don’t need all these styles, then please delete what you aren’t using from your ResourceDictionary.

It is great that we have design-time implementations of these styles and of course I’m partial to the XAML one as more familiar to me.  Adam pointed out the discrepancy of not having all the styles defined.  As I note, you shouldn’t have defined what you don’t need, but in the spirit of adding value, here’s an updated StandardStyles.zip with all the 150 icons defined.

Hope this helps!

I hope that you had a chance to download the Windows 8 Consumer Preview.  One of the things that you will absolutely want to do is watch Jensen’s video as a video walk-through of Windows 8 features, focusing on working with the operating system as a user, introducing the gestures and things you want to know about.  It is a great, short video and you should definitely watch it:

As an avid keyboard user (and one without a touch device currently) I rely on the ‘desktop’ use of my Windows installation.  In addition to those things that Jensen mentions in his video, here’s a list of some helpful keyboard shortcuts…

These have been helpful for me to work through these new experiences quickly.  Hope this helps!

Today, Microsoft will reveal the Windows 8 Consumer Preview for download to everyone.  This builds on the momentum and feedback from the Developer Preview released in September.  I’m very excited to get the developer platform in front of you so you can see the changes and new features we’ve made available as well as fixes based on your feedback.

Along with the release of the actual bits, we’ve updated many resources for you to take advantage of as a developer, so allow me to iterate my top resources for you now…

• First, download the Windows 8 Consumer Preview
• As a developer, get the Visual Studio 11 Express Beta Tools
• Subscribe to the Windows 8 app developer blog which is a new blog for the developer community direct from the platform teams
• Visit the MSDN Developer Center for Metro style apps where you will find samples, forums and updated documentation.
• Read the Windows 8 UX design guidelines (and download assets like PSD guides, etc.)

I’m very excited to see the progress of applications that are coming in the Windows Store and even more interested to see what you are going to be building!  Please feel free to subscribe to this blog as well for XAML-related tips and tricks on the platform!