.NET 4.0+

WPF Media Controls - Image

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

The eighty-fourth part of the Windows Presentation Foundation Fundamentals tutorial begins to look at the media controls provided by WPF. These allow multimedia content such as images, sounds and video clips to be included in WPF applications.

Image

The Image control is the first of the WPF media controls. It allows you to include a bitmap picture in your WPF application, which you might use for simple image display or as the content of other controls, such as Buttons in a ToolBar. In this article we'll use the control to show images and demonstrate its key properties.

To begin, we need a sample solution. Create a new WPF application project in Visual Studio, naming the project, "ImageDemo". Once ready, add an image to the WPF project by right-clicking its name in the Solution Explorer, choosing "Add" and then "Existing Item". In the dialog box, change the file type to allow you to find images, then locate and load an image file from your disk. If you do not have a suitable image, download the sample code using the link at the start of this article. The sample project includes a JPEG image of a fish.

With the image added to the project, replace the XAML of the main window with the code below. Note that the Image control in the XAML includes the name of the image in its Source property. In the sample, this is, "Fish.jpg". Source is the property that allows you to identify the image to display. Change the name to match that of the file that you added to the project in the previous step.

<Window x:Class="ImageDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Image Demo"
        Height="200"
        Width="200">
    <Grid>
        <Image Source="Fish.jpg"/>
    </Grid>
</Window>

Run the program to see the results. You should see the image displayed within the window.

Image Stretching

When you run the program you will see that the image resizes automatically to fill its parent control. In this case the parent is the Grid. However, as the Grid fills the Window, the image fits to the window. If you resize the window you will see that the image is scaled accordingly.

By default, the aspect ratio for the picture is retained. If the image does not fit perfectly within its parent, there will be empty bars around the image, either above and below or to the sides. In the screen shot above, these appear as white bars above and below the fish photograph.

You can modify the resizing behaviour using the Stretch property. This can be set to one of four values, each defined in the Stretch enumeration. The options are:

• None. The image size matches that of the original file and is never resized. In most cases the bitmap will be recreated pixel for pixel. However, if the image was saved with a non-standard dots per inch (DPI) value, it may appear larger or smaller than anticipated. You can fix this by opening the image in a drawing package and saving it again without the DPI setting.
• Uniform. This is the default option. The image is resized proportionally to retain the aspect ratio. It will fill the parent control either horizontally or vertically, with empty areas if necessary.
• UniformToFill. This option is similar to Uniform. The height and width are increased or decreased by the same proportion to fill the parent control. With this setting, the entire parent control is filled with no empty areas. If necessary, the image is cropped.
• Fill. The Fill option stretches the image to fill its parent completely without any cropping. The aspect ratio of the image is not preserved so the image can appear stretched.

To demonstrate, replace the XAML of the Grid control with the following code. This creates a window containing four copies of the picture. Each Image control uses a different Stretch option.

<Grid>
    <Grid.ColumnDefinitions>
        <ColumnDefinition/>
        <ColumnDefinition/>
    </Grid.ColumnDefinitions>
    <Grid.RowDefinitions>
        <RowDefinition/>
        <RowDefinition/>
    </Grid.RowDefinitions>

    <Image Source="Fish.jpg" Stretch="None"/>
    <TextBlock Foreground="Red">None</TextBlock>
        
    <Image Grid.Column="1" Source="Fish.jpg" Stretch="Uniform"/>
    <TextBlock Grid.Column="1" Foreground="Red">Uniform</TextBlock>
        
    <Image Grid.Row="1" Source="Fish.jpg" Stretch="UniformToFill"/>
    <TextBlock Grid.Row="1" Foreground="Red">UniformToFill</TextBlock>
        
    <Image Grid.Column="1" Grid.Row="1" Source="Fish.jpg" Stretch="Fill"/>
    <TextBlock Grid.Column="1" Grid.Row="1" Foreground="Red">Fill</TextBlock>
</Grid>

Run the program and try resizing the window to see the results. The window should appear similar to that shown below. You can see that the image at the top left is not scaled at all so is cropped. The top-right and bottom-left images are scaled proportionally, with the Uniform option adding empty, white areas and the UniformToFill cropping the image. The Image with the Fill setting for the Stretch property fills the grid cell without cropping but the image is distorted.

Stretch Direction

There is a second property that you can use to control the way in which images are scaled. This is the StretchDirection property, which accepts a value from the StretchDirection property. This member allows you to prevent images from becoming larger or smaller. The three possible values are:

• UpOnly. The image can be scaled upwards but will never become smaller than its native size. If the parent control is smaller than the image, the picture is cropped. If the parent control is larger than the image, the picture can grow according to the Stretch property value.
• DownOnly. The image can be scaled downwards but cannot grow in size. If the parent control is larger than the image, the picture will be surrounded by empty bars. If the parent control is smaller than the picture, it will shrink according to the Stretch option used.
• Both. This is the default option. The image will grow and shrink as normal.