Article
06/13/2011

Canvas.ZIndex

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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

<object Canvas.ZIndex="integer"  .../>

value = object["Canvas.ZIndex"]
object["Canvas.ZIndex"] = value

Property Value

Type: integer

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

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

Managed Equivalent

ZIndex

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 decimal, internally the value will be converted to, and treated as, an integer.

Elements that have higher values for Canvas.ZIndex will render on top of elements that have a lower Canvas.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.

Note the script syntax, which resembles an indexer or array syntax. The ["ownerType.propertyName"] form (with no dot separating this property form and the target object for getting or setting) is necessary to get or set an attached property such as Canvas.ZIndex in script.

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

z-order example

Example

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.

<!-- 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 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, followed by the second object, and so on. 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". This is a purely arbitrary value, but it 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.