Virtualizing Wrap Panel

Use it as the ItemsPanel of a ListBox – or any items control whose template has a ScrollViewer with content scrolling on – wherever a long list reads better as tiles than as rows: photo galleries, product catalogues, file browsers, dashboards of cards.

How it virtualises

The panel is its own scroll owner (IScrollInfo). On each measure it works out from the offset and the viewport which items are in view, has containers created for those alone, and keeps or removes the ones that have left the view as VirtualizationSchemeOption says. Everything else exists only as data, in ItemsControl.ItemsSource.

Two layouts

By default each item gets a cell of ItemDimension, which you must set. A line holds as many cells as fit (see ItemPositioningMode) and an item's place is arithmetic on its index, so a jump to any item is cheap. With IsVariableItemSizeEnabled or IsDataSourceGrouped, a flow layout gives each item its own measured size instead.

Scrolling and grouping

Orientation gives rows that scroll down (the default) or columns that scroll across, a line – one item – at a time; ScrollToTheDesiredChild takes the user to any item. For groups, bind the items control to a VirtualizingCollectionView, which presents each group's header as a row of the flat list, and set IsDataSourceGrouped: the headers are laid out as GroupVirtualizationMode says and virtualised with the items.

Things to know

• Set the margin through RendertimeMargin, which the panel copies to its Margin when loaded.
• It needs a bounded viewport. Inside a StackPanel, or any parent that measures with unlimited space along the scrolling direction, there is nothing to virtualise against (see IsDynamicConstructionCapabilityEnabled).
• The items control creates the panel from its ItemsPanelTemplate: wire its events there and keep a reference from its Loaded event (see ScrollToTheDesiredChild).

A product catalogue as 180 by 140 tiles; Products holds objects with Name and Price.

<ListBox xmlns:vwp="clr-namespace:Binarymission.WPF.Controls.Panels;assembly=Binarymission.WPF.Controls.VirtualizingWrapPanel"
         ItemsSource="{Binding Products}">
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <vwp:BinaryVirtualizingWrapPanel ItemDimension="180,140" ItemPositioningMode="Safe" />
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>
    <ListBox.ItemTemplate>
        <DataTemplate>
            <StackPanel Margin="8">
                <TextBlock Text="{Binding Name}" FontWeight="SemiBold" TextTrimming="CharacterEllipsis" />
                <TextBlock Text="{Binding Price, StringFormat=C}" />
            </StackPanel>
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>