.NET 4.0+

WPF Layout Controls - Viewbox

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

The eleventh part of the Windows Presentation Foundation Fundamentals tutorial continues the examination of the WPF layout controls. This instalment looks at the Viewbox control, which automatically resizes its contents to fit the available area.

Stretch Property

The Viewbox control has no attached properties but does include a couple of important properties that affect its child control. The first of these is Stretch. It modifies the scaling of the Viewbox's child. There are four available options:

• None. If you set the Stretch property to None, the child control is never resized. Depending upon the size of the Viewbox, the child control may be bordered by empty areas or clipped.
• Fill. When set to Fill, the child control is resized to completely fill the Viewbox and is never clipped. The horizontal and vertical scaling may be different, causing the contents of the Viewbox to be distorted.
• Uniform. This is the default option. The child control is resized uniformly to fit either the width or the height of the Viewbox. The image will be the largest possible size without clipping. Empty bars may be present at either the top and bottom or at the sides of the child control.
• UniformToFill. The fourth option scales the height and width of the child control by the same amount, ensuring no distortion. The child control is sized to completely fill the available area, even if this means that it will be clipped.

To demonstrate the options, replace the entire XAML for the window with that shown below. This creates a Grid containing four Viewboxes, each containing a similarly sized button but using a different Stretch option.

<Window x:Class="ViewboxDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Viewbox Demo"
        Width="250"
        Height="200">
    <Grid>
        <Grid.ColumnDefinitions>
            <ColumnDefinition/>
            <ColumnDefinition/>
        </Grid.ColumnDefinitions>
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition/>
        </Grid.RowDefinitions>

        <Viewbox Stretch="None">
            <Button Content="None" Width="60"/>
        </Viewbox>

        <Viewbox Stretch="Fill" Grid.Column="1">
            <Button Content="Fill" Width="60"/>
        </Viewbox>

        <Viewbox Stretch="Uniform" Grid.Row="1">
            <Button Content="Uniform" Width="60"/>
        </Viewbox>

        <Viewbox Stretch="UniformToFill" Grid.Row="1" Grid.Column="1">
            <Button Content="U.Fill" Width="60"/>
        </Viewbox>
    </Grid>
</Window>

Executing the code gives the following results. Try resizing the window to see how each button behaves.

StretchDirection Property

The second interesting property is StretchDirection. This allows you to specify whether you wish to limit the scaling of the control. You can elect to only allow it to grow, only allow it to shrink or to permit both options. The three possible property values are:

• UpOnly. If the Viewbox is made larger than the desired size of the child control, the child will be made larger too. If it is made smaller, the child will not shrink and will instead be clipped.
• DownOnly. The Viewbox will be permitted to make the child control smaller than its default size. Increasing the size will cause empty areas around the child control.
• Both. The default option permits the child control to either increase or decrease in size.