Content within a user interface is often larger than a computer screen's display area. The ScrollViewer control provides a convenient way to enable scrolling of content in Windows Presentation Foundation (WPF) applications. This topic introduces the ScrollViewer element and provides several usage examples.
This topic contains the following sections:
- The ScrollViewer Control
- Physical vs. Logical Scrolling
- Defining and Using a ScrollViewer Element
- Styling a ScrollViewer
- Paginating Documents
- Related Topics
The ScrollViewer Control
There are two predefined elements that enable scrolling in WPF applications: ScrollBar and ScrollViewer. The ScrollViewer control encapsulates horizontal and vertical ScrollBar elements and a content container (such as a Panel element) in order to display other visible elements in a scrollable area. You must build a custom object in order to use the ScrollBar element for content scrolling. However, you can use the ScrollViewer element by itself because it is a composite control that encapsulates ScrollBar functionality.
The ScrollViewer control responds to both mouse and keyboard commands, and defines numerous methods with which to scroll content by predetermined increments. You can use the ScrollChanged event to detect a change in a ScrollViewer state.
Physical vs. Logical Scrolling
Physical scrolling is used to scroll content by a predetermined physical increment, typically by a value that is declared in pixels. Logical scrolling is used to scroll to the next item in the logical tree. Physical scrolling is the default scroll behavior for most Panel elements. WPF supports both types of scrolling.
The IScrollInfo Interface
The IScrollInfo interface represents the main scrolling region within a ScrollViewer or derived control. The interface defines scrolling properties and methods that can be implemented by Panel elements that require scrolling by logical unit, rather than by a physical increment. Casting an instance of IScrollInfo to a derived Panel and then using its scrolling methods provides a useful way to scroll to the next logical unit in a child collection, rather than by pixel increment. By default, the ScrollViewer control supports scrolling by physical units.
StackPanel and VirtualizingStackPanel both implement IScrollInfo and natively support logical scrolling. For layout controls that natively support logical scrolling, you can still achieve physical scrolling by wrapping the host Panel element in a ScrollViewer and setting the CanContentScroll property to false.
Defining and Using a ScrollViewer Element
The following example creates a ScrollViewer in a window that contains some text and a rectangle. ScrollBar elements appear only when they are necessary. When you resize the window, the ScrollBar elements appear and disappear, due to updated values of the ComputedHorizontalScrollBarVisibility and ComputedVerticalScrollBarVisibility properties.
For the complete code sample, see Scroll Viewer Sample.
// Create the application's main window mainWindow = new Window (); mainWindow.Title = "ScrollViewer Sample"; // Define a ScrollViewer myScrollViewer = new ScrollViewer(); myScrollViewer.HorizontalScrollBarVisibility = ScrollBarVisibility.Auto; // Add Layout control myStackPanel = new StackPanel(); myStackPanel.HorizontalAlignment = HorizontalAlignment.Left; myStackPanel.VerticalAlignment = VerticalAlignment.Top; TextBlock myTextBlock = new TextBlock(); myTextBlock.TextWrapping = TextWrapping.Wrap; myTextBlock.Margin = new Thickness(0, 0, 0, 20); myTextBlock.Text = "Scrolling is enabled when it is necessary. Resize the Window, making it larger and smaller."; Rectangle myRectangle = new Rectangle(); myRectangle.Fill = Brushes.Red; myRectangle.Width = 500; myRectangle.Height = 500; // Add child elements to the parent StackPanel myStackPanel.Children.Add(myTextBlock); myStackPanel.Children.Add(myRectangle); // Add the StackPanel as the lone Child of the Border myScrollViewer.Content = myStackPanel; // Add the Border as the Content of the Parent Window Object mainWindow.Content = myScrollViewer; mainWindow.Show ();
<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" WindowTitle="ScrollViewer Sample"> <ScrollViewer HorizontalScrollBarVisibility="Auto"> <StackPanel VerticalAlignment="Top" HorizontalAlignment="Left"> <TextBlock TextWrapping="Wrap" Margin="0,0,0,20">Scrolling is enabled when it is necessary. Resize the window, making it larger and smaller.</TextBlock> <Rectangle Fill="Red" Width="500" Height="500"></Rectangle> </StackPanel> </ScrollViewer> </Page>
Styling a ScrollViewer
Like all controls in Windows Presentation Foundation, the ScrollViewer can be styled in order to change the default rendering behavior of the control. For an example of a custom styled ScrollViewer, see Style the ScrollViewer Element. For additional information on control styling, see Styling and Templating.
For document content, an alternative to scrolling is to choose a document container that supports pagination. FlowDocuments are documents that are designed to be hosted within a viewing control, such as FlowDocumentPageViewer, that supports paginating content across multiple pages, preventing the need for scrolling. DocumentViewer provides a solution for viewing FixedDocument content, which uses traditional scrolling to display content outside the realm of the display area.
For additional information about document formats and presentation options, see Documents in Windows Presentation Foundation.