This article is compatible with the latest version of Silverlight.
Introduction
In this tutorial we will provide brief introduction in the usage of the image control. It’s not very complicated, but there are a few interesting things we can find out about it.
Overview
For our examples we will use the turtle from the Sample Images in Windows. Here is the first example:
<Grid x:Name="Layout" Background="Black" Width="300" Height="200">
<Image x:Name="MyImage" Source="/Images/GiantSeaTurtle.jpg"></Image>
</Grid>
In it we use the Source property of the Image control. In this property we can set the path to the image we want to place in our application. Note: My directory “Images” is placed in the “ClientBin” directory. In case you want it to be in your project’s directory, the path should look like that: "../Images/GiantSeaTurtle.jpg".
We continue with the Stretch property of the Image control. It can be set to one of the following values: Fill, None, Uniform and UniformToFill. The default one is Uniform. We will examine every one of these properties.
Let’s begin with the Fill option:
<Image x:Name="MyImage" Source="/Images/GiantSeaTurtle.jpg"
Stretch="Fill"></Image>
It can be observed that when we use Fill the image is scaled in such a way that it takes the whole place the Grid provides for it. In this case the initial proportion of the image is not kept.
Next, we take a look at the None option:
<Image x:Name="MyImage" Source="/Images/GiantSeaTurtle.jpg"
Stretch="None"></Image>
With this property the image is not scaled. The grid is smaller than the image, so the image is cut. By default the Image control is top left aligned. Still, if we use the VerticalAlignment and HorizontalAlignment, we can change the position of the unscaled image. For example, the HorizontalAlignment can be set to Right and the VerticalAlignment to Center:
<Image x:Name="MyImage" Source="/Images/GiantSeaTurtle.jpg"
Stretch="None" VerticalAlignment="Center"
HorizontalAlignment="Right"></Image>
So this is the None option.
Third, we will examine the Uniform option:
<Image x:Name="MyImage" Source="/Images/GiantSeaTurtle.jpg"
Stretch="Uniform"></Image>
That’s the default value of the Stretch property. Not only does the image fit to the Grid, but also the proportion is kept. Depending on where we have black lines we can use the HorizontalAlignment or VerticalAlignment property of the control to align the Image in the Grid.
Finally, we will pay attention to the UniformToFill option:
<Image x:Name="MyImage" Source="/Images/GiantSeaTurtle.jpg"
Stretch="UniformToFill"></Image>
You can see that the image is cut on the bottom, scaled, it fills the Grid and the proportion of the image is kept. You can use the VerticalAlignment or HorizontalAlignment property (depending on the direction in which the image is cut) to align the image in the Grid.
If you use the UniformToFill option, the image fills the Grid and it looks nice and normal. On the one hand, you can lose parts of the image, if the image proportion does not match the proportions of the layout control (in our case a Grid). But on the other hand if they match then the Uniform, Fill and UniformToFill will have identical behavior. If the image has the same size as the layout control, all options of the Stretch property will behave alike.
Note: If you set the Width and Height properties of the Image control, the Stretch property will have no effect over the displaying of the image.
Image.Clip
This is another interesting thing that we can use with our Image control. With the “Clip” we can make a specific part of the image visible. It’s also possible to add an animation in it, but this will be an object of one of the upcoming articles (they will examine the Clip and the Geometry classes in details). In our case we’ll use Ellipse figure for the Clip of our image. Refer to the following:
<Image x:Name="MyImage" Source="/Images/GiantSeaTurtle.jpg"
Stretch="UniformToFill">
<Image.Clip>
<EllipseGeometry x:Name="Ellipse" RadiusX="150" RadiusY="100"
Center="150,100"/>
</Image.Clip>
</Image>
We use the RadiusX and RadiusY properties of the EllipseGeometry to set the radiuses of the ellipse, and the Center property to position it over the image.
Conclusion
This article is just a brief tutorial that includes the key features of the Image control. It targets the developer who has just started with the Silverlight controls. Any comments are welcome.