Working with the Search charm in Windows 8

I actually attended BUILD. I sat there, bombarded with so much information about Windows 8 and Metro style applications that I just went into my happy place, franticly taking notes on all that I should investigate later on. That very long and almost unreadable list contained, amongst many others, the keywords – contracts and charms. To be perfectly honest I didn’t really grasp the concept at first. Implement contracts in order to make your application available to charms… say what now? My best way to actually understand something really follows the same pattern every time (although sometimes my progress stops at confusion).

Thought process

This time was no different, so when I finally reached some sort of understanding I ended up with this blog post. I’ll try to explain charms and contracts. I also want to show how you can use a charm, more specifically the search charm, to extend your application into Windows 8.

Charms and contract – no comprende?

Let’s start with charms. As it is, you get five charms in Windows 8. You have Search,The charms Share, Start (you can’t really do anything with this one, it just shows the home screen), Devices and Settings. They can either be accessed by sliding in from the right hand side or, if you are using a mouse, you can find them in the bottom left. You can think of charms as a more powerful version of the traditional start menu. A start menu that you can use to extend your application into the operating system.

What about contracts then? Contracts are what connect your application to the charms. You just select the required contract in your appmanifest and then voilà. You can write all of your code without doing this, but then will get an AccessViolationException when running your code – which tends to go against best practice.

Implementing the search charm

So, I started with a basic implementation of the search charm. As a test application I had my conference application that I wrote for Øredev. First up, declare the contract in order to avoid that nagging exception. Just open up your Package.appxmanifest file and declare your application as one that can interact with the search charm.

Signing the contract

If we start our application now and then press the search charm we will see our own little Øredev application, at the very top with the ugly icon, in the list for applications implementing the search contract. That’s basically all one need to know about contracts.

Contract implemented

Now we’re all set up to start coding. In App.xaml.cs, add the following code.

protected override void OnLaunched(LaunchActivatedEventArgs args)

private void ActivateSearchCharm()
    var pane = SearchPane.GetForCurrentView();
    pane.QuerySubmitted += QuerySubmitted;
    pane.SuggestionsRequested += SuggestionsRequested;
    pane.ResultSuggestionChosen += ResultSuggestionChosen;

protected override void OnSearchActivated(SearchActivatedEventArgs args)
    // the first page in a collection of many - just for testing
    ShowSplit(_sampleData.GroupedCollections.First(), args.QueryText);

What we get here is basically three different events and one override that you should handle in order to implement the search charm.

  • Event – QuerySubmitted
  • Event – SuggestionsRequested
  • Event – ResultSuggestionChosen
  • Override – OnSearchActivated

We start with the override of OnSearchActivated. This will trigger if our application is not in the foreground and you swipe out the right pane, press the search charm and then tap the application. In the screenshot below you can see what happened when I did just that. In this case I just show a plain view containing all the talks for the Agile track, naturally, one should navigate to something more suitable in a real application.

OnSearchActived done

We continue with the implementation of QuerySubmitted. This event will fire when the user enters a query and then press enter. I to remind any and all that this code is only intended to make my example work, I would not implement any real search functionality this way.

private void QuerySubmitted(SearchPane sender, SearchPaneQuerySubmittedEventArgs args)
    var items = page.Items as SampleDataCollection;
    page.Items = items.OfType<SampleDataItem>()
                      .Where(a => a.Description.Contains(args.QueryText));

Right, so we pick out all the items bound to the page. Then we pick out any item that has a description that contains the query string. To test my code I simply entered “someone” and tapped enter.

My very first query

As you can see, all other sessions, not containing the word “someone” are removed, only showing the session that match the search criteria.

This was basically all that I expected from the search charm. But there’s actually one more thing to the it that can really make your application shine. The secret sauce? SuggestionsRequested and ResultSuggestionChosen.

private void SuggestionsRequested(SearchPane sender, SearchPaneSuggestionsRequestedEventArgs args)
    var suggestions = args.Request.SearchSuggestionCollection;
    var items = page.Items
                    .Where(i => i.Category.StartsWith(args.QueryText, StringComparison.OrdinalIgnoreCase));

    foreach (var item in items)

                    StreamReference.CreateFromUri(new Uri(item.ImagePath)),

private void ResultSuggestionChosen(SearchPane sender, SearchPaneResultSuggestionChosenEventArgs args)
    var items = page.Items as SampleDataCollection;
    page.Items = items.OfType<SampleDataItem>()
                      .Where(a => a.Title == args.Tag));

So, this is what happens. When the user start to write in the search field, SuggestionsRequested is called, once called we can find any partial matches for the query string. In my case I match against everything that is the start of Category. Then I add those results to the search charm with AppendResultSuggestion(string text, string detailText, string tag, StreamReference image, string imageAlternateText). This will give us this very neat behavior.


If the user starts writing a word we can send suggested items to the search charm. If the user taps on one of them it will trigger ResultSuggestionChosen where we will get the Tag for the selected item allowing us to display it. Also notice that “Joha” gets highlighted in the suggestion list; this is done automagically by Windows 8.


Personally – I’m very excited about this. Charms really take one step closer to really erase the borders between the OS and your application. Much like what Microsoft has done with Windows Phone. I believe that this is the right way to go and I look forward to see it evolve.

But – there’s always a but. Don’t implement it if your application doesn’t have the need for it. It can be pretty annoying to have several applications taking up space in the search pane without having any real reason for doing so.

This Post Has 3 Comments

  1. Bình Vũ Thanh

    Hi Peter,
    I wondering if I can change the title of the search panel from Search Øredev to Øredev Search :)?
    I tried to find a property to do that but it come out with nothing.

  2. nupcypecrop

    My brother want to become a pixel editor. Is it a good job?

Leave a Reply