Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

TileBrush.Stretch Property

Gets or sets a value that specifies how the content of this TileBrush stretches to fit its tiles. This is a dependency property.

Namespace: System.Windows.Media
Assembly: PresentationCore (in presentationcore.dll)
XML Namespace:  http://schemas.microsoft.com/winfx/2006/xaml/presentation

public Stretch Stretch { get; set; }
/** @property */
public Stretch get_Stretch ()

/** @property */
public void set_Stretch (Stretch value)

public function get Stretch () : Stretch

public function set Stretch (value : Stretch)

<object Stretch="Stretch" .../>

Property Value

A value that specifies how this TileBrush content is projected onto its base tile. The default value is Fill.

Identifier field

StretchProperty

Metadata properties set to true

None

The Stretch property accepts the following values, which the Stretch enumeration defines:

  • None: The TileBrush content does not stretch to fill the tile.

  • Uniform: The TileBrush content is scaled to fit the tile dimensions. However, the aspect ratio of the content is preserved.

  • UniformToFill: The TileBrush content is scaled so that it completely fills the output area but preserves its original aspect ratio.

  • Fill: The TileBrush content is scaled to fit the tile. Because the content's height and width are scaled independently, the original aspect ratio of the content might not be preserved. That is, the TileBrush content might be distorted in order to completely fill the output tile.

The following image illustrates the different Stretch settings.

Different stretch settings


Different TileBrush Stretch settings

Note that you specify the dimensions of TileBrush content by using the Viewbox property; you specify the position and size of the TileBrush base tile by using the Viewport property.

Viewbox Clipping

TileBrush contents are never clipped to the Viewbox. However, TileBrush contents are clipped to the edges of the Viewport, which sets the dimensions for the TileBrush base tile.

The following illustration shows the effect of different Stretch settings on a TileBrush that has a Viewbox that is smaller than its Viewport. The parts of the image that are outside the Viewbox are tinted gray.

TileBrush with different Stretch settings


TileBrush with different Stretch settings

This example shows how to use the Stretch property of an ImageBrush in order to preserve the aspect ratio of the image.

By default, when you use an ImageBrush to paint an area, its content is stretched to completely fill the output area. When the output area and the image have different aspect ratios, the image is distorted by this stretching.

To make an ImageBrush preserve the aspect ratio of its image, set the Stretch property to Uniform or UniformToFill.

The following example uses two ImageBrush objects to paint two rectangles. Each rectangle is 300 by 150 pixels and each contains a 300 by 300 pixel image. The Stretch property of the first brush is set to Uniform, and the Stretch property of the second brush is set to UniformToFill.

using System;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Media.Imaging;
using System.Windows.Media;
using System.Windows.Shapes;

namespace Microsoft.Samples.Graphics.UsingImageBrush
{
    /// <summary>
    /// Demonstrates different ImageBrush Stretch settings.
    /// </summary>
    public class StretchModes : Page
    {
        public StretchModes()
        {

            // Create an ImageBrush with its Stretch
            // property set to Uniform. The image it
            // contains will be expanded as much as possible
            // to fill the output area while still
            // preserving its aspect ratio.
            ImageBrush uniformBrush = new ImageBrush();
            uniformBrush.ImageSource = 
                new BitmapImage(new Uri("sampleImages\\square.jpg", UriKind.Relative));
            uniformBrush.Stretch = Stretch.Uniform;

            // Freeze the brush (make it unmodifiable) for performance benefits.
            uniformBrush.Freeze();

            // Create a rectangle and paint it with the ImageBrush.
            Rectangle rectangle1 = new Rectangle();
            rectangle1.Width = 300;
            rectangle1.Height = 150;
            rectangle1.Stroke = Brushes.MediumBlue;
            rectangle1.StrokeThickness = 1.0;
            rectangle1.Fill = uniformBrush;

            // Create an ImageBrush with its Stretch
            // property set to UniformToFill. The image it
            // contains will be expanded to completely fill
            // the rectangle, but its aspect ratio is preserved.
            ImageBrush uniformToFillBrush = new ImageBrush();
            uniformToFillBrush.ImageSource =
                new BitmapImage(new Uri("sampleImages\\square.jpg", UriKind.Relative));
            uniformToFillBrush.Stretch = Stretch.UniformToFill;

            // Freeze the brush (make it unmodifiable) for performance benefits.
            uniformToFillBrush.Freeze();

            // Create a rectangle and paint it with the ImageBrush.
            Rectangle rectangle2 = new Rectangle();
            rectangle2.Width = 300;
            rectangle2.Height = 150;
            rectangle2.Stroke = Brushes.MediumBlue;
            rectangle2.StrokeThickness = 1.0;
            rectangle2.Margin = new Thickness(0, 10, 0, 0);
            rectangle2.Fill = uniformToFillBrush;

            StackPanel mainPanel = new StackPanel();
            mainPanel.Children.Add(rectangle1);
            mainPanel.Children.Add(rectangle2);

            Content = mainPanel;
            Background = Brushes.White;
            Margin = new Thickness(20);
            Title = "ImageBrush Stretch Modes";


        }
    }
}

<!-- Demonstrates different ImageBrush Stretch settings.-->
<Page 
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:PresentationOptions="http://schemas.microsoft.com/winfx/2006/xaml/presentation/options" 
  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
  mc:Ignorable="PresentationOptions"
  Background="White" Margin="20"
  Title="ImageBrush Stretch Modes">
  <StackPanel>

    <!-- The ImageBrush in this example has its
         Stretch property set to Uniform. As a result,
         the image it contains is expanded as much as possible
         to fill the rectangle while
         still preserving its aspect ratio.-->
    <Rectangle
      Width="300" Height="150" 
      Stroke="MediumBlue" StrokeThickness="1">
      <Rectangle.Fill>
        <ImageBrush
          Stretch="Uniform" ImageSource="sampleImages\square.jpg"
          PresentationOptions:Freeze="True" />
      </Rectangle.Fill>
    </Rectangle>

    <!-- The ImageBrush in this example has its
         Stretch property set to UniformToFill. As a result,
         the image is expanded to completely fill
         the rectangle, but its aspect ratio is preserved.-->
    <Rectangle
      Width="300" Height="150"
      Stroke="MediumBlue" StrokeThickness="1"
      Margin="0,10,0,0">
      <Rectangle.Fill>
        <ImageBrush 
          Stretch="UniformToFill" ImageSource="sampleImages\square.jpg" 
          PresentationOptions:Freeze="True" />
      </Rectangle.Fill>
    </Rectangle>
  </StackPanel>
</Page>

The following illustration shows the output of the first brush, which has a Stretch setting of Uniform.

ImageBrush with Uniform stretching

The next illustration shows the output of the second brush, which has a Stretch setting of UniformToFill.

ImageBrush with UniformToFill stretching

Note that the Stretch property behaves identically for the other TileBrush objects, that is, for DrawingBrush and VisualBrush. For more information about ImageBrush and the other TileBrush objects, see Painting with Images, Drawings, Visuals, and Patterns.

Note also that, although the Stretch property appears to specify how the TileBrush content is stretched to fit its output area, it actually specifies how the TileBrush content is stretched to fill its base tile. For more information, see TileBrush.

This code example is part of a larger example that is provided for the ImageBrush class. For the complete sample, see ImageBrush Sample.

More Code

How to: Set the Horizontal and Vertical Alignment of a TileBrush

This example shows how to control the horizontal and vertical alignment of content in a tile. To control the horizontal and vertical alignment of a TileBrush, use its AlignmentX and AlignmentY properties.

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft