BinaryVirtualizingWrapPanel

Creates a panel that lays items out in rows and keeps every container it creates.

The items control normally creates it from an ItemsPanelTemplate; set ItemDimension before it is shown.

Gets or sets whether the panel refreshes the bound collection view whenever items are added, removed, moved or replaced.

Each change then does what Refresh does: refreshes the ICollectionView in ItemsControl.ItemsSource (nothing, when the source is not a collection view), measures again and scrolls back to the first item. For a list edited in batches, leave it off and call Refresh after the batch.

Gets or sets whether the panel may scroll horizontally.

While there is a scroll owner and this is false, SetHorizontalOffset is ignored. With no scroll owner, offsets are always applied.

Gets or sets whether the panel may scroll vertically.

While there is a scroll owner and this is false, SetVerticalOffset is ignored. See CanHorizontallyScroll.

Gets or sets the space between a group's header and its first line of items, when it is not a whole item's height.

Used when IsRenderItemDimensionHeightSpacingBetweenGroupHeaderAndDataItemRowEnabled is false, or when IsTrimExtraLinkbreakForLeadingRowWithOneChildEnabled applies.

Gets or sets the height of the blank line between the end of one group and the next group's header, in StandaloneLine mode.

Used with GroupVirtualizationMode set to StandaloneLine, ShouldRenderExtraLineBeforeHeader on and ShouldRenderItemHeightSpacingAfterAGroupHasBeenRendered off.

A value set while IsDataSourceGrouped is true and ShouldRenderItemHeightSpacingAfterAGroupHasBeenRendered is false is held to at most 80 per cent of the height of ItemDimension (or to 2, when that height is zero or less). Set ItemDimension first.

Gets or sets how the panel settles after a jump to DesiredChildIndexToScrollTo.

Despite its name, it does not follow the collection view's current item. After a jump the panel steps one line back, forward and back again so that the lines round the target are created. With this false, that happens only when no index, or index 0, is asked for; with it true, whenever the target is more than two lines from the end.

Gets or sets the index of the item the panel should bring into view – a jump straight to it, however far down the list it is.

Setting an index of zero or more scrolls so that the line holding that item is near the top of the viewport, creating only the items around it. The value stays set, and the panel keeps that item in view when its size changes. While it is -1, the panel sets it itself after the viewport is resized, to the item that was first in view, so that the user keeps their place. Setting the value it already has does nothing – call ScrollToTheDesiredChild to repeat a jump. An index at or past the end of the list does not move the view to a new place.

Jumping relies on the fixed-size layout, where an item's place follows from its index. With IsVariableItemSizeEnabled on, the panel cannot work out where the item is and does not take the user to it.

Keep the panel on the photo the view model has selected:

<vwp:BinaryVirtualizingWrapPanel ItemDimension="160,160"
                                 DesiredChildIndexToScrollTo="{Binding SelectedPhotoIndex}" />

Gets the height of all the content, shown or not – what the vertical scroll bar spans.

Gets the width of all the content, shown or not – what the horizontal scroll bar spans.

Gets or sets the height of a group header line – the size the header row's data template is drawn at.

Applies in the LineBreak and StandaloneLine modes, where the header is as wide as the line; laid out vertically, it is the header's height at the top of its column. In Continuation mode a header takes one item cell instead.

Gets or sets how a grouped source is laid out: each group's header in line with the items, or starting a line of its own, with or without a blank line before it.

Used while IsDataSourceGrouped is true.

• Continuation — A header takes one item cell, and the groups run on along the same lines.
• LineBreak — A header starts a line of its own, as long as the line and GroupHeaderItemCustomHeight high, and its items start on the next line. 8 units separate a group from the next header.
• StandaloneLine — As LineBreak, with a blank line before each header – see ShouldRenderExtraLineBeforeHeader.

Laid out vertically, a header heads its column instead, GroupHeaderItemCustomHeight tall. A change lays the panel out again from the first item.

Gets how far the content is scrolled to the right.

Gets or sets whether the panel plays PanelAnimationEffect as it scrolls a page or a wheel notch, and when it is laid out again.

The effect plays on PageUp, PageDown, PageLeft, PageRight, the mouse-wheel steps, LineLeft and LineRight, and when the panel is resized or refreshed – not on LineUp or LineDown, nor while the scroll bar's thumb is dragged.

<vwp:BinaryVirtualizingWrapPanel ItemDimension="180,140"
                                 IsAnimationEnabled="True"
                                 PanelAnimationEffect="BlurToNormal" />

Gets or sets whether the panel fades briefly out and in again when it jumps to an item.

ScrollToTheDesiredChild sets this for its own jump from its argument, and restores it.

Gets or sets whether the items control's source is a grouped VirtualizingCollectionView, so that the panel lays out group headers among the items.

A VirtualizingCollectionView with group descriptions presents each group's header as a row of its own, ahead of the group's items, whose data is the CollectionViewGroup – its Name and ItemCount are there to bind to. With this set, the panel uses the flow layout, starts each group as GroupVirtualizationMode says, and virtualises headers and items together. Bind to an ordinary grouped view instead and WPF generates a group item per group, which this panel cannot virtualise.

While grouped, VirtualizationSchemeOption is held at VirtualizationScheme.LightWeightCache, and jumping to an index (DesiredChildIndexToScrollTo, ScrollToTheDesiredChild) is not available. A change lays the panel out again from the first item.

A catalogue grouped by category. Two implicit data templates draw the rows: one for the header rows (a CollectionViewGroup) and one for the products.

<Window x:Class="Catalogue.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="clr-namespace:Catalogue"
        xmlns:vwp="clr-namespace:Binarymission.WPF.Controls.Panels;assembly=Binarymission.WPF.Controls.VirtualizingWrapPanel"
        Title="Catalogue" Width="960" Height="640">
    <ListBox x:Name="catalogue">
        <ListBox.Resources>
            <DataTemplate DataType="{x:Type CollectionViewGroup}">
                <TextBlock FontSize="16" FontWeight="Bold" VerticalAlignment="Center">
                    <Run Text="{Binding Name, Mode=OneWay}" />
                    (<Run Text="{Binding ItemCount, Mode=OneWay}" /> products)
                </TextBlock>
            </DataTemplate>
            <DataTemplate DataType="{x:Type local:Product}">
                <StackPanel Margin="8">
                    <TextBlock Text="{Binding Name}" FontWeight="SemiBold" TextTrimming="CharacterEllipsis" />
                    <TextBlock Text="{Binding Price, StringFormat=C}" />
                </StackPanel>
            </DataTemplate>
        </ListBox.Resources>
        <ListBox.ItemsPanel>
            <ItemsPanelTemplate>
                <vwp:BinaryVirtualizingWrapPanel ItemDimension="180,120"
                                                 IsDataSourceGrouped="True"
                                                 GroupVirtualizationMode="LineBreak"
                                                 GroupHeaderItemCustomHeight="32" />
            </ItemsPanelTemplate>
        </ListBox.ItemsPanel>
    </ListBox>
</Window>

using System.ComponentModel;
using System.Windows.Data;
using Binarymission.WPF.Data.DataExtensions;

// products is a List<Product>; Product has Name, Price and Category.
var view = new VirtualizingCollectionView(products);
view.SortDescriptions.Add(new SortDescription(nameof(Product.Category), ListSortDirection.Ascending));
view.GroupDescriptions.Add(new PropertyGroupDescription(nameof(Product.Category)));
catalogue.ItemsSource = view;

Gets or sets whether the panel uses the items control's actual size as its viewport when its parent measures it with unlimited space.

Measured with infinite width or height – inside a StackPanel, say – the panel has no viewport to virtualise against. With this on, it uses the items control's ActualWidth and ActualHeight instead, so give the items control a size of its own.

Gets or sets whether the panel adds ten units to every side of RendertimeMargin.

Applied when the panel is loaded, and at once when this changes, which also scrolls to the first item.

Gets or sets whether a whole item's height of space separates a group's header from its first line of items.

Applies in the LineBreak and StandaloneLine modes. When the lines are too short for two items and IsTrimExtraLinkbreakForLeadingRowWithOneChildEnabled is set, the smaller custom spacing is used even with this on.

Gets or sets whether, when the lines are too short to hold two items, the space under each group header shrinks from a whole item's height to CustomExtraSpacingBetweenGroupHeaderRowAndDataItemRow.

A narrow panel showing one item per line would otherwise put a large gap under every header. It matters only while IsRenderItemDimensionHeightSpacingBetweenGroupHeaderAndDataItemRowEnabled is on.

Gets or sets whether items may each be a different size, rather than all sharing the cell of ItemDimension.

With variable sizes, items flow along each line at their own width (their own height, laid out vertically) and wrap when the line is full; a line is as tall as its tallest item. An item is measured when it first comes near the view, and its size is remembered; until then ItemDimension is its estimate, so set that to a typical item's size and the scroll bar will be close from the start. Grouping works with variable sizes too.

ItemPositioningMode does not apply, and jumping to an index (DesiredChildIndexToScrollTo) does not take the user to the item. Turning this on or off forgets the sizes measured so far.

Notes of different lengths, each as wide as its text needs, up to 320 units:

<ListBox ItemsSource="{Binding Notes}">
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <vwp:BinaryVirtualizingWrapPanel IsVariableItemSizeEnabled="True" ItemDimension="200,90" />
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>
    <ListBox.ItemTemplate>
        <DataTemplate>
            <Border Padding="10" MaxWidth="320" Background="LightYellow">
                <TextBlock Text="{Binding Text}" TextWrapping="Wrap" />
            </Border>
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>

Gets or sets the size of the cell each item is laid out in – and, with variable sizes, the size assumed for an item not yet measured.

In the fixed-size layout every item is measured and arranged in a cell of this size – size it for the largest item – and the panel knows from an index alone where an item is, which is what lets it virtualise a huge list without measuring it. Left at the default, the fixed-size layout shows nothing; the flow layout estimates 100 by 100. A line of scrolling is one cell. A change lays the panel out again from the first item. In XAML: ItemDimension="200,160".

Gets or sets what the fixed-size layout does with space at the end of a line too narrow for a whole item: leave it empty, or fit one more item, slightly clipped.

Safe puts whole items only on a line, so every item seen is complete. Greedy takes one more item when the space left is at least 85 per cent of an item; that last item is clipped by at most fifteen per cent of its width (its height, laid out vertically).

It applies to the fixed-size layout. The flow layout, used with IsVariableItemSizeEnabled or IsDataSourceGrouped, wraps each item at its own size and does not read it. A change re-counts the lines and keeps the scroll position.

Gets or sets the direction items run along a line before wrapping onto the next.

A change scrolls the panel back to the first item.

Gets or sets the transition played as the panel scrolls, while IsAnimationEnabled is on.

Keep transitions for galleries and showcases: they play on every page and wheel step, and a blur over a large panel costs rendering time on every frame it plays.

Gets or sets how many items, from the target onward, a jump to an item is meant to prepare.

The items created after a jump are those in view at the new position; this value does not change them.

Gets or sets the margin the panel gives itself when it is loaded: the space between the edge of the items control and the lines of items.

The panel copies this to its own FrameworkElement.Margin when it is loaded and when IsExtraMarginAtStartupRequired changes.

Gets or sets the scroll viewer that shows the panel's scroll bars and drives its scrolling.

Part of IScrollInfo; there is normally no reason to set it yourself. The scroll viewer must have CanContentScroll on (a ListBox has) for it to hand scrolling to the panel.

Gets or sets whether right alignment (ShouldRecomputeViewportExtentSpacingUponAlignment) leaves room for a vertical scroll bar.

Gets or sets whether the panel trims the owning items control's padding so that the first line of items sits snugly in its top-left corner.

When set, the owner's Padding loses three units on the left and nine at the top – once per owner, however often the panel is loaded – so the left-most item's border is not cut off and no gap shows above the first line. Setting it back gives them back. A change scrolls back to the first item.

Gets or sets whether the panel places its lines of items as its FrameworkElement.HorizontalAlignment says – centred, or against the right – by moving the space left at the end of each line into its own margin.

Only Center and Right are acted on, and only when the viewport is wider than ExtentWidth. The margin is worked out when this becomes true and each time the panel is loaded, not as the panel is resized. Setting it back to false restores RendertimeMargin. See also ShouldShareUnusedSpaceEquallyOnHorizontalAlignment.

Gets or sets whether, with StandaloneLine grouping (see GroupVirtualizationMode), a blank line comes before each group's header.

The blank line is one item high when ShouldRenderItemHeightSpacingAfterAGroupHasBeenRendered is set, else CustomExtraSpacingBetweenGroupRenderingCompletionAndGroupHeaderRowRenderingBegins.

Gets or sets whether the blank line before a group header, in StandaloneLine mode, is a whole item high.

Applies only with GroupVirtualizationMode set to StandaloneLine and ShouldRenderExtraLineBeforeHeader on.

Gets or sets whether centring, under ShouldRecomputeViewportExtentSpacingUponAlignment, splits the space left over exactly in half.

Gets or sets whether the margin set for ShouldRecomputeViewportExtentSpacingUponAlignment keeps the top and bottom of RendertimeMargin.

Gets how far the content is scrolled down.

Gets the height of the part of the content on show.

Gets the width of the part of the content on show.

Gets or sets what the panel does with the containers of items scrolled out of view.

While IsDataSourceGrouped is true, any other value is set back to VirtualizationScheme.LightWeightCache at once. A jump to an item uses VirtualizationSchemeWhenScrollingToASpecificChildIndex instead. A change scrolls to the first item.

Gets or sets what the panel does with the containers left out of view by a jump to an item.

Used for the layout passes of a jump only; ordinary scrolling uses VirtualizationSchemeOption. ScrollToTheDesiredChild sets it for its own jump and restores it.

Places each created item in its cell, or at its place in the flow layout.

finalSize.

Scrolls on by one line: one item's height laid out horizontally, one item's width laid out vertically.

The Down arrow key and the vertical scroll bar's down arrow call it. It stops at the end of the content.

Scrolls left by one item's width.

It moves the view only when the content is wider than the viewport – in practice, with Orientation set to Vertical. Plays PanelAnimationEffect when IsAnimationEnabled is on.

Scrolls right by one item's width.

It moves the view only when the content is wider than the viewport – in practice, with Orientation set to Vertical. Plays PanelAnimationEffect when IsAnimationEnabled is on.

Scrolls back by one line: one item's height laid out horizontally, one item's width laid out vertically.

The Up arrow key and the vertical scroll bar's up arrow call it. It stops at the start of the content.

Scrolls the least distance that brings part of an item into the viewport.

rectangle, unchanged.

WPF calls this for FrameworkElement.BringIntoView, for keyboard focus moving to an item, and for ListBox.ScrollIntoView. It works in every layout, because it reads the item's arranged position. It can only reach an item whose container exists; to reach any item by index, use ScrollToTheDesiredChild. A visual that is not inside the panel is ignored.

Works out which items are in view, creates and measures their containers, and reports the panel's size.

The whole of the space offered (or the items control's size used in its place).

Scrolls on by one line for a notch of the mouse wheel, as LineDown does.

Plays PanelAnimationEffect when IsAnimationEnabled is on.

Scrolls left by one item's width – the step for horizontal wheel scrolling – as LineLeft does.

Scrolls right by one item's width – the step for horizontal wheel scrolling – as LineRight does.

Scrolls back by one line for a notch of the mouse wheel, as LineUp does.

Plays PanelAnimationEffect when IsAnimationEnabled is on.

Lays the panel out again when it becomes the items control's items host, which on a window's first show happens after its first measure.

Drops the containers of items removed, moved or replaced, and – with AutoUpdateViewportOnDetectingTransactionalUpdatesToDataSource – refreshes the view.

Scrolls one line for the arrow keys – Up and Down call LineUp and LineDown, Left and Right call LineLeft and LineRight – after the base class has seen the key.

Lays the items out again for the panel's new size, keeping the item that was first in view (or DesiredChildIndexToScrollTo, when set) in view.

Scrolls on by one viewport: its height laid out horizontally, its width laid out vertically.

Plays PanelAnimationEffect when IsAnimationEnabled is on.

Scrolls left by the width of the viewport.

Plays PanelAnimationEffect when IsAnimationEnabled is on.

Scrolls right by the width of the viewport.

Plays PanelAnimationEffect when IsAnimationEnabled is on.

Scrolls back by one viewport: its height laid out horizontally, its width laid out vertically.

Plays PanelAnimationEffect when IsAnimationEnabled is on.

Refreshes the items control's collection view and lays the panel out again from the first item – call it after committing edits to the source, so that what is on screen matches the data.

When the items control's ItemsControl.ItemsSource is an ICollectionView (a VirtualizingCollectionView or a ListCollectionView, say), the view is refreshed – re-sorted, re-filtered and regrouped - the panel is measured again and both offsets go back to 0. With any other source it does nothing.

This is the panel's implementation of ISupportTransactionalUpdates.Refresh. AutoUpdateViewportOnDetectingTransactionalUpdatesToDataSource calls it on every change instead.

// Mark a batch of orders as shipped through the editable view, then bring the tiles up to date.
var view = (IEditableCollectionView)ordersList.ItemsSource;
foreach (Order order in selectedOrders)
{
    view.EditItem(order);
    order.Status = "Shipped";
    view.CommitEdit();
}

panel.Refresh();

Takes the user straight to an item, however far away it is, choosing for this jump alone whether the panel fades as it lands and what happens to the containers left behind.

The jump is made at once, by setting DesiredChildIndexToScrollTo and laying the panel out. IsAnimationEnabledWhenScrollToASpecificChildIndex and VirtualizationSchemeWhenScrollingToASpecificChildIndex are set from the arguments for the jump and restored afterwards. Unlike setting DesiredChildIndexToScrollTo, calling this with the same index again jumps again – after the user has scrolled away, say.

An order board: the panel is kept when it loads (it is created by the items control, from the template), and a "Go to order" button takes the clerk to the order typed in.

<ListBox x:Name="ordersList" ItemsSource="{Binding Orders}">
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <vwp:BinaryVirtualizingWrapPanel ItemDimension="220,110" Loaded="OnPanelLoaded" />
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>
</ListBox>

using Binarymission.WPF.Controls.Panels;

private BinaryVirtualizingWrapPanel _panel;

private void OnPanelLoaded(object sender, RoutedEventArgs e)
{
    _panel = (BinaryVirtualizingWrapPanel)sender;
}

private void OnGoToOrderClick(object sender, RoutedEventArgs e)
{
    int index = _orders.FindIndex(order => order.Number == orderNumberBox.Text);
    if (index >= 0 && _panel != null)
    {
        _panel.ScrollToTheDesiredChild(index, true,
            BinaryVirtualizingWrapPanel.VirtualizationScheme.DisposeOnLeavingViewPortBounds);
    }
}

Scrolls the content to a horizontal position.

Ignored while there is a ScrollOwner and CanHorizontallyScroll is false. The items now in view are created on the next layout pass.

Scrolls the content to a vertical position.

Ignored while there is a ScrollOwner and CanVerticallyScroll is false. The items now in view are created on the next layout pass.

// Back to the top of the gallery.
panel.SetVerticalOffset(0);

Occurs when the panel is about to create the items for a new stretch of the list, giving the first and last index about to be shown.

Raised from the measure pass of the fixed-size layout whenever the first index in view changes – not during a jump to an item, and not in the flow layout (variable sizes or grouping). Use it to fetch what those items need, or to show where in the list the user is. Changing ItemDimension from the handler lays the panel out again from the first item.

Identifies the CustomExtraSpacingBetweenGroupHeaderRowAndDataItemRow dependency property.

Identifies the CustomExtraSpacingBetweenGroupRenderingCompletionAndGroupHeaderRowRenderingBegins dependency property.

Identifies the DesiredChildIndexScrollingIsDataContextSynchronized dependency property.

Identifies the DesiredChildIndexToScrollTo dependency property.

Identifies the GroupHeaderItemCustomHeight dependency property.

Identifies the GroupVirtualizationMode dependency property.

Identifies the IsAnimationEnabled dependency property.

Identifies the IsAnimationEnabledWhenScrollToASpecificChildIndex dependency property.

Identifies the IsDataSourceGrouped dependency property.

Identifies the IsDynamicConstructionCapabilityEnabled dependency property.

Identifies the IsExtraMarginAtStartupRequired dependency property.

Identifies the IsRenderItemDimensionHeightSpacingBetweenGroupHeaderAndDataItemRowEnabled dependency property.

Identifies the IsTrimExtraLinkbreakForLeadingRowWithOneChildEnabled dependency property.

Identifies the IsVariableItemSizeEnabled dependency property.

Identifies the ItemDimension dependency property.

Identifies the ItemPositioningMode dependency property.

Identifies the Orientation dependency property.

Identifies the PanelAnimationEffect dependency property.

Identifies the ReRenderVisibilityRangeMaxCount dependency property.

Identifies the RendertimeMargin dependency property.

Identifies the ShouldAutoAdjustParentItemsControlInternalPadding dependency property.

Identifies the ShouldRenderExtraLineBeforeHeader dependency property.

Identifies the ShouldRenderItemHeightSpacingAfterAGroupHasBeenRendered dependency property.

Identifies the VirtualizationSchemeOption dependency property.

Identifies the VirtualizationSchemeWhenScrollingToASpecificChildIndex dependency property.