Export (0) Print
Expand All

Image Class

Represents a control that displays an image.

Namespace: System.Windows.Controls
Assembly: PresentationFramework (in presentationframework.dll)
XML Namespace:  http://schemas.microsoft.com/winfx/2006/xaml/presentation

[LocalizabilityAttribute(LocalizationCategory.None, Readability=Readability.Unreadable)] 
public class Image : FrameworkElement, IUriContext
/** @attribute LocalizabilityAttribute(LocalizationCategory.None, Readability=Readability.Unreadable) */ 
public class Image extends FrameworkElement implements IUriContext
LocalizabilityAttribute(LocalizationCategory.None, Readability=Readability.Unreadable) 
public class Image extends FrameworkElement implements IUriContext

The Image class enables you to load the following image types: .bmp, .gif, .ico, .jpg, .png, .wdp, and .tiff.

When displaying a multiframe image, only the first frame is displayed. The animation of multiframe images is not supported by the Image control.

Until the image content is loaded, the ActualWidth and ActualHeight of the control will report as zero, because the image content is used to determine the final size and location of the control.

For a fixed size control, the Width and/or Height properties can be set. However, to preserve the media's aspect ratio, set the Width or Height properties but not both.

This example shows how to include images in an application using the Image element.

The following example shows how to render an image 200 pixels wide. In this Extensible Application Markup Language (XAML) example, both attribute syntax and property tag syntax are used to define the image. For more information on attribute syntax and property syntax, see Properties Overview. A BitmapImage is used to define the image's source data and is explicitly defined for the property tag syntax example. In addition, the DecodePixelWidth of the BitmapImage is set to the same width as the Width of the Image. This is done to ensure that the minimum amount of memory is used rendering the image.

Note: In general, if you want to specify the size of a rendered image, specify only the Width or the Height but not both. By only specifying one, the image is allowed to preserve its aspect ratio. Otherwise the image may unexpectedly appear stretched or warped.

Performance Note: When you specify the size of an image with either Width or Height, you should also set either DecodePixelWidth or DecodePixelHeight to the same respective size.

<!-- Simple image rendering. However, rendering an image this way may not
     result in the best use of application memory. See markup below which
     creates the same end result but using less memory. -->
<Image Width="200" 
Source="C:\Documents and Settings\All Users\Documents\My Pictures\Sample Pictures\Water Lilies.jpg"/>

<Image Width="200">
  <Image.Source>
    <!-- To save significant application memory, set the DecodePixelWidth or  
     DecodePixelHeight of the BitmapImage value of the image source to the desired 
     height and width of the rendered image. If you don't do this, the application will 
     cache the image as though it were rendered as its normal size rather then just 
     the size that is displayed. -->
    <!-- Note: In order to preserve aspect ratio, only set either DecodePixelWidth
         or DecodePixelHeight but not both. -->
    <BitmapImage DecodePixelWidth="200"  
     UriSource="C:\Documents and Settings\All Users\Documents\My Pictures\Sample Pictures\Water Lilies.jpg" />
  </Image.Source>
</Image>

The following example shows how to render an image 200 pixels wide using code.

NoteNote:

Setting BitmapImage properties must be done within a BeginInit and EndInit block.

// Create Image Element
Image myImage = new Image();
myImage.Width = 200;
         
// Create source
BitmapImage myBitmapImage = new BitmapImage();

// BitmapImage.UriSource must be in a BeginInit/EndInit block
myBitmapImage.BeginInit();
myBitmapImage.UriSource = new Uri(@"C:\Documents and Settings\All Users\Documents\My Pictures\Sample Pictures\Water Lilies.jpg");

// To save significant application memory, set the DecodePixelWidth or  
// DecodePixelHeight of the BitmapImage value of the image source to the desired 
// height or width of the rendered image. If you don't do this, the application will 
// cache the image as though it were rendered as its normal size rather then just 
// the size that is displayed.
// Note: In order to preserve aspect ratio, set DecodePixelWidth
// or DecodePixelHeight but not both.
myBitmapImage.DecodePixelWidth = 200;
myBitmapImage.EndInit();
//set image source
myImage.Source = myBitmapImage;

The following example shows how to render an image 200 pixels wide using code.

NoteNote:

Setting or modifying BitmapImage properties must be done within a BeginInit and EndInit block.

// Create Image Element
Image myImage = new Image();
myImage.Width = 200;
         
// Create source
BitmapImage myBitmapImage = new BitmapImage();

// BitmapImage.UriSource must be in a BeginInit/EndInit block
myBitmapImage.BeginInit();
myBitmapImage.UriSource = new Uri(@"C:\Documents and Settings\All Users\Documents\My Pictures\Sample Pictures\Water Lilies.jpg");

// To save significant application memory, set the DecodePixelWidth or  
// DecodePixelHeight of the BitmapImage value of the image source to the desired 
// height or width of the rendered image. If you don't do this, the application will 
// cache the image as though it were rendered as its normal size rather then just 
// the size that is displayed.
// Note: In order to preserve aspect ratio, set DecodePixelWidth
// or DecodePixelHeight but not both.
myBitmapImage.DecodePixelWidth = 200;
myBitmapImage.EndInit();
//set image source
myImage.Source = myBitmapImage;

The following example applies each of the available Stretch enumerations to an Image.

The following image shows the output from the example and demonstrates the affect the different Stretch settings have when applied to an image.

<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >
  <DockPanel>

    <Border DockPanel.Dock="Top" Background="Black">
      <TextBlock Foreground="White" HorizontalAlignment="Stretch" FontSize="20">
        Stretching an Image
      </TextBlock>
    </Border>

    <Grid Name="simpleGrid" Background="{StaticResource CheckeredBrushResource}" 
       Margin="10" 
       ShowGridLines="True"
       VerticalAlignment="Center"
       HorizontalAlignment="Center">
      <Grid.ColumnDefinitions>
        <ColumnDefinition Width="175" />
        <ColumnDefinition Width="175" />
        <ColumnDefinition Width="175" />
        <ColumnDefinition Width="175" />
      </Grid.ColumnDefinitions>
      <Grid.RowDefinitions>
        <RowDefinition />
        <RowDefinition Height="200"/>
      </Grid.RowDefinitions>
      <!-- Labels -->
      <TextBlock Style="{StaticResource Header1}" 
        Grid.Column="0" Grid.Row="0">None</TextBlock>
      <TextBlock Style="{StaticResource Header1}" 
        Grid.Column="1" Grid.Row="0">Uniform</TextBlock>
      <TextBlock Style="{StaticResource Header1}" 
        Grid.Column="2" Grid.Row="0">UniformToFill</TextBlock>
      <TextBlock Style="{StaticResource Header1}"
        Grid.Column="3" Grid.Row="0">Fill</TextBlock>
      <Border Grid.Column="0" Grid.Row="1" BorderThickness="1" BorderBrush="Black">
        <!-- None: Image is not scaled. If image is larger than the
             output area, the image will be cropped to the size of the output area.-->
        <Image
          Source="sampleImages/gecko.jpg" 
          Stretch="None" />
      </Border>
      <Border Grid.Column="1" Grid.Row="1" BorderThickness="1" BorderBrush="Black">
        <!-- Uniform: Scale to fit output area.
             Aspect ratio is preserved.-->
        <Image
          Source="sampleImages/gecko.jpg" 
          Stretch="Uniform" />
      </Border>
      <Border Grid.Column="2" Grid.Row="1" BorderThickness="1" BorderBrush="Black">
        <!-- UniformToFill: Scale to completely fill output area.
             Aspect ratio is preserved. Cropping may occur.-->
        <Image  
          Source="sampleImages/gecko.jpg" 
        Stretch="UniformToFill" />
      </Border>
      <Border Grid.Column="3" Grid.Row="1" BorderThickness="1" BorderBrush="Black">
      <!-- Fill: Scale to completely fill output area.
             Aspect ratio may not be preserved.-->
      <Image 
        Source="sampleImages/gecko.jpg" 
        Stretch="Fill" />
      </Border>
    </Grid>
  </DockPanel>
</Page>

More Code

How to: Crop an Image

This example shows how to crop an image using CroppedBitmap.

How to: Rotate an Image

This example shows how to rotate an image 90 degrees by using a Rotation property of a BitmapImage.

How to: Convert an Image to Greyscale

This example shows how to convert an image to grayscale using FormatConvertedBitmap.

How to: Use a Drawing as an Image Source

This example shows how to use a Drawing as the Source for an Image control. To display a Drawing with an Image control, use a DrawingImage as the Image control's Source and set the DrawingImage object's DrawingImage.Drawing property to the drawing you want to display.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

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

Community Additions

ADD
Show:
© 2014 Microsoft