Telerik UI for Windows Phone

VirtualizingDataCollection is a specialized collection used together with the RadDataBoundListBox control to implement the AutomaticDataVirtualizationMode. This collection implements some special features like support for caching downloaded data items, automatic download range calculation and dynamic resizing. This topic will cover these features and will provide some code samples to better explain them.

Note
VirtualizingDataCollection cannot be used as a standalone collection. It should always be used with the RadDataBoundListBox control in Automatic data virtualization mode.

Initializing a VirtualizingDataCollection

The constructor of the VirtualizingDataCollection accepts two parameters

  • count: the count of all data items that will be eventually downloaded
  • pageSize: the size of a single data item portion that will be downloaded upon a data request

The code snippet below shows how to initialize an instance of the VirtualizingDataCollection class:

CopyC#
VirtualizingDataCollection collection = new VirtualizingDataCollection(200, 10);

In this case the collection will create a cache for 200 items and will load them in portions of 10 items. Initially each cache slot for a single data item is initialized with an internal object which is used to differentiate between initialized slots and slots that have not been loaded yet.

Using with RadDataBoundListBox

To use VirtualizingDataCollection with a RadDataBoundListBox instance you should simply set the DataVirtualizationMode of the control to Automatic and set the collection as ItemsSource. You should also subscribe for the ItemsLoading event of the collection which will be fired each time a data portion has to be downloaded and loaded in the collection:

CopyC#
this.radDataBoundListBox.DataVirtualizationMode = DataVirtualizationMode.Automatic;
collection.ItemsLoading += this.OnVirtualizingDataCollectionItemsLoading;
this.radDataBoundListBox.ItemsSource = collection;

Handling the ItemsLoading event

The ItemsLoading event is fired each time the collection decides that a new portion of data items has to be loaded. The arguments passed to the handler contain information about the zero-based starting index of the data portion and the size of the portion (which is the size defined in the constructor of the VirtualizingDataCollection class):

CopyC#
private void OnVirtualizingDataCollectionItemsLoading(object sender, VirtualizingDataCollectionItemsLoadingEventArgs e)
{
...
int startIndex = e.StartIndex;
int count = e.Count;
this.LoadItems(startIndex, count);
...
}

In the most common scenario this is the point where data items have to be requested/downloaded. When the newly requested items are already available, you can use the LoadItems method of the VirtualizingDataCollection instance to load them.

Loading new data items

When a new portion of data items is ready to be loaded in the VirtualizingDataCollection you can use the LoadItems method of the collection to do this:

CopyC#
private void OnDataItemsDelivered(object sender, EventArgs e)
{
//Here the start index is the location where items will be loaded into the VirtualizingDataCollection.
The sessionsSource is a collection containing the new data items.
collection.LoadItems(startIndex, this.sessionsSource);
}

By calling the LoadItems method with a given startIndex, the VirtualizingDataCollection will automatically calculate the cache range to which the loaded data belongs and will fill its slots with the provided collection. It is recommended to provide the starting index used when requesting the corresponding data items, i.e. ItemsLoading event triggered data requests should be mapped to a corresponding LoadItems calls.

Changing the VirtualizingDataCollection's count dynamically

There are cases in which the developer does not initially know the amount of data items that will be handled by the VirtualizingDataCollection instance. In such cases it is possible to initialize the collection with count equal to zero and in later moment resize the collection by setting its Count property.

Note
It is worth noting that setting the count property will trigger different actions according to the current state of the VirtualizingDataCollection instance. If the collection is already filled with some data and the new count is less than the already defined, the collection will be shrunk and the excessive data items at the end of the collection will be purged.