The Composing a XAML Clip Art Scene posting showed how you could layer multiple drawing objects in an XAML file. The sample XAML file in that posting used the default z-order behavior of objects in a collection. One of the changes made in WPF Beta 2 is the introduction of the ZIndex attached property, which allows you to explicitly set the z-order of objects in the child collection of Panel-derived objects, such as Canvas, Grid, and StackPanel objects.

Using the ZIndex Property
Try running the following code in XAMLPad:

<Canvas Background="Ivory"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation">


 
<Canvas>
    <Rectangle Height="60" Width="60" Fill="Gold"/>
    <Rectangle Height="50" Width="70" Fill="Coral"/>
    <Rectangle Height="40" Width="80" Fill="Teal"/>
    <Rectangle Height="30" Width="90" Fill="Black"/>
  </Canvas>

  <Canvas Canvas.Left="120">
    <Rectangle Canvas.ZIndex="99" Height="60" Width="60" Fill="Gold"/>
    <Rectangle Canvas.ZIndex="98" Height="50" Width="70" Fill="Coral"/>
    <Rectangle Canvas.ZIndex="97" Height="40" Width="80" Fill="Teal"/>
    <Rectangle Canvas.ZIndex="96" Height="30" Width="90" Fill="Black"/>
  </Canvas>

</Canvas>

Notice how the second set of Rectangle objects is layered in reverse z-order from the first set of Rectangle objects:

Default and explicit Z-order

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

In the second set of Rectangle objects, I want to ensure that the first object (the Gold-colored one) is the highest in the z-order, or closest to the foreground.  I have defined its ZIndex value as "99" -- a purely arbitrary value. What is more important is that the value must be greater than any other child object ZIndex value in the Canvas collection. If you do not explicitly set the ZIndex value, it defaults to 0.

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

Z-order aligns along the z-axis
Relationship of z-order to z-axis

Accessing the ZIndex Value at Run Time
To retrieve the value of the ZIndex property, use the GetZIndex method of the Panel-derived object:

int zOrder = Canvas.GetZIndex(object);

Likewise, to set the value of the ZIndex property, use the SetZIndex method:

Canvas.SetZIndex(object, (int)99);

A key performance issue is that changing the ZIndex property of a child object does not change its position within the collection. The ordering within the collection remains the same.

Prior to the introduction of the ZIndex property, you would have had to do the following to change the z-order of objects in a collection:

  1) Remove the child object from the collection.
  2) Re-insert the child object into the collection
      at the desired position.

In short, the addition of the ZIndex property is a much easier and more efficient way to change z-order!

Enjoy,
Lorin


About Us

We are the Windows Presentation Foundation SDK writers and editors.