Windows 8.1: Search Contracts and Search Boxes

One of the more obvious changes around Windows 8.1 is the change to the way in which search is handled. In Windows 8.0, the search charm presented a UI where I could search my local system (e.g. for apps, files, settings) or I could take a search term and pick a particular app and I could have that app handle the search term.

For instance – if I wanted to search the web, I’d hit the Search charm, type a term and then click Internet Explorer to ask IE to do whatever it did to search for that term. In IE’s case it would do a web search but equally I could type a term like “London to Manchester” into the charm and pass it to the SkyScanner app which would then go off and find me flights from London to Manchester.

Only apps that implemented the Windows 8.0 search contract were listed as possibilities for handling searches and the user had the control to switch off specific apps so that they never showed up in the search charm.

If I was already inside of an app that implemented the search contract (e.g. the maps app) then using the charm would, by default, cause the search to happen inside of that app although as a user I could always choose to “send” the search term to a different app.

This all changes in Windows 8.1 as detailed up in the blog post on the Windows blog quite a few months ago now and there’s more detail on the UX changes with the general guidance being that search becomes part of an application’s UI rather than residing on the search charm.

Beyond that there are more complete “Guidelines for Search” again on the Dev Center.

As an example, if I search for “richard thompson”;


then the first thing is that I’m getting web provided hints as to what I might be trying to search for but also I can only choose between;


Everywhere/Settings/Files/Web Images/Web Videos. I can’t “send” this search term into a specific application. If I let the search stay with the default “everywhere” then I get a pretty impressive set of results back;


which includes all kinds of goodness powered by Bing so this “experience” becomes the way in which I can web search for pretty much anything and get back a whole bunch of results.

If I’m in an application though, how do I search? The first thing to say is that existing applications 8.0 like Sky News (purely as an example) implement the search contract and so still need to be searchable. The system copes with that by offering an additional option when it comes to choosing where I want to search;


and a quick update to an app like this would be to add a button which will invoke the search pane programmatically so that the app has some visible UI of its own which invokes the search pane in order that a user doesn’t have to know how to do what’s being shown in that screenshot above.

If I choose a few applications that have been updated for Windows 8.1 it’s interesting to see where search has gone in their UI. For instance, the Maps app has a search button in the bottom right hand corner and that’s mentioned in that Dev Center guidance;


The News app has a search box in the top right of the screen and that box stays there regardless of me scrolling the screen;


the Weather app has similar;


and travel, sport, health and fitness all have the same approach as does the reading list app.

In terms of building search into an app, when I was travelling around talking to developers about building for Windows 8.0 I tended to use my “flickR Photos” example to show a bunch of features including search. That example’s still on the site in both .NET technologies and in HTML/JS technologies but it’s now a little out of date with respect to Windows 8.1.

In that example, I sketched out a simple GridView-based UI and then populated it with a few photographs obtained by searching flickR online  in response to interaction from the Windows 8.0 search charm.

I had a couple of code snippets that made this easier for me to show without typing “lots” of code and those snippets looked something like this;

      // Get the search pane.
      SearchPane searchPane = SearchPane.GetForCurrentView();

      // Handle its "SuggestionsRequested" event by making an async HTTP call to flickR
      // asking them what's "hot" on flickR right now that matches whatever the user
      // has typed in so far.
      searchPane.SuggestionsRequested += async (s, e) =>
          var deferral = e.Request.GetDeferral();

          var flickrHotTags = await FlickrSearcher.GetHotlistTagsAsync(e.QueryText);



      searchPane.QuerySubmitted += async (s, e) =>
          // Go search flickR for photos that match whatever the user has submitted.
          var results = await FlickrSearcher.SearchAsync(e.QueryText);

          // Put the results into the UI.


and that was pretty much it (with the UI taken out of the equation) in terms of what I needed to implement in order to get the basics of search implemented (there is more that we could do like, e.g., also dealing with Result Suggestions alongside trying to deal with Query Suggestions).

For Windows 8.1, even though this was a pretty simple implementation it was trivially easy to move it across from implementing the search contract to making use of the new SearchBox control (there’s an HTML/JS equivalent of this);


I’m not sure whether the API I use at flickR for getting “hot search tags” works very well (or whether I use it correctly) as it often seems to return similar results. Nonetheless you can perhaps see that this control is providing query suggestions;


and it also is tracking history for me in that having search once before for “stratocaster” if I start to type “strat” then the control prompts me;


In terms of that “UI” above, I have pretty much a GridView and a SearchBox;


and there’s a few interesting properties on that SeachBox;

  • SearchHistoryEnabled – fairly obvious.
  • SearchHistoryContext – you don’t have to set this but it enables the system to store/differentiate the history that it’s maintaining if you have multiple search boxes (with different scopes) in your app.
  • PlaceholderText – there’s a section on using this in the guidance I referred to previously.
  • FocusOnKeyboardInput – again, there’s a section in the guidance but, essentially, this is making sure that (given my UI is blank here apart from a searchbox) focus goes straight to the SearchBox as soon as the user types regular characters into the keyboard rather than having to manually set focus on the SearchBox.

and then the QuerySubmitted and SuggestionsRequested events are so similar (by design) to the ones from the search contract that the code I have which handles them looks exactly like the code I wrote for Windows 8.0;

    async void SearchFlickr(string searchText)
      var searchResults = await FlickrSearcher.SearchAsync(searchText);
      this.gridView.DataContext = searchResults;

    async void OnSuggestionsRequested(SearchBox sender, 
      SearchBoxSuggestionsRequestedEventArgs args)
      var deferral = args.Request.GetDeferral();

      var querySuggestions = await FlickrSearcher.GetHotlistTagsAsync(



which makes it very easy to migrate once you’ve figured out how to use/position SearchBox in your UI.

The only other thing that occurred to me around the SearchBox was that a number of the built-in apps seem to do an “expando” SearchBox. For instance, the Finance app has;


but if I tap on that button I see;


I was wondering whether this was some “automatic” capability of the SearchBox or whether it’s initially just a button which then shows the SearchBox when it’s clicked on.

I had a look around the template of the XAML control and didn’t quite answer my question so my “guess” at the moment is that these apps are displaying a button which then unhides a SearchBox control but I’ll update this post if I figure out that it’s being done differently.