Virtualizing​Stack​Panel Class

Definition

Arranges and virtualizes content on a single line that is oriented either horizontally or vertically.

public class VirtualizingStackPanel : System.Windows.Controls.VirtualizingPanel, System.Windows.Controls.Primitives.IScrollInfo
Inheritance
Derived
Implements

Inherited Members

System.Object

System.Windows.Controls.Panel

System.Windows.Controls.VirtualizingPanel

System.Windows.DependencyObject

System.Windows.FrameworkElement

System.Windows.Media.Visual

System.Windows.Threading.DispatcherObject

System.Windows.UIElement

Examples

The following example shows how to bind to an XML data source and virtualize the items displayed in a ListBox element using Extensible Application Markup Language (XAML). Notice that the VirtualizingStackPanel.IsVirtualizing attached property is explicitly set to true.

<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
      WindowTitle="VirtualizingStackPanel Sample" 
      Height="150"
      VerticalAlignment="Top">
    <Page.Resources>
        <XmlDataProvider x:Key="Leagues" Source="Leagues.xml" XPath="Leagues/League"/>
        
    <DataTemplate x:Key="NameDataStyle">
      <TextBlock Text="{Binding XPath=@name}" FontFamily="Arial" FontSize="12" Foreground="Black"/>
    </DataTemplate>
        
    </Page.Resources>
  <Border HorizontalAlignment="Left" 
          VerticalAlignment="Top" 
          BorderBrush="Black" 
          BorderThickness="2">
       <ScrollViewer>
      <StackPanel DataContext="{Binding Source={StaticResource Leagues}}">
          <TextBlock Text="{Binding XPath=@name}" FontFamily="Arial" FontSize="18" Foreground="Black"/>
              <ListBox VirtualizingStackPanel.IsVirtualizing="True" 
                       ItemsSource="{Binding XPath=Team}" 
                       ItemTemplate="{DynamicResource NameDataStyle}"/>      
      </StackPanel>
      </ScrollViewer>
  </Border>    
</Page>

The following example creates a ListBox and sets the VirtualizingStackPanel.VirtualizationMode attached property to Recycling.

<StackPanel>

  <StackPanel.Resources>
    <src:LotsOfItems x:Key="data"/>
  </StackPanel.Resources>

  <ListBox Height="150" ItemsSource="{StaticResource data}" 
             VirtualizingStackPanel.VirtualizationMode="Recycling" />

</StackPanel>

The following example shows the data used in the previous example.

public class LotsOfItems : ObservableCollection<String>
{
    public LotsOfItems()
    {
        for (int i = 0; i < 1000; ++i)
        {
            Add("item " + i.ToString());
        }
    }
}
Public Class LotsOfItems
    Inherits ObservableCollection(Of String)
    Public Sub New()
        For i As Integer = 0 To 999
            Add("item " & i.ToString())
        Next
    End Sub
End Class

Remarks

The standard layout system creates item containers and computes layout for each item associated with a list control. The word "virtualize" refers to a technique by which a subset of user interface (UI) elements are generated from a larger number of data items based on which items are visible on-screen. Generating many UI elements when only a few elements might be on the screen can adversely affect the performance of your application. The VirtualizingStackPanel calculates the number of visible items and works with the ItemContainerGenerator from an ItemsControl (such as ListBox or ListView) to create UI elements only for visible items.

Virtualization in a StackPanel only occurs when the items control contained in the panel creates its own item containers. You can ensure this happens by using data binding. In scenarios where item containers are created and added to the items control, a VirtualizingStackPanel offers no performance advantage over a StackPanel.

VirtualizingStackPanel is the default items host for the ListBox element. By default, the VirtualizingStackPanel.IsVirtualizing attached property is set to true.

When the VirtualizingStackPanel.IsVirtualizing attached property is set to false, a VirtualizingStackPanel behaves the same as an ordinary StackPanel.

Constructors

Virtualizing​Stack​Panel()

Initializes a new instance of the VirtualizingStackPanel class.

Fields

Clean​Up​Virtualized​Item​Event

Identifies the VirtualizingStackPanel.CleanUpVirtualizedItem attached event.

Is​Virtualizing​Property

Identifies the VirtualizingPanel.IsVirtualizing attached property.

Orientation​Property

Identifies the Orientation dependency property.

Virtualization​Mode​Property

Identifies the VirtualizingStackPanel.VirtualizationMode attached property.

Properties

Can​Hierarchically​Scroll​And​Virtualize​Core

Gets value that indicates whether the VirtualizingStackPanel can virtualize items that are grouped or organized in a hierarchy.

Can​Horizontally​Scroll

Gets or sets a value that indicates whether a VirtualizingStackPanel can scroll in the horizontal dimension.

Can​Vertically​Scroll

Gets or sets a value that indicates whether content can scroll in the vertical dimension.

Extent​Height

Gets a value that contains the vertical size of the extent.

Extent​Width

Gets a value that contains the horizontal size of the extent.

Has​Logical​Orientation

Gets a value that indicates if this VirtualizingStackPanel has a vertical or horizontal orientation.

Horizontal​Offset

Gets a value that contains the horizontal offset of the scrolled content.

Logical​Orientation

Gets a value that represents the Orientation of the VirtualizingStackPanel.

Orientation

Gets or sets a value that describes the horizontal or vertical orientation of stacked content.

Scroll​Owner

Gets or sets a value that identifies the container that controls scrolling behavior in this VirtualizingStackPanel.

Vertical​Offset

Gets a value that contains the vertical offset of the scrolled content.

Viewport​Height

Gets a value that contains the vertical size of the viewport of the content.

Viewport​Width

Gets a value that contains the horizontal size of the viewport of the content.

Methods

Add​Clean​Up​Virtualized​Item​Handler(​Dependency​Object, ​Clean​Up​Virtualized​Item​Event​Handler)

Adds an event handler for the VirtualizingStackPanel.CleanUpVirtualizedItem attached event.

Arrange​Override(​Size)

Arranges the content of a VirtualizingStackPanel element.

Bring​Index​Into​View(​Int32)

Generates the item at the specified index position and brings it into view.

Get​Item​Offset​Core(​UI​Element)

Returns the position of the specified item, relative to the VirtualizingStackPanel.

Line​Down()

Scrolls content downward by one logical unit.

Line​Left()

Scrolls content to the left by one logical unit.

Line​Right()

Scrolls content to the right by one logical unit.

Line​Up()

Scrolls content upward by one logical unit.

Make​Visible(​Visual, ​Rect)

Scrolls to the specified coordinates and makes that portion of a Visual visible.

Measure​Override(​Size)

Measures the child elements of a VirtualizingStackPanel in anticipation of arranging them during the ArrangeOverride(Size) pass.

Mouse​Wheel​Down()

Scrolls content logically downward in response to a downward click of the mouse wheel button.

Mouse​Wheel​Left()

Scrolls content logically to the left in response to a left click of the mouse wheel button.

Mouse​Wheel​Right()

Scrolls content logically to the right in response to a right click of the mouse wheel button.

Mouse​Wheel​Up()

Scrolls content logically upward in response to an upward click of the mouse wheel button.

On​Clean​Up​Virtualized​Item(​Clean​Up​Virtualized​Item​Event​Args)

Called when an item that is hosted by the VirtualizingStackPanel is re-virtualized.

On​Clear​Children()

Called when the collection of child elements is cleared by the base Panel class.

On​Items​Changed(​Object, ​Items​Changed​Event​Args)

Called when the Items collection that is associated with the ItemsControl for this Panel changes.

On​Viewport​Offset​Changed(​Vector, ​Vector)

Called when the offset of the viewport changes as a user scrolls through content.

On​Viewport​Size​Changed(​Size, ​Size)

Called when the size of the viewport changes.

Page​Down()

Scrolls content downward by one page.

Page​Left()

Scrolls content to the left by one page.

Page​Right()

Scrolls content to the right by one page.

Page​Up()

Scrolls content upward by one page.

Remove​Clean​Up​Virtualized​Item​Handler(​Dependency​Object, ​Clean​Up​Virtualized​Item​Event​Handler)

Removes an event handler for the VirtualizingStackPanel.CleanUpVirtualizedItem attached event.

Set​Horizontal​Offset(​Double)

Sets the value of the HorizontalOffset property.

Set​Vertical​Offset(​Double)

Sets the value of the VerticalOffset property.

Should​Items​Change​Affect​Layout​Core(​Boolean, ​Items​Changed​Event​Args)

Returns a value that indicates whether a changed item in an ItemsControl affects the layout for this panel.