| title | description | ms.date | dev_langs | helpviewer_keywords | ms.assetid | |||||
|---|---|---|---|---|---|---|---|---|---|---|
ScrollViewer Overview |
Learn about the ScrollViewer control, which enables scrolling of content in Windows Presentation Foundation applications. See usage examples. |
03/30/2017 |
|
|
94a13b94-cfdf-4b12-a1aa-90cb50c6e9b9 |
Content within a user interface is often larger than a computer screen's display area. The xref:System.Windows.Controls.ScrollViewer control provides a convenient way to enable scrolling of content in Windows Presentation Foundation (WPF) applications. This topic introduces the xref:System.Windows.Controls.ScrollViewer element and provides several usage examples.
There are two predefined elements that enable scrolling in WPF applications: xref:System.Windows.Controls.Primitives.ScrollBar and xref:System.Windows.Controls.ScrollViewer. The xref:System.Windows.Controls.ScrollViewer control encapsulates horizontal and vertical xref:System.Windows.Controls.Primitives.ScrollBar elements and a content container (such as a xref:System.Windows.Controls.Panel element) in order to display other visible elements in a scrollable area. You must build a custom object in order to use the xref:System.Windows.Controls.Primitives.ScrollBar element for content scrolling. However, you can use the xref:System.Windows.Controls.ScrollViewer element by itself because it is a composite control that encapsulates xref:System.Windows.Controls.Primitives.ScrollBar functionality.
The xref:System.Windows.Controls.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 xref:System.Windows.Controls.ScrollViewer.ScrollChanged event to detect a change in a xref:System.Windows.Controls.ScrollViewer state.
A xref:System.Windows.Controls.ScrollViewer can only have one child, typically a xref:System.Windows.Controls.Panel element that can host a xref:System.Windows.Controls.Panel.Children%2A collection of elements. The xref:System.Windows.Controls.ContentPresenter.Content%2A property defines the sole child of the xref:System.Windows.Controls.ScrollViewer.
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 xref:System.Windows.Controls.Panel elements. WPF supports both types of scrolling.
The xref:System.Windows.Controls.Primitives.IScrollInfo interface represents the main scrolling region within a xref:System.Windows.Controls.ScrollViewer or derived control. The interface defines scrolling properties and methods that can be implemented by xref:System.Windows.Controls.Panel elements that require scrolling by logical unit, rather than by a physical increment. Casting an instance of xref:System.Windows.Controls.Primitives.IScrollInfo to a derived xref:System.Windows.Controls.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 xref:System.Windows.Controls.ScrollViewer control supports scrolling by physical units.
xref:System.Windows.Controls.StackPanel and xref:System.Windows.Controls.VirtualizingStackPanel both implement xref:System.Windows.Controls.Primitives.IScrollInfo and natively support logical scrolling. For layout controls that natively support logical scrolling, you can still achieve physical scrolling by wrapping the host xref:System.Windows.Controls.Panel element in a xref:System.Windows.Controls.ScrollViewer and setting the xref:System.Windows.Controls.ScrollViewer.CanContentScroll%2A property to false.
The following code example demonstrates how to cast an instance of xref:System.Windows.Controls.Primitives.IScrollInfo to a xref:System.Windows.Controls.StackPanel and use content scrolling methods (xref:System.Windows.Controls.Primitives.IScrollInfo.LineUp%2A and xref:System.Windows.Controls.Primitives.IScrollInfo.LineDown%2A) defined by the interface.
[!code-csharpIScrollInfoMethods#3] [!code-vbIScrollInfoMethods#3]
The following example creates a xref:System.Windows.Controls.ScrollViewer in a window that contains some text and a rectangle. xref:System.Windows.Controls.Primitives.ScrollBar elements appear only when they are necessary. When you resize the window, the xref:System.Windows.Controls.Primitives.ScrollBar elements appear and disappear, due to updated values of the xref:System.Windows.Controls.ScrollViewer.ComputedHorizontalScrollBarVisibility%2A and xref:System.Windows.Controls.ScrollViewer.ComputedVerticalScrollBarVisibility%2A properties.
[!code-cppScrollViewer#1] [!code-csharpScrollViewer#1] [!code-vbScrollViewer#1] [!code-xamlScrollViewer#1]
Like all controls in Windows Presentation Foundation, the xref:System.Windows.Controls.ScrollViewer can be styled in order to change the default rendering behavior of the control. 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. xref:System.Windows.Documents.FlowDocument is for documents that are designed to be hosted within a viewing control, such as xref:System.Windows.Controls.FlowDocumentPageViewer, that supports paginating content across multiple pages, preventing the need for scrolling. xref:System.Windows.Controls.DocumentViewer provides a solution for viewing xref:System.Windows.Documents.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 WPF.
- xref:System.Windows.Controls.ScrollViewer
- xref:System.Windows.Controls.Primitives.ScrollBar
- xref:System.Windows.Controls.Primitives.IScrollInfo
- How to: Create a Scroll Viewer
- Documents in WPF
- ScrollBar Styles and Templates
- Controls