| -api-id | -api-type |
|---|---|
T:Windows.UI.Xaml.Controls.Canvas |
winrt class |
Defines an area within which you can explicitly position child objects, using coordinates that are relative to the Canvas area.
<Canvas ...>
oneOrMoreUIElements
</Canvas>
-or-
<Canvas .../>Canvas is a layout panel that supports absolute positioning of child elements relative to the top left corner of the canvas.
A Canvas is one of the Panel elements that enable layout. Canvas uses absolute positioning as its layout technique for its contained child elements. Each child element is rendered within the Canvas area. You control the positioning of elements inside the Canvas by specifying x and y coordinates. These coordinates are in pixels. The x and y coordinates are often specified by using the Canvas.Left and Canvas.Top attached properties. Canvas.Left specifies the object's distance from the left side of the containing Canvas (the x-coordinate), and Canvas.Top specifies the object's distance from the top of the containing Canvas (the y-coordinate).
Note
Because absolute positioning does not take into account the size of the app window, scaling, or other user-selected sizing, using a container element that adapts to different orientations and screen settings, such as Grid or StackPanel, is often a better choice than using Canvas. For more information, see Define layouts with XAML.
You can nest Canvas objects. When you nest objects, the coordinates used by each object are relative to its immediate containing Canvas.
Each child object of a Canvas must be a UIElement. In XAML, you declare child objects as content of a Canvas object element. In code, you can manipulate the collection of Canvas child objects by getting the collection that is accessed by the Children property.
In many cases, a Canvas is used solely as a container for other objects and does not have any visible properties. A Canvas and its children (if any) are not visible if any of these conditions are true:
- The Visibility property is set to Collapsed.
- The Opacity property of the Canvas is 0.
The children of a Canvas (if any) are still visible even if the Canvas has any of these conditions:
- The Background property of the Canvas is null.
- The Height or Width property of the Canvas is 0.
A Canvas with no children and with a default Height and Width of Auto doesn't have dimensions. This is also the case if the Canvas has children but all the children have Visibility of Collapsed, or zero Height or Width.
Canvas is the host service class for several XAML attached properties.
In order to support XAML processor access to the attached properties, and also to expose equivalent get and set operations to code, each XAML attached property has a pair of Get and Set accessor methods. Another way to get or set the value in code is to use the dependency property system, calling either GetValue or SetValue and passing the identifier field as the dependency property identifier.
| Attached property | Description |
|---|---|
| Left | Gets or sets the distance between the left side of an object and the left side of its parent Canvas.
|
| Top | Gets or sets the distance between the top of an element and the top of its parent Canvas.
A Canvas.Top value is interpreted by the most immediate parent Canvas element from where the value is set. The value is used along with Canvas.Left to specify the layout characteristics of each child element of a Canvas. |
| ZIndex | Gets or sets the Z-order of an element when that element is presented in its parent Canvas layout container.
You typically use values 0 and greater but negative values are permitted. A negative value, such as -99, places the object even farther from the foreground than any default value. A value is interpreted by the most immediate parent Canvas element from where the value is set. The value is used to explicitly define the draw order in cases where child elements overlap. |
Tip
For more info, design guidance, and code examples, see Canvas.
[!div class="nextstepaction"] Open the WinUI 2 Gallery app and see the Canvas in action
The WinUI 2 Gallery app includes interactive examples of most WinUI 2 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.
This example shows how to position a rectangle 30 pixels from the left and 30 pixels from the top of a Canvas.
[!code-xamlLayoutOvwCanvas1]
Panel, Define layouts, Alignment, margin, and padding, Attached properties overview, Grid, StackPanel, VariableSizedWrapGrid, Controls list, Controls by function