Share via

Stretch Property (Image)

  • Article

Gets or sets a value that describes how an Image should be stretched to fill the destination rectangle.

XAML
<object Stretch="Stretch" .../>
Scripting
value = object.Stretch
object.Stretch = value

Property Value

Stretch

A value of the Stretch enumeration that specifies how the source image is applied if the Height and Width of the Image are specified and are different than the source image's height and width.

This property is read/write. The default value is Uniform.

Remarks

A value of Fill will cause your image to stretch 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 Image preserve the aspect ratio of the image, set this property to Uniform (the default) or UniformToFill. Alternatively, you can leave Height and Width of the Image unset, which will display the image source at its true resolution, although this results in loss of control over the element sizing in XAML.

Examples

Setting the Height and Width creates a containing rectangular area that the image is displayed in. You can specify how the image fills this containing area using the Stretch property. The Stretch property accepts the following values, which the Stretch enumeration defines:

  • None: The image does not stretch to fill the output dimensions.

  • Uniform: This is the default value. The image is scaled to fit the output dimensions. However, the aspect ratio of the content is preserved.

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

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

The following image illustrates the different Stretch settings.

Different Stretch settings

The example below shows how to display an Image that fills a 300 by 300 pixel output area but preserves its original aspect ratio by setting the Stretch property to UniformToFill.

XAML 
<Canvas xmlns="https://schemas.microsoft.com/client/2007"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
  Width="300" Height="300" x:Name="rootCanvas" Background="Gray">
  
  <Image Source="myImage.jpg" Stretch="UniformToFill" Width="300" Height="300" />
</Canvas>

Note   When only one constraint attribute is set (for example Height), the other attribute (in this case Width) is automatically calculated based upon the aspect ratio of the natural image. Because of this behavior, setting the Stretch property will not change the behavior unless it is set to None.

Applies To

Image

See Also

ImageBrush