Using the LibraryBar Control

The LibraryBar control that is included in the Microsoft Surface Toolkit for Windows Touch Beta is an ItemsControl object that enables you to list items horizontally, group items into several groups, and scroll groups. By default, the LibraryBar control supports drag-and-drop operations. For more information on using drag-and-drop operations with the LibraryBar control, see Using Drag-and-Drop with the LibraryBar and LibraryStack Controls.

LibraryBar - Close-up example

In the following code example, a LibraryBar control is created as part of a SurfaceWindow object. The DataTemplate for the LibraryBar control is set to show the images that are bound to the control.


<s:SurfaceWindow
    x:Class="LibraryBar.SurfaceWindow1"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:s="http://schemas.microsoft.com/surface/2008"
    Title="LibraryBar">

    <Grid>
        <s:LibraryBar Name="MainLibraryBar">
            <s:LibraryBar.ItemTemplate>
                <DataTemplate>
                    <Image Source="{Binding}"/>
                </DataTemplate>
            </s:LibraryBar.ItemTemplate>
        </s:LibraryBar>
    </Grid>

</s:SurfaceWindow>

In the code for SurfaceWindow, the OnInitialized method is overridden to set the ItemsSource property of the LibraryBar control to a collection of sample images.


protected override void OnInitialized(EventArgs e)
{
    base.OnInitialized(e);

    // Query the registry to find out where the sample photos are stored.
    const string shellKey =
        @"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\explorer\Shell Folders";

    string imagesPath =
        (string)Microsoft.Win32.Registry.GetValue(shellKey, "CommonPictures", null) + @"\Sample Pictures";

    try
    {
        // Get the list of files.
        string[] files = System.IO.Directory.GetFiles(imagesPath, "*.jpg");

        // Create an ObservableCollection from the file names.
        // LibraryBar.ItemsSource should implement INotifyCollectionChanged
        // in order for the built-in drag-and-drop capability to work properly.
        ObservableCollection<string> items = new ObservableCollection<string>(files);

        // Set the ItemsSource property.
        MainLibraryBar.ItemsSource = items;
    }
    catch (System.IO.DirectoryNotFoundException)
    {
        // Handle exception as needed.
    }
}
noteNote
The ObservableCollection type is in the System.Collections.ObjectModel namespace. You must add a using statement to the SurfaceWindow1.xaml.cs file for this namespace.


using System.Collections.ObjectModel;

Controlling the Number of Rows

By default, a LibraryBar control uses two rows to display the items. You can change the number of rows by setting the Rows property. The following illustration shows a LibraryBar control that uses a single row to display items.

LibraryBar - Rows set to 1

Enabling and Disabling Items

By default, the items in the LibraryBar control are enabled. When an item is enabled, it is displayed with normal opacity, and users can drag it from the control.

When an item is disabled, it appears dimmed and users cannot drag it from the control. By default, when users drag an item from LibraryBar, it remains in the control and becomes disabled.

You can set the state of an item by using the SetIsItemDataEnabled method. The following example disables the last item in the Items collection of the LibraryBar control.


int idx = MainLibraryBar.Items.Count - 1;
if (idx >= 0)
{
    MainLibraryBar.SetIsItemDataEnabled(MainLibraryBar.Items[idx], false);
}

Controlling the Grouping of Items

To group items in the LibraryBar control, add a PropertyGroupDescription object to the GroupDescriptions collection of the default collection view for the collection that is bound to the ItemsSource property. The following code example shows how to group items in this way.


protected override void OnInitialized(EventArgs e)
{
    base.OnInitialized(e);

    // Create an ObservableCollection, and add the items.
    // LibraryBar.ItemsSource should implement INotifyCollectionChanged
    // in order for the built-in drag-and-drop capability to work properly.
    ObservableCollection<DataThumbnail> items = new ObservableCollection<DataThumbnail>();

    items.Add(new DataThumbnail(@"Resources\Thumbnail-1.png", "Photo 1", "Group 1"));
    items.Add(new DataThumbnail(@"Resources\Thumbnail-2.png", "Photo 2", "Group 1"));
    items.Add(new DataThumbnail(@"Resources\Thumbnail-3.png", "Photo 3", "Group 1"));
    items.Add(new DataThumbnail(@"Resources\Thumbnail-4.png", "Photo 4", "Group 2"));
    items.Add(new DataThumbnail(@"Resources\Thumbnail-5.png", "Photo 5", "Group 2"));
    items.Add(new DataThumbnail(@"Resources\Thumbnail-6.png", "Photo 6", "Group 2"));
    items.Add(new DataThumbnail(@"Resources\Thumbnail-7.png", "Photo 7", "Group 3"));
    items.Add(new DataThumbnail(@"Resources\Thumbnail-8.png", "Photo 8", "Group 3"));

    MainLibraryBar.ItemsSource = items;
    // Get the default view and establish grouping.
    ICollectionView defaultView = CollectionViewSource.GetDefaultView(items);
    defaultView.GroupDescriptions.Add(new PropertyGroupDescription("GroupName"));
}

The PropertyGroupDescription object is associated with the GroupName property of the DataThumbnail class. The following code example shows how to implement this class.


/// <summary>
/// Represents an image thumbnail with an associated label and a group name.
/// </summary>
public class DataThumbnail
{
    private string label;
    private string fileName;
    private string groupName;
    private BitmapImage bitmap;

    /// <summary>
    /// Creates a new instance of the DataThumbnail class.
    /// </summary>
    /// <param name="fileName">The file name of the image.</param>
    /// <param name="label">The text associated with the image.</param>
    /// <param name="groupName">The group name for the image.</param>
    public DataThumbnail(string fileName, string label, string groupName)
    {
        // For simplicity, not checking for null parameters.
        this.fileName = fileName;
        this.label = label;
        this.groupName = groupName;
        this.bitmap = new BitmapImage(new Uri(fileName, UriKind.Relative));
    }

    /// <summary>
    /// Gets the label of this instance.
    /// </summary>
    public string Label
    {
        get { return label; }
    }

    /// <summary>
    /// Gets the group name of this instance.
    /// </summary>
    public string GroupName
    {
        get { return groupName; }
    }

    /// <summary>
    /// Gets the image used by this instance.
    /// </summary>
    public BitmapSource Bitmap
    {
        get { return bitmap; }
    }
}

In the following code example, the DataTemplate for the LibraryBar control is set to display the image and label that are assigned to each DataThumbnail object by binding to the Bitmap and Label properties, respectively.


<s:LibraryBar Name="MainLibraryBar" Rows="2">
    <s:LibraryBar.ItemTemplate>
        <DataTemplate>
            <Grid>
                <Image Source="{Binding Bitmap}"/>
                <Label FontSize="14" Content="{Binding Label}"/>
            </Grid>
        </DataTemplate>
    </s:LibraryBar.ItemTemplate>
</s:LibraryBar>

When you run the application, the images are assigned to the LibraryBar control in groups, as the following illustration shows.

LibraryBar - Grouping

See Also

Community Additions

Show: