Windows 8, Windows Phone, Silverlight: Files APIs

Showing posts with label Files APIs. Show all posts

Sunday, March 18, 2012

File searching and filtering

In my last post, I discussed accessing and displaying file data from your Metro app, and grouping files using the pivot API. Let me follow up on that with a discussion of basic file filtering using the search API. So in our photo browser app, suppose we’d like the user filter photos by their own rating. In the Windows OS, the user can right click on a picture and set a personal rating using the Rating property :

This is the property that we’re going to use for our filtering example. So we’ll assume the user has at least some pictures rated using the above property settings in her file system.
Here’s what we want to achieve :

The buttons in the top row match each distinct rating value the user has assigned to her pics. So we need to generate these buttons. Then, when the user clicks one of them, the list will refresh to only show pics matching the selected rating value.
Let’s start with the buttons :

private async void CreateRatingButtons()
{
    var pivot = CommonFolderQuery.GroupByRating;
    var folders = await library.GetFoldersAsync(pivot);
  
    var ratingValues = folders.Cast<StorageFolder>().Select(
        f => new Rating { Name = f.Name }).OrderBy(r => r.Name);
    Ratings = new ObservableCollection<Rating>(ratingValues);
    DefaultViewModel["Ratings"] = Ratings;
}

You can see our old friend the pivot, which we first use to group the files by rating. As in the previous post, we generate a list of virtual folders, each representing a group of pictures matching a specific rating value. Then we just retrieve the vfolder name which is the rating value itself. At this point, our goal is just to get the list of rating values assigned by the user in her file system. We store them in a simple data model class in an observable collection to make data binding easier. Then we bind an items control to the collection to generate the list of buttons :

<ItemsControl x:Name="icRatings"
              ItemsSource="{Binding Ratings}">
    <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
            <StackPanel Orientation="Horizontal" />
        </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
    <ItemsControl.ItemTemplate>
        <DataTemplate>
            <Button Name="btnFilter" 
                    Content="{Binding Name}"
                    Click="btnFilter_Click" />
        </DataTemplate>
    </ItemsControl.ItemTemplate>
</ItemsControl>

So the ItemsControl is bound to the Ratings list (here through the DefaultViewModel property for convenience, but you could just set icRatings’s ItemsSource to Ratings in code if you so prefer). That takes care of creating our filter buttons.

Next, what happens when a button is clicked ? Well, here’s the workhorse method :

private async Task GetFilesAsync(StorageFolder rootFolder, string search = "")
{
    var options = new QueryOptions { FolderDepth = FolderDepth.Deep };
    options.ApplicationSearchFilter = search;
  
  
    var result = rootFolder.CreateFileQueryWithOptions(options);
    var files = await result.GetFilesAsync();
  
    foreach (var file in files)
    {
        var myFile = new MyFile { FileName = file.Name };
  
        myFile.Thumbnail = await file.GetThumbnailAsync(ThumbnailMode.PicturesView, 200);
  
        var props = await file.Properties.RetrievePropertiesAsync(new List<string> { "System.RatingText", "System.Title" });
        var title = props["System.Title"];
        var ratingText = props["System.RatingText"];
        myFile.Title = title != null ? title.ToString() : string.Empty;
        myFile.RatingText = ratingText != null ? ratingText.ToString() : string.Empty;
  
        myFiles.Add(myFile);
    }
}

I start by creating a QueryOptions instance, and set its ApplicationSearchFilter to the filter criterion we’re interested in. In this case, search should be set in the button click handler :

private async void btnFilter_Click(object sender, RoutedEventArgs e)
{
    myFiles.Clear();
    
    var rating = (sender as Button).DataContext as Rating;
    if (rating != null)
    {
        ...
        await GetFilesAsync(library, "System.Rating:" + ratingText);
    }
}

Note that I also set FolderDepth to Deep so as to specify a deep search. As we’ve seen before, I then create the query and start the async operation to retrieve the files matching the passed in search criterion. Then I loop through the result files, and seek to retrieve the actual rating value for the file (although I already know it since it should match the search criterion) as well as the image title. This is to illustrate accessing file properties using the new set of interfaces in WinRT Consumer Prev. Notice I first access the file’s Properties value and call RetrievePropertiesAsync() on that object, passing to it a list of property names I need to retrieve. The property names to pass are very badly documented at this point, but after some digging I found they must conform to Windows’ Advanced Query Syntax (documented here). Here’s a list of Windows properties : http://msdn.microsoft.com/en-us/library/bb760685(VS.85).aspx

So anyway to make things short, the property we’re interested in is not System.Rating, which returns a number, but System.RatingText. So we retrieve that as well as Title, and we store the retrieved values in our MyFile data model object so we can bind to it in the UI. Here’s the updated version of MyFile :

public class MyFile : BindableBase
{
    public string FileName { get; set; }
  
    string title;
    public string Title 
    {
        get { return title; }
        set { SetProperty<string>(ref title, value); }
    }
  
    public StorageItemThumbnail Thumbnail { get; set; }
    public string RatingText { get; set; }
}

So hopefully, this has given you an idea of how you can implement searching/filtering on file data in your apps. I’ve used a simple example but you can obviously implement much more complex scenarios using these techniques.

Happy filtering…

Using files as your app data

In Windows 8, you can use your files as data for your app. Suppose you have a bunch of pics stored on your machine or on your network, for example. You can easily display them in your Metro app :

Here’s the basic method behind this UI :

private async Task GetFilesAsync(IStorageFolder rootFolder)
{
    myFiles.Clear();
  
    var files = await rootFolder.GetFilesAsync();
  
    foreach (var f in files)
    {
        var myFile = new MyFile { FileName = f.Name };
  
        myFile.Thumbnail = await (f as StorageFile).GetThumbnailAsync(
            ThumbnailMode.ListView, 100, ThumbnailOptions.ResizeThumbnail);
  
        myFiles.Add(myFile);
    }
}

It uses a data model file that looks something like this :

public class MyFile : BindableBase
{
    public string FileName { get; set; }
  
    string title;
    public string Title 
    {
        get { return title; }
        set { SetProperty<string>(ref title, value); }
    }
  
    public StorageItemThumbnail Thumbnail { get; set; }
}

A custom file class that stores the file name, title (set by the user on her pictures) and thumbnail to display. Note it extends BindableBase for convenience to easily implement INotifyPropertyChanged and raise UI notifications but simply calling SetMethod(), defined in BindableBase.

Also note the GetFilesAsync method asynchronously retrieves the thumbnail of each pic by calling GetThumbnailAsync. How easy is that ? Thanks winRT.

Now suppose you want to group the pics in some way. You can do it easily through the pivot API, which creates virtual folders that represent groups. Here’s another method :

private async Task GetVirtualFoldersAsync(StorageFolder rootFolder)
{
    myVirtualFolders.Clear();
  
    var pivot = CommonFolderQuery.GroupByMonth;
    var queryOptions = new QueryOptions(pivot);
  
    var queryResult = rootFolder.CreateFolderQueryWithOptions(queryOptions);
    var vFolders = await queryResult.GetFoldersAsync();
  
    foreach (StorageFolder vfolder in vFolders)
    { 
        var myFolder = new MyFolder { FolderName = vfolder.Name };
  
        var files = await vfolder.GetFilesAsync();
        myFolder.ImageCount = files.Count();
  
        myFolder.Thumbnail = await (vfolder as StorageFolder).GetThumbnailAsync(
            ThumbnailMode.ListView, 200, ThumbnailOptions.ResizeThumbnail);
  
        myVirtualFolders.Add(myFolder);
    }
}

What this method does is generate a list of virtual folders each matching a group of pics taken during a given month. The pivot is defined using the GroupByMonth query, which will result in the files being pivoted on using this criterion. We could have picked another pivot, such as CommonFolderQuery.GroupByAuthor for example.

Next we call CreateFolderQueryWithOptions(options) to actually create the pivoted query. This method is available on the StorageFolder passed into the method, for example Windows.Storage.KnownFolders.PicturesLibrary. Then we call GetFoldersAsync to actually dig and retrieve the files grouped by month.

Once the method completes, you can access the list of virtual folders representing the groups created. Here this is done in the foreach loop which loops over the virtual folders. My code then goes on to do app-specific stuff, such as retrieving the list of files in the group (vfolder) so as to display the count in the UI, and retrieve the vfolder’s thumbnail. Windows does that for you, it will generate a thumbnail for your folder or virtual folder, usually the thumbnail of the first pic in the folder. So you can call GetThumbnailAsync on a StorageFile OR a StorageFolder. Awesome.

Like before, I instantiate a custom class to store the vfolder data and store it in an observable collection so my UI can bind to it and get change notified. The UI then lists groups (vfolders), and I can add code so that when a Vfolder thumbnail is tapped, the list of actual pics in that vfolder gets displayed.

So you can see how easy it is to use files as app data and then implement simple pivots on that data. The beauty of this is the way we perform asynchronous operations, which would have previously made a hellish mess in our code, so smoothly and easily using async / await. Thanks to this new pattern the work we need to do to define and implement pivots on top of file resources in our data apps is almost fun!

Happy pivoting