Table of Contents

Class VirtualizingStaggeredPanel

Namespace
Nova.Avalonia.UI.Controls
Assembly
Nova.Avalonia.UI.dll

A virtualizing panel that arranges children in a staggered grid (masonry) layout. Items are placed in the shortest column, creating an efficient Pinterest-style layout. Only items within the visible viewport (plus buffer) are materialized for optimal performance.

public class VirtualizingStaggeredPanel : VirtualizingPanel, INotifyPropertyChanged, IDataContextProvider, ILogical, IThemeVariantHost, IResourceHost, IResourceNode, IStyleHost, ISetLogicalParent, ISetInheritanceParent, ISupportInitialize, IStyleable, INamed, IInputElement, IDataTemplateHost, ISetterValue, IChildIndexProvider, INavigableContainer
Inheritance
AvaloniaObject
Animatable
StyledElement
Visual
Layoutable
Interactive
InputElement
Control
Panel
VirtualizingPanel
VirtualizingStaggeredPanel
Implements
IDataContextProvider
ILogical
IThemeVariantHost
IResourceHost
IResourceNode
IStyleHost
ISetLogicalParent
ISetInheritanceParent
IStyleable
INamed
IInputElement
IDataTemplateHost
ISetterValue
IChildIndexProvider
INavigableContainer
Inherited Members
VirtualizingPanel.OnItemsControlChanged(ItemsControl)
VirtualizingPanel.AddInternalChild(Control)
VirtualizingPanel.RemoveInternalChild(Control)
VirtualizingPanel.ItemContainerGenerator
VirtualizingPanel.Items
VirtualizingPanel.ItemsControl
Panel.BackgroundProperty
Panel.Render(DrawingContext)
Panel.AffectsParentArrange<TPanel>(params AvaloniaProperty[])
Panel.AffectsParentMeasure<TPanel>(params AvaloniaProperty[])
Panel.Children
Panel.Background
Panel.IsItemsHost
Control.FocusAdornerProperty
Control.TagProperty
Control.ContextMenuProperty
Control.ContextFlyoutProperty
Control.RequestBringIntoViewEvent
Control.ContextRequestedEvent
Control.LoadedEvent
Control.UnloadedEvent
Control.SizeChangedEvent
Control.GetTemplateFocusTarget()
Control.OnLoaded(RoutedEventArgs)
Control.OnUnloaded(RoutedEventArgs)
Control.OnSizeChanged(SizeChangedEventArgs)
Control.OnAttachedToVisualTreeCore(VisualTreeAttachmentEventArgs)
Control.OnDetachedFromVisualTreeCore(VisualTreeAttachmentEventArgs)
Control.OnGotFocus(GotFocusEventArgs)
Control.OnLostFocus(RoutedEventArgs)
Control.OnCreateAutomationPeer()
Control.OnPointerReleased(PointerReleasedEventArgs)
Control.OnKeyUp(KeyEventArgs)
Control.FocusAdorner
Control.DataTemplates
Control.ContextMenu
Control.ContextFlyout
Control.IsLoaded
Control.Tag
Control.ContextRequested
Control.Loaded
Control.Unloaded
Control.SizeChanged
InputElement.FocusableProperty
InputElement.IsEnabledProperty
InputElement.IsEffectivelyEnabledProperty
InputElement.CursorProperty
InputElement.IsKeyboardFocusWithinProperty
InputElement.IsFocusedProperty
InputElement.IsHitTestVisibleProperty
InputElement.IsPointerOverProperty
InputElement.IsTabStopProperty
InputElement.GotFocusEvent
InputElement.LostFocusEvent
InputElement.KeyDownEvent
InputElement.KeyUpEvent
InputElement.TabIndexProperty
InputElement.TextInputEvent
InputElement.TextInputMethodClientRequestedEvent
InputElement.PointerEnteredEvent
InputElement.PointerExitedEvent
InputElement.PointerMovedEvent
InputElement.PointerPressedEvent
InputElement.PointerReleasedEvent
InputElement.PointerCaptureLostEvent
InputElement.PointerWheelChangedEvent
InputElement.TappedEvent
InputElement.HoldingEvent
InputElement.DoubleTappedEvent
InputElement.Focus(NavigationMethod, KeyModifiers)
InputElement.OnAccessKey(RoutedEventArgs)
InputElement.OnKeyDown(KeyEventArgs)
InputElement.OnTextInput(TextInputEventArgs)
InputElement.OnPointerEntered(PointerEventArgs)
InputElement.OnPointerExited(PointerEventArgs)
InputElement.OnPointerMoved(PointerEventArgs)
InputElement.OnPointerPressed(PointerPressedEventArgs)
InputElement.OnPointerCaptureLost(PointerCaptureLostEventArgs)
InputElement.OnPointerWheelChanged(PointerWheelEventArgs)
InputElement.UpdateIsEffectivelyEnabled()
InputElement.Focusable
InputElement.IsEnabled
InputElement.Cursor
InputElement.IsKeyboardFocusWithin
InputElement.IsFocused
InputElement.IsHitTestVisible
InputElement.IsPointerOver
InputElement.IsTabStop
InputElement.IsEffectivelyEnabled
InputElement.TabIndex
InputElement.KeyBindings
InputElement.IsEnabledCore
InputElement.GestureRecognizers
InputElement.GotFocus
InputElement.LostFocus
InputElement.KeyDown
InputElement.KeyUp
InputElement.TextInput
InputElement.TextInputMethodClientRequested
InputElement.PointerEntered
InputElement.PointerExited
InputElement.PointerMoved
InputElement.PointerPressed
InputElement.PointerReleased
InputElement.PointerCaptureLost
InputElement.PointerWheelChanged
InputElement.Tapped
InputElement.Holding
InputElement.DoubleTapped
Interactive.RaiseEvent(RoutedEventArgs)
Interactive.BuildEventRoute(RoutedEvent)
Layoutable.DesiredSizeProperty
Layoutable.WidthProperty
Layoutable.HeightProperty
Layoutable.MinWidthProperty
Layoutable.MaxWidthProperty
Layoutable.MinHeightProperty
Layoutable.MaxHeightProperty
Layoutable.MarginProperty
Layoutable.HorizontalAlignmentProperty
Layoutable.VerticalAlignmentProperty
Layoutable.UseLayoutRoundingProperty
Layoutable.UpdateLayout()
Layoutable.ApplyTemplate()
Layoutable.Measure(Size)
Layoutable.Arrange(Rect)
Layoutable.InvalidateMeasure()
Layoutable.InvalidateArrange()
Layoutable.AffectsMeasure<T>(params AvaloniaProperty[])
Layoutable.AffectsArrange<T>(params AvaloniaProperty[])
Layoutable.MeasureCore(Size)
Layoutable.ArrangeCore(Rect)
Layoutable.OnMeasureInvalidated()
Layoutable.OnVisualParentChanged(Visual, Visual)
Layoutable.Width
Layoutable.Height
Layoutable.MinWidth
Layoutable.MaxWidth
Layoutable.MinHeight
Layoutable.MaxHeight
Layoutable.Margin
Layoutable.HorizontalAlignment
Layoutable.VerticalAlignment
Layoutable.DesiredSize
Layoutable.IsMeasureValid
Layoutable.IsArrangeValid
Layoutable.UseLayoutRounding
Layoutable.EffectiveViewportChanged
Layoutable.LayoutUpdated
Visual.BoundsProperty
Visual.ClipToBoundsProperty
Visual.ClipProperty
Visual.IsVisibleProperty
Visual.OpacityProperty
Visual.OpacityMaskProperty
Visual.EffectProperty
Visual.HasMirrorTransformProperty
Visual.RenderTransformProperty
Visual.RenderTransformOriginProperty
Visual.FlowDirectionProperty
Visual.VisualParentProperty
Visual.ZIndexProperty
Visual.GetFlowDirection(Visual)
Visual.SetFlowDirection(Visual, FlowDirection)
Visual.InvalidateVisual()
Visual.AffectsRender<T>(params AvaloniaProperty[])
Visual.InvalidateMirrorTransform()
Visual.Bounds
Visual.ClipToBounds
Visual.Clip
Visual.IsEffectivelyVisible
Visual.IsVisible
Visual.Opacity
Visual.OpacityMask
Visual.Effect
Visual.HasMirrorTransform
Visual.RenderTransform
Visual.RenderTransformOrigin
Visual.FlowDirection
Visual.ZIndex
Visual.VisualChildren
Visual.VisualRoot
Visual.BypassFlowDirectionPolicies
Visual.AttachedToVisualTree
Visual.DetachedFromVisualTree
StyledElement.DataContextProperty
StyledElement.NameProperty
StyledElement.ParentProperty
StyledElement.TemplatedParentProperty
StyledElement.ThemeProperty
StyledElement.BeginInit()
StyledElement.EndInit()
StyledElement.ApplyStyling()
StyledElement.InitializeIfNeeded()
StyledElement.OnAttachedToLogicalTree(LogicalTreeAttachmentEventArgs)
StyledElement.OnDetachedFromLogicalTree(LogicalTreeAttachmentEventArgs)
StyledElement.OnDataContextBeginUpdate()
StyledElement.OnDataContextEndUpdate()
StyledElement.OnInitialized()
StyledElement.Name
StyledElement.Classes
StyledElement.DataContext
StyledElement.IsInitialized
StyledElement.Styles
StyledElement.StyleKey
StyledElement.Resources
StyledElement.TemplatedParent
StyledElement.Theme
StyledElement.LogicalChildren
StyledElement.PseudoClasses
StyledElement.StyleKeyOverride
StyledElement.Parent
StyledElement.ActualThemeVariant
StyledElement.AttachedToLogicalTree
StyledElement.DetachedFromLogicalTree
StyledElement.DataContextChanged
StyledElement.Initialized
StyledElement.ResourcesChanged
StyledElement.ActualThemeVariantChanged
Animatable.TransitionsProperty
Animatable.OnPropertyChangedCore(AvaloniaPropertyChangedEventArgs)
Animatable.Transitions
AvaloniaObject.CheckAccess()
AvaloniaObject.VerifyAccess()
AvaloniaObject.ClearValue(AvaloniaProperty)
AvaloniaObject.ClearValue<T>(AvaloniaProperty<T>)
AvaloniaObject.ClearValue<T>(StyledProperty<T>)
AvaloniaObject.ClearValue<T>(DirectPropertyBase<T>)
AvaloniaObject.GetHashCode()
AvaloniaObject.GetValue(AvaloniaProperty)
AvaloniaObject.GetValue<T>(StyledProperty<T>)
AvaloniaObject.GetValue<T>(DirectPropertyBase<T>)
AvaloniaObject.GetBaseValue<T>(StyledProperty<T>)
AvaloniaObject.IsAnimating(AvaloniaProperty)
AvaloniaObject.IsSet(AvaloniaProperty)
AvaloniaObject.SetValue<T>(StyledProperty<T>, T, BindingPriority)
AvaloniaObject.SetValue<T>(DirectPropertyBase<T>, T)
AvaloniaObject.SetCurrentValue<T>(StyledProperty<T>, T)
AvaloniaObject.Bind(AvaloniaProperty, IBinding)
AvaloniaObject.CoerceValue(AvaloniaProperty)
AvaloniaObject.RaisePropertyChanged<T>(DirectPropertyBase<T>, T, T)
AvaloniaObject.SetAndRaise<T>(DirectPropertyBase<T>, ref T, T)
AvaloniaObject.InheritanceParent
AvaloniaObject.this[AvaloniaProperty]
AvaloniaObject.this[IndexerDescriptor]
AvaloniaObject.PropertyChanged

Examples

<ItemsControl ItemsSource="{Binding Items}">
    <ItemsControl.ItemsPanel>
        <ItemsPanelTemplate>
            <controls:VirtualizingStaggeredPanel DesiredColumnWidth="200" ColumnSpacing="8" RowSpacing="8"/>
        </ItemsPanelTemplate>
    </ItemsControl.ItemsPanel>
</ItemsControl>

Remarks

This panel virtualizes items by only creating UI containers for visible items. Off-screen items are recycled and reused when scrolling, minimizing memory usage and improving scroll performance for large datasets.

The panel automatically calculates the number of columns based on the available width and the DesiredColumnWidth property.

Constructors

VirtualizingStaggeredPanel() 

public VirtualizingStaggeredPanel()

Fields

ColumnSpacingProperty

Defines the ColumnSpacing property.

public static readonly StyledProperty<double> ColumnSpacingProperty

Field Value

StyledProperty<double>

DesiredColumnWidthProperty

Defines the DesiredColumnWidth property.

public static readonly StyledProperty<double> DesiredColumnWidthProperty

Field Value

StyledProperty<double>

RowSpacingProperty

Defines the RowSpacing property.

public static readonly StyledProperty<double> RowSpacingProperty

Field Value

StyledProperty<double>

Properties

ColumnSpacing

Gets or sets the horizontal spacing between columns.

public double ColumnSpacing { get; set; }

Property Value

double

The horizontal spacing in device-independent pixels. Default is 0.

DesiredColumnWidth

Gets or sets the desired width of each column. The actual column width may vary slightly to fill the available space evenly.

public double DesiredColumnWidth { get; set; }

Property Value

double

The desired column width in device-independent pixels. Default is 250.

RowSpacing

Gets or sets the vertical spacing between items in the same column.

public double RowSpacing { get; set; }

Property Value

double

The vertical spacing in device-independent pixels. Default is 0.

Methods

ArrangeOverride(Size)

Positions child elements as part of a layout pass.

protected override Size ArrangeOverride(Size finalSize)

Parameters

finalSize Size

The size available to the control.

Returns

Size

The actual size used.

ContainerFromIndex(int)

Returns the container for the item at the specified index.

protected override Control? ContainerFromIndex(int index)

Parameters

index int

The index of the item to retrieve.

Returns

Control

The container for the item at the specified index within the item collection, if the item is realized; otherwise, null.

Remarks

Note for implementors: if the item at the specified index is an ItemIsOwnContainer item that has previously been realized, then the item should be returned even if it currently falls outside the realized viewport.

GetControl(NavigationDirection, IInputElement?, bool)

Gets the next control in the specified direction.

protected override Control? GetControl(NavigationDirection direction, IInputElement? from, bool wrap)

Parameters

direction NavigationDirection

The movement direction.

from IInputElement

The control from which movement begins.

wrap bool

Whether to wrap around when the first or last item is reached.

Returns

Control

The control.

GetRealizedContainers()

Gets the currently realized containers.

protected override IEnumerable<Control>? GetRealizedContainers()

Returns

IEnumerable<Control>

IndexFromContainer(Control)

Returns the index to the item that has the specified realized container.

protected override int IndexFromContainer(Control container)

Parameters

container Control

The generated container to retrieve the item index for.

Returns

int

The index to the item that corresponds to the specified realized container, or -1 if container is not found.

MeasureOverride(Size)

Measures the control and its child elements as part of a layout pass.

protected override Size MeasureOverride(Size availableSize)

Parameters

availableSize Size

The size available to the control.

Returns

Size

The desired size for the control.

OnAttachedToVisualTree(VisualTreeAttachmentEventArgs)

Called when the control is added to a rooted visual tree.

protected override void OnAttachedToVisualTree(VisualTreeAttachmentEventArgs e)

Parameters

e VisualTreeAttachmentEventArgs

The event args.

OnDetachedFromVisualTree(VisualTreeAttachmentEventArgs)

Called when the control is removed from a rooted visual tree.

protected override void OnDetachedFromVisualTree(VisualTreeAttachmentEventArgs e)

Parameters

e VisualTreeAttachmentEventArgs

The event args.

OnItemsChanged(IReadOnlyList<object?>, NotifyCollectionChangedEventArgs)

Called when the Avalonia.Controls.ItemsControl.Items collection of the owner Avalonia.Controls.VirtualizingPanel.ItemsControl changes.

protected override void OnItemsChanged(IReadOnlyList<object?> items, NotifyCollectionChangedEventArgs e)

Parameters

items IReadOnlyList<object>

The items.

e NotifyCollectionChangedEventArgs

The event args.

Remarks

This method is called a INotifyCollectionChanged event is raised by the items, or when the Avalonia.Controls.ItemsControl.Items property is assigned a new collection, in which case the NotifyCollectionChangedAction will be Reset.

OnPropertyChanged(AvaloniaPropertyChangedEventArgs)

Called when a avalonia property changes on the object.

protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs change)

Parameters

change AvaloniaPropertyChangedEventArgs

The property change details.

ScrollIntoView(int)

Scrolls the specified item into view.

protected override Control? ScrollIntoView(int index)

Parameters

index int

The index of the item.

Returns

Control

The element with the specified index, or null if the element could not be brought into view.

Edit this page