Canvas.ZIndex Property

  • Article

Gets or sets a value that represents the z-order rendering behavior of objects in a Canvas.

XAML
<object Canvas.ZIndex="integer" .../>
Scripting
value = object["Canvas.ZIndex"]
object["Canvas.ZIndex"] = value

Property Value

integer

A value that represents the z-order of the object within the Canvas.

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

Remarks

The value of the Canvas.ZIndex property is expressed as any numeric value, positive or negative. Although you can specify the value as a Double, internally the value will be converted to and treated as an integer.

Elements with higher values for Canvas.ZIndex will render on top of elements with a lower ZIndex. The general effect of Canvas.ZIndex is to potentially override the default rendering order that is determined by the order of elements in a Canvas.

You can also set the Canvas.ZIndex value to a negative value, such as "-99", which places the object even farther from the foreground. Canvas.ZIndex values are aligned along the z-axis -- higher values are closer to the foreground; lower values are farther from the foreground. The following illustration shows the relationship of z-order to z-axis.

Relationship of z-order to z-axis

Relationship of z-order to z-axis

Examples

The following XAML example shows how to define two sets of Rectangle objects. The second set of rectangles sets the Canvas.ZIndex property to invert the z-order:

XAML 
<!-- Render rectangles using default z-order (position within the Canvas). -->
<Canvas>
  <Rectangle
    Fill="Maroon" Canvas.Top="20" Canvas.Left="20" Height="100" Width="100" />
  <Rectangle
    Fill="LightBlue" Canvas.Top="40" Canvas.Left="40" Height="100" Width="100" />
  <Rectangle
    Fill="Teal" Canvas.Top="60" Canvas.Left="60" Height="100" Width="100" />
</Canvas>
<!-- Render rectangles using explicit z-order by using Canvas.ZIndex. -->
<Canvas Canvas.Left="200">
  <Rectangle
    Canvas.ZIndex="2"
    Fill="Maroon" Canvas.Top="20" Canvas.Left="20" Height="100" Width="100" />
  <Rectangle
    Canvas.ZIndex="1"
    Fill="LightBlue" Canvas.Top="40" Canvas.Left="40" Height="100" Width="100" />
  <Rectangle
    Canvas.ZIndex="0"
    Fill="Teal" Canvas.Top="60" Canvas.Left="60" Height="100" Width="100" />
</Canvas>

The following image displays the result of the previous XAML content example:

Changing the z-order of objects within a Canvas

The first set of Rectangle objects uses the default z-order rendering of objects, which is based on the position of the child object in the Canvas. The first object in the Canvas is rendered first, then the second object, and so forth. The second set of Rectangle objects uses the Canvas.ZIndex property to override the default z-ordering of objects in the Canvas.

In the second set of Rectangle objects, the first object (the Maroon-colored one) is the highest in the z-order, or closest to the foreground. Its Canvas.ZIndex value is "2", a purely arbitrary value. What is more important is that the value must be greater than any other child object Canvas.ZIndex value in the Canvas. If you do not explicitly set the Canvas.ZIndex value, it defaults to 0.

Applies To

Canvas, Ellipse, Glyphs, Image, InkPresenter, Line, MediaElement, Path, Polygon, Polyline, Rectangle, TextBlock

See Also

Referencing and Modifying Silverlight Objects
Canvas.Left
Canvas.Top