Dan Crevier's Blog : VirtualizingTilePanel

Implementing a VirtualizingPanel part 4: the goods!

dancre — Fri, 17 Feb 2006 08:00:00 GMT

Ok, we finally get to a full implementation with this post. I’ll be showing the implementation of a VirtualizingTilePanel. This is a layout is very similar to the one I used for the layout animation sample. For the sample, I’ve created a small test harness that lets you play with it. Here’s a screenshot of what it looks like:

This harness lets you insert and delete items so you can make sure that works and step through the code to see how it works.

When implementing a panel like this, you have a couple of options on the scrolling behavior. You can scroll by pixels, or scroll by items. VirtualizingStackPanel (the default for ListBox) scrolls by item so the top of the view will always be at top of an item. The views in Max do pixel based scrolling. One advantage to item based scrolling is that you can support variable sized items without having to do really complex approximations to handle scroll positions. Pixel based scrolling is only easy if you have fixed sized children. For this panel, I’m using pixel based scrolling. If there is interest, I can write about how item based scrolling will work. The panel chooses the children per row based on the width and grows vertically.

I’m not going to write much on the test harness implementation, unless there are questions. Basically it just creates an ObservableCollection<string> and sets it as the ItemSource for an ItemsControl that uses VirtualizingTilePanel. It uses the ObservableCollection APIs to insert and remove items. When creating new items, it uses increasing numbers so you can tell where the new ones are.

I divided the VirtualizingTilePanel implementation into 3 parts:

First is the IScrollInfo implementation. I basically just grabbed the code from Ben’s latest posts on IScrollInfo. He hasn’t done his last post yet, so it doesn’t preserve the position properly on a resize, and it doesn’t implement MakeVisible. One addition I had to make was to call InvalidateMeasure when scrolling to force new items to be realized. I only support vertical scrolling.

Second is the layout specific information. I tried to encapsulate this so that if you are doing a panel that’s similar enough, you can just replace this logic with yours. Creating a base class with the common logic and abstract classes for the layout stuff would also be a natural next step.

Finally, there’s the VirtualizingPanel specific stuff. I went over the MeasureCore and CleanUpItems logic in the previous post, but there are a couple of new pieces here. Here’s the ArrangeOverride implementation:

protected override Size ArrangeOverride(Size finalSize)

{

IItemContainerGenerator generator = this.ItemContainerGenerator;

UpdateScrollInfo(finalSize);

for (int i = 0; i < this.Children.Count; i++)

{

UIElement child = this.Children[i];

// Map the child offset to an item offset

int itemIndex = generator.IndexFromGeneratorPosition(new GeneratorPosition(i, 0));

ArrangeChild(itemIndex, child, finalSize);

}

return finalSize;

}

The only interesting thing here is the line that converts a child index to an item index. We need this to figure out where to put a child.

And, there’s the code that deals with items being removed:

protected override void OnItemsChanged(object sender, ItemsChangedEventArgs args)

{

switch (args.Action)

{

case NotifyCollectionChangedAction.Remove:

case NotifyCollectionChangedAction.Replace:

case NotifyCollectionChangedAction.Move:

RemoveInternalChildRange(args.Position.Index, args.ItemUICount);

break;

}

This removes realized children when the corresponding data items are removed. I have to be honest that I’m not sure this implementation works in all cases. ObservableCollection<> only supports removing single items, so I haven’t tested he more complex cases that can happen.

The code can be found at http://www.boingo.org/samples/VirtualizingTilePanelSample.zip. It works with the December/January CTP.

I’m hoping to hear some good feedback on this! Let me know what you think and if you have questions.

Implementing a VirtualizingPanel part 3: MeasureCore

dancre — Wed, 15 Feb 2006 09:11:00 GMT

Now that we understand how IItemContainerGenerator works, I’m going to walk through some of the details of how your virtualizing panel’s MeasureOverride should work. I think the easiest way to see how it all works is to just look at some code. In the code below, I’ve excluded the code in MeasureOverride that implements the IScrollInfo stuff. I’m also excluding all of the layout specific code. Basically, it will have to figure out the range of items that are visible based on the scroll position.

protected override Size MeasureOverride(Size constraint)

{

// Do work for IScrollInfo implementation

// Figure out range that's visible based on layout algorithm

int firstVisibleItemIndex = 0;

int lastVisibleItemIndex = 0;

IItemContainerGenerator generator = this.ItemContainerGenerator;

// Get the generator position of the first visible data item

GeneratorPosition startPos = generator.GeneratorPositionFromIndex(firstVisibleItemIndex);

// Get index where we'd insert the child for this position. If the item is realized

// (position.Offset == 0), it's just position.Index, otherwise we have to add one to

// insert after the corresponding child

childIndex = (position.Offset == 0) ? position.Index : position.Index + 1;

using (generator.StartAt(startPos, GeneratorDirection.Forward, true))

{

for (int itemIndex = firstVisibleItemIndex; itemIndex <= lastVisibleItemIndex; ++itemIndex, ++childIndex)

{

bool newlyRealized;

// Get or create the child

UIElement child = generator.GenerateNext(out newlyRealized) as UIElement;

if (newlyRealized)

{

// Figure out if we need to insert the child at the end or somewhere in the middle

if (childIndex >= children.Count)

{

base.AddInternalChild(child);

}

else

{

base.InsertInternalChild(childIndex, child);

}

generator.PrepareItemContainer(child);

}

else

{

// The child has already been created, let's be sure it's in the right spot

Debug.Assert(child == children[childIndex], "Wrong child was generated");

}

// Measurements will depend on layout algorithm

child.Measure(new Size(itemWidth, itemHeight));

}

// Note: this could be deferred to idle time for efficiency

CleanUpItems(firstVisibleIndex, lastVisibleIndex);

return desiredSize;

}

private void CleanUpItems(int firstVisibleItemIndex, int lastVisibleItemIndex)

{

UIElementCollection children = this.InternalChildren;

IItemContainerGenerator generator = this.ItemContainerGenerator;

for (int i = children.Count-1; i >= 0; i--)

{

// Map a child index to an item index by going through a generator position

GeneratorPosition childGeneratorPos = new GeneratorPosition(i, 0);

int itemIndex = generator.IndexFromGeneratorPosition(childGeneratorPos);

if (itemIndex < firstVisibleItemIndex || itemIndex > lastVisibleItemIndex)

{

generator.Remove(childGeneratorPos, 1);

RemoveInternalChildRange(i, 1);

}

That’s it! There’s not actually that much virtualization specific code. The loop in MeasureCore will generate any missing children, and then measure children whether they are new or were already there. The cleanup code removes all UI that’s no longer visible. There are lots of opportunities for optimization here. You can defer the cleanup to idle time to keep it from slowing down layout. You can also keep extra items around in case they may come into view again. Also, it’s more efficient to remove children in batches, so the code could be improved to batch them up.

Let’s walk through a hypothetical case. Say you have a view that can display 10 items at a time. I hope these aren’t too hard to follow. It might be easier to step through the complete code I post in a future post if this is too hard to follow.

When you first display the panel, firstVisibleItemIndex will be 0 and lastVisibleItemIndex will be 9. The childIndex will be 0. It will loop through creating and measuring 10 children, inserting each one at the end. The cleanup code will walk through the children and see their item indices are in the range 0-9, so it won’t remove them.

Now, say you scroll it down a bit so items 2-11 are visible. The loop in measure core will find startPosition to be index=2, offset=0. This will be mapped to child index 2. Newly realized will be false for the first 7 items, but then it will start creating new items and adding them at the end. In cleanup items, it loops through the children backwards. The last 10 children will all be in the visible range, but then it will hit children that are out of range and remove them one at a time.

If the item collection was modified so that an item was added at index 8, this would cause a remeasure to happen. The IItemContainerGenerator is going to know about the new item, so when we iterate through the positions, it will create a new item and we’ll insert it at the right location.

But, what happens when you remove an item from the collection? We’ll get measure called again and the IItemContainerGenerator will be updated, but we’ll have this extra child that’s no longer in the generator. This is a problem! The solution to this is to override OnItemsChanged and update things immediately. I’ll include the full code for this in my next post.

Coming next is an implementation of a VirtualizingTilePanel that puts this all together.

Implementing a VirtualizingPanel part 2: IItemContainerGenerator

dancre — Tue, 14 Feb 2006 07:37:00 GMT

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 3^rd item using the following code. Remember that GeneratorPositionFromIndex is an item index, so index=2 is the 3^rd 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.

Implementing a virtualized panel in WPF (Avalon)

dancre — Tue, 07 Feb 2006 07:31:00 GMT

Displaying large sets of data can be challenging to do performantly. If you have a scrolling list of data, one technique to improve performance is to only create the UI elements that are visible. This is refered to as UI virtualization (as opposed to data virtualization, which is the technique of not materializing the data that isn’t visible). WPF has a built in virtualizing panel called VirtualizingStackPanel that supports UI virtualization and lays out its children like StackPanel. ListBox uses this panel by default. However, if you want to lay out your children differently, you need to write your own Panel that supports virtualization. WPF has a VirtualizingPanel class you can descend from to do this, but it’s still a fair amount of work. I’ll describe how to write your own virtualizing panel in this series of posts.

The basic approach is as follows:

· In your Panel’s MeasureCore, you need to figure out which range of data items are visible. Then, you generate the UI for any of the visible data items that haven’t previously been generated. This is referred to as realizing the UI for these items. Finally, you destroy the UI for any data items that are no longer visible. This is referred to as revirtualizing the item. The revirtualization can actually be deferred until idle time for better performance.

· In your Panel’s ArrangeCore, you simply arrange the UI elements that are visible to the appropriate locations.

Sounds simple, right? Well, there are a couple of complications.

The first complication is that your MeasureCore needs to know how much is visible. If you just subclass VirtualizingPanel and put your panel in an ItemsControl, you’ll find that you get measured with infinite constraints and you can’t really tell what is visible. While it might be possible to jump through some hoops to figure out what’s visible, the right way to do this is to implement IScrollInfo. Ben Constable has an excellent series of posts about IScrollInfo, so I won’t be writing much about that implementation here. Once you’ve implemented IScrollInfo, your MeasureCore will be called with the visible region as the constraints.

The second complication is that you need to generate the UI elements in the proper way that takes WPF’s data model into account (finding the proper DataTemplate, etc). Beatriz Costa has an excellent blog on dealing with data in Avalon/WPF. VirtualizingPanel exposes an object that implements IItemContainerGenerator which lets you properly generate the UI for elements.

And, the last complication is that you need to do the book keeping to keep track of which UI elements correspond to which data items. The IItemContainerGenerator helps you do this book keeping if you keep the child UI elements in the same order as the data items (which is a natural thing to do). VirtualizingPanel exposes methods to insert/add/remove the child UI elements.

In part 2, I’ll dig into the IItemContainerGenerator and explain how it is used to generate the child UI elements and how it can be used to map data items to UI elements.

Tutorial on IScrollInfo

dancre — Sat, 07 Jan 2006 19:42:00 GMT

Ben Constable, our l33t Max guy, is writing up a nice tutorial on how to use IScrollInfo for those times when you need full control of your scrolling view in Avalon. Parts 1 and 2 are up so far.