Implementing a VirtualizingPanel part 2: IItemContainerGenerator
In part 1 of this series of posts, I gave an overview of how to write a VirtualizingPanel. One of the keys to the implementation is understanding IItemContainerGenerator. I personally found it a bit nonintuitive to begin with. IItemContainerGenerator will not only help us generate (realize) and destroy (virtualize) the items, but we'll also use it to track the mapping of child indices to item indices through the GeneratorPosition.
The easiest way to see how this works is to step through an example of using it. For this example, I created a simple Avalon application that had an ItemsControl bound to 5 integers and used a custom VirtualizingPanel subclass as the ItemsPanelTemplate for the ItemsControl. Then, I inserted some test code into MeasureOverride.
Before we can use the generator, we must access the InternalChildren property as follows. Until you do, the generator is null. This is a bug, that will hopefully be fixed before long.
UIElementCollection children = base.InternalChildren;
Next, let’s look at the state of the generator using a utility function. The function demonstrates the use of GeneratorPositionFromIndex. This function takes a item index, not a child index. So, in our test case, we always expect there to be 5 iterations through this loop, no matter how many children we have created.
private void DumpGeneratorContent()
{
IItemContainerGenerator generator = this.ItemContainerGenerator;
ItemsControl itemsControl = ItemsControl.GetItemsOwner(this);
Console.WriteLine("Generator positions:");
for (int i = 0; i < itemsControl.Items.Count; i++)
{
GeneratorPosition position = generator.GeneratorPositionFromIndex(i);
Console.WriteLine("Item index=" + i + ", Generator position: index=" + position.Index + ", offset=" + position.Offset);
}
Console.WriteLine();
}
The result in the initial state is as follows. There are no realized items yet – they are all virtualized.
Generator positions:
Item index=0, Generator position: index=-1, offset=1
Item index=1, Generator position: index=-1, offset=2
Item index=2, Generator position: index=-1, offset=3
Item index=3, Generator position: index=-1, offset=4
Item index=4, Generator position: index=-1, offset=5
Next, let’s realize the first item:
Console.WriteLine("Realizing the first item...");
IItemContainerGenerator generator = this.ItemContainerGenerator;
bool isNewlyRealized;
GeneratorPosition position = generator.GeneratorPositionFromIndex(0);
using (generator.StartAt(position, GeneratorDirection.Forward, true))
{
DependencyObject child = generator.GenerateNext(out isNewlyRealized);
Console.WriteLine("isNewlyRealized = " + isNewlyRealized);
generator.PrepareItemContainer(child);
}
DumpGeneratorContent();
First, we map the item index to a GeneratorPosition. Before you can use it, you need to use the StartAt function to tell it where to start generating. StartAt is an IDisposable, so putting it inside a using is the most convenient way to set up a range of code that does the iteration. We tell it to start at our generator position and to go forward. The last parameter is allowStartAtRealizedItem and says whether StartAt will throw an exception if the item at the position has already been realized. In this case, none of the items are realized, so it doesn’t matter.
GenerateNext() is what actually creates the child. It has an output parameter which will tell you if the child is new, or if it had been previously realized. Finally, if the child is new, you must call PrepareItemContainer() to set up the UI. To be honest, I’m not sure why this is necessary. It seems like GenerateNext could do this for you.
The results are:
Realizing the first item...
isNewlyRealized = True
Generator positions:
Item index=0, Generator position: index=0, offset=0
Item index=1, Generator position: index=0, offset=1
Item index=2, Generator position: index=0, offset=2
Item index=3, Generator position: index=0, offset=3
Item index=4, Generator position: index=0, offset=4
Note that the one we just realized has index 0 and offset 0, the items that are still virtualized have non-zero offsets.
If you were to repeat this same code, you’d get isNewlyRealized = true. If you had passed false in as the final parameter to StartAt, it would throw an exception when you called GenerateNext because is has been previously realized.
If you were to then realize the 3rd item using the following code. Remember that GeneratorPositionFromIndex is an item index, so index=2 is the 3rd item.
position = generator.GeneratorPositionFromIndex(2);
using (generator.StartAt(position, GeneratorDirection.Forward, true))
{
DependencyObject child = generator.GenerateNext(out isNewlyRealized);
Console.WriteLine("isNewlyRealized = " + isNewlyRealized);
generator.PrepareItemContainer(child);
}
DumpGeneratorContent();
The results are as follows:
Realizing the third item...
isNewlyRealized = True
Generator positions:
Item index=0, Generator position: index=0, offset=0
Item index=1, Generator position: index=0, offset=1
Item index=2, Generator position: index=1, offset=0
Item index=3, Generator position: index=1, offset=1
Item index=4, Generator position: index=1, offset=2
You can see that the GeneratorPosition for item 2 now has index=1 and offset=0. Conveniently, if we keep the children sorted by item index, the generator positions correspond to the child indices.
You can revirtualize an item with code like the following:
Console.WriteLine("Virtualizng the first item...");
position = generator.GeneratorPositionFromIndex(0);
generator.Remove(position, 1);
DumpGeneratorContent();
We map the item index to a GeneratorPosition and then tell it to remove 1 item starting at that position. If you tell it to remove multiple items, they must be contiguous realized items that you remove. The results are as follows:
Virtualizng the first item...
Generator positions:
Item index=0, Generator position: index=-1, offset=1
Item index=1, Generator position: index=-1, offset=2
Item index=2, Generator position: index=0, offset=0
Item index=3, Generator position: index=0, offset=1
Item index=4, Generator position: index=0, offset=2
The GeneratorPosition for item index 2 has now shifted down to 1.
In summary:
· Realized items will have a GeneratorPosition of (index = child index, offset = 0)
· Virtualized items will have a GeneratorPosition with a non-zero offset
In the next post I’ll walk through the implementation of a VirtualizingPanel’s MeasureOverride to realize and virtualize the child UI. I’ll also talk about what happens when the item collection changes.
Comments
- Anonymous
February 13, 2006
Displaying large sets of data can be challenging to do performantly. If you have a scrolling list of... - Anonymous
February 13, 2006
Hi Dan,
thanks for the very good post about virtualizing panels. Maybe your next post will
light IItemsContainerGenerator more up but the coherence of its index and offset when
items get realized are not 100% clear to me. I understand that the index is growing
proportional to the amount of generated items and that virtualized items will have a non-zero
offsets but what does this offset tells me exactly? Does it show me that if I have index=x and offset=2
that this is a non realized item 2 neighbours forward from the x-realized one?
Thanks for your help
Chris - Anonymous
February 14, 2006
Hopefully my next post will clear it up. I don't know of a case where you actually care what the absolute value of the index is, just whether or not it's zero. - Anonymous
February 14, 2006
Now that we understand how IItemContainerGenerator works, I’m going to walk through some of the details... - Anonymous
February 15, 2006
Our friends from Max have been
busy.
Not only are they cranking away at a beautiful WinFX app, but... - Anonymous
July 25, 2006
Control Licensing in Cider (WPF designer for VS)
James provides some
great
information on supporting... - Anonymous
January 06, 2007
Now that we understand how IItemContainerGenerator works, I’m going to walk through some of the details