.NET 4.0+

WPF Base Classes - FrameworkElement - Visibility

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

The twenty-fifth part of the Windows Presentation Foundation Fundamentals tutorial continues to look at the FrameworkElement type. This article examines the visibility methods and events, which allow items in scrollable areas to be brought into view.

FrameworkElement

We started to look at the FrameworkElement class in the previous article in the tutorial. This class is a base class that is inherited by all of the layout controls and other WPF controls. FrameworkElement provides functionality related to the logical tree, styling, data binding and lifetime events.

In this article we will look at a method and an event that are provided by FrameworkElement. The method can be used against controls that have been positioned within a scrollable area, such as a ScrollViewer. When you execute it, it attempts to scroll that area in order to make the control wholly or partially visible. This is very useful when you have a large number of controls, some of which may be outside of the visible area of a ScrollViewer, and you wish to show the user a specific item. The event is related to the method.

To demonstrate the members we need a sample project. Create a new WPF application project in Visual Studio. Name the project, "FrameworkElementVisibilityDemo". Once the project has loaded, replace the XAML of the main window with the following code:

<Window x:Class="FrameworkElementVisibilityDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="FrameworkElement Demo"
        Width="250"
        Height="200">
    <Grid>
        <DockPanel>
            <StackPanel DockPanel.Dock="Top" Orientation="Horizontal">
                <Button Width="70">Top</Button>
                <Button Width="70">Middle</Button>
                <Button Width="70">Bottom</Button>
            </StackPanel>

            <ScrollViewer>
                <StackPanel Margin="0 30 0 0">
                    <Border Name="Top"
                            BorderBrush="Red"
                            BorderThickness="5"
                            Height="100">
                        <Label HorizontalAlignment="Center"
                               VerticalAlignment="Center"
                               Content="Top"/>
                    </Border>

                    <Border Name="Middle"
                            BorderBrush="Orange"
                            BorderThickness="5"
                            Height="100">
                        <Label HorizontalAlignment="Center"
                               VerticalAlignment="Center"
                               Content="Middle"/>
                    </Border>

                    <Border Name="Bottom"
                            BorderBrush="Green"
                            BorderThickness="5"
                            Height="100">
                        <Label HorizontalAlignment="Center"
                               VerticalAlignment="Center"
                               Content="Bottom"/>
                    </Border>
                </StackPanel>
            </ScrollViewer>
        </DockPanel>
    </Grid>
</Window>

The XAML includes several controls. Key are the three Borders within the ScrollViewer. We'll be moving these into view using C# code in events attached to the three buttons. If you run the project you'll see that one of the borders is completely out of view and one is clipped by the bottom edge of the ScrollViewer.

BringIntoView Method

The basic version of the BringIntoView method has no parameters. When executed against a control, the layout system attempts to make the control visible. This only works if the control is positioned within a scrollable area that is currently able to be scrolled. On execution, the logical tree is examined to find a suitable scrollable area that houses the control. This area is then scrolled just enough to show the entire child control. If the control is already completely in view, the method has no effect.

We can demonstrate this by adding events to each of the three buttons. Replace the XAML for the buttons with the code below to add the event definitions.

<Button Click="Top_Click" Width="70">Top</Button>
<Button Click="Middle_Click" Width="70">Middle</Button>
<Button Click="Bottom_Click" Width="70">Bottom</Button>

You can now add the C# code behind the window. We'll make each button bring one of the Borders into view. Add the following source code:

private void Top_Click(object sender, RoutedEventArgs e)
{
    Top.BringIntoView();
}

private void Middle_Click(object sender, RoutedEventArgs e)
{
    Middle.BringIntoView();
}

private void Bottom_Click(object sender, RoutedEventArgs e)
{
    Bottom.BringIntoView();
}

Try running the program and clicking each of the buttons. Note how each button causes scrolling by the minimum number of pixels to display the corresponding border. This is particularly noticeable with the border in the middle. If you scroll to the top of the available area, clicking the middle button moves the border upwards so that it appears at the bottom of the ScrollViewer. If you scroll to the bottom before clicking the button, the border is moved downwards until it reaches the top of the scrolling area.