.NET 4.0+

WPF Layout Controls - ScrollViewer

by Richard Carr, published at http://www.blackwasp.co.uk/WPFScrollViewer.aspx

The thirteenth part of the Windows Presentation Foundation Fundamentals tutorial continues the examination of the WPF layout controls. This article looks at the ScrollViewer control, which contains its children in a scrollable rectangle.

The ScrollViewer

The ScrollViewer is a WPF layout control that allows you to show more information than the available space permits. When the child control is too large to fit within the rectangle defined by a ScrollViewer, horizontal and vertical scroll bars can be added. These allow the user to scroll up and down or from side to side to view the hidden content.

As with other layout controls, the ScrollViewer must contain a single child control. However, this can be a layout control that has many children of its own, such as a Grid, StackPanel or Canvas.

ScrollViewer Example

For our first example of a ScrollViewer we'll use mainly default property values. Create a new WPF Application project in Visual Studio. Name the project, "ScrollViewerDemo" and replace the XAML in the initial window with the following:

<Window x:Class="ScrollViewerDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="ScrollViewer Demo"
        Width="250"
        Height="200">
    <ScrollViewer>
        <TextBlock FontSize="15" TextWrapping="Wrap">         
            Inferno · Canto I<LineBreak/>
            <LineBreak/>
            Nel mezzo del cammin di nostra vita<LineBreak/>
            mi ritrovai per una selva oscura,<LineBreak/>
            ché la diritta via era smarrita.<LineBreak/>
            <LineBreak/>
            Ahi quanto a dir qual era è cosa dura<LineBreak/>
            esta selva selvaggia e aspra e forte<LineBreak/>
            che nel pensier rinova la paura!<LineBreak/>
            <LineBreak/>
            Tant’ è amara che poco è più morte;<LineBreak/>
            ma per trattar del ben ch’i’ vi trovai,<LineBreak/>
            dirò de l’altre cose ch’i’ v’ho scorte.<LineBreak/>
            <LineBreak/>
            Io non so ben ridir com’ i’ v’intrai,<LineBreak/>
            tant’ era pien di sonno a quel punto<LineBreak/>
            che la verace via abbandonai.<LineBreak/>
        </TextBlock>
    </ScrollViewer>
</Window>

The above XAML generates a Window containing a ScrollViewer. As the ScrollViewer has no dimensions specified it will expand to fill the entire available area and will shrink or grow if you resize the window at run-time. The child control is a TextBlock that shows the first few stanzas of Dante's Inferno.

Try running the program to see the results, which should be similar to those shown below. You can see that a vertical scroll bar is added, allowing you to move up and down through the text. If you make the window tall enough that all of the text is visible, the scroll bar becomes disabled.

A horizontal scroll bar is not present, so the text wraps within the available area. The default options for a ScrollViewer are a visible vertical scroll bar but no visible horizontal scroll bar. This can be changed using the configuration properties of the control.

Controlling Scrollbar Visibility

You can control the visibility of the two scroll bars with the HorizontalScrollBarVisibility and VerticalScrollBarVisibility properties. There are four possible values for each property. When working in .NET code, you set them to a value from the ScrollBarVisibility enumeration. In XAML you can enter the name of the desired constant.

The available values are:

• Visible. The scroll bar is always visible. If the ScrollViewer is large enough that there is no hidden content in the scroll bar's direction, it will be disabled. We've seen this behaviour already with the vertical scroll bar in the first example.
• Hidden. The scroll bar will be hidden so any scrolling must be controlled using a different method. When using Hidden, the ScrollViewer's child control may extend beyond the confines of the ScrollViewer.
• Auto. The scroll bar is made visible only when needed. If the content of the ScrollViewer fits within the available area, the scroll bar will be hidden automatically.
• Disabled. The scroll bar will be hidden. The different between Disabled and Hidden is that, with Disabled, the size of the child control is limited to the size of the ScrollViewer.

For a first demonstration of these options we'll change both properties to Auto. So that we can see the horizontal scrolling we'll also disable the automatic text wrapping of the TextBlock.

Replace the ScrollViewer element in the XAML with the following code.

<ScrollViewer HorizontalScrollBarVisibility="Auto" VerticalScrollBarVisibility="Auto">
    <TextBlock FontSize="15">         
        Inferno · Canto I<LineBreak/>
        <LineBreak/>
        Nel mezzo del cammin di nostra vita<LineBreak/>
        mi ritrovai per una selva oscura,<LineBreak/>
        ché la diritta via era smarrita.<LineBreak/>
        <LineBreak/>
        Ahi quanto a dir qual era è cosa dura<LineBreak/>
        esta selva selvaggia e aspra e forte<LineBreak/>
        che nel pensier rinova la paura!<LineBreak/>
        <LineBreak/>
        Tant’ è amara che poco è più morte;<LineBreak/>
        ma per trattar del ben ch’i’ vi trovai,<LineBreak/>
        dirò de l’altre cose ch’i’ v’ho scorte.<LineBreak/>
        <LineBreak/>
        Io non so ben ridir com’ i’ v’intrai,<LineBreak/>
        tant’ era pien di sonno a quel punto<LineBreak/>
        che la verace via abbandonai.<LineBreak/>
    </TextBlock>
</ScrollViewer>

Try running the updated program. You should see that both scroll bars are initially visible. However, if you make the window large enough that they are unnecessary they will disappear.