| -api-id | -api-type | ms.custom |
|---|---|---|
T:Windows.UI.Xaml.Controls.RelativePanel |
winrt class |
19H1 |
Defines an area within which you can position and align child objects in relation to each other or the parent panel.
<RelativePanel ...>
oneOrMoreUIElements
</RelativePanel>
-or-
<RelativePanel .../>RelativePanel is a layout container that is useful for creating UI that do not have a clear linear pattern; that is, layouts that are not fundamentally stacked, wrapped, or tabular, where you might naturally use a StackPanel or Grid.
If your UI consists of multiple nested panels, RelativePanel is a good option to consider.
Here's an example of a UI using a RelativePanel for its layout:
<RelativePanel BorderBrush="Gray" BorderThickness="10">
<Rectangle x:Name="RedRect" Fill="Red" MinHeight="100" MinWidth="100"/>
<Rectangle x:Name="BlueRect" Fill="Blue" MinHeight="100" MinWidth="100"
RelativePanel.RightOf="RedRect"/>
<!-- Width is not set on the green and yellow rectangles.
It's determined by the RelativePanel properties. -->
<Rectangle x:Name="GreenRect" Fill="Green" MinHeight="100" Margin="0,5,0,0"
RelativePanel.Below="RedRect"
RelativePanel.AlignLeftWith="RedRect"
RelativePanel.AlignRightWith="BlueRect"/>
<Rectangle Fill="Yellow" MinHeight="100"
RelativePanel.Below="GreenRect"
RelativePanel.AlignLeftWith="BlueRect"
RelativePanel.AlignRightWithPanel="True"/>
</RelativePanel>RelativePanel, used in conjunction with AdaptiveTrigger s, can be a powerful tool to create responsive UI that scales well across different screen sizes. For more examples, see the XAML Responsive Techniques sample.
By default, any unconstrained element declared as a child of the RelativePanel is given the entire available space and positioned at the (0, 0) coordinates (upper left corner) of the panel. So, if you are positioning a second element relative to an unconstrained element, keep in mind that the second element might get pushed out of the panel.
In this example, RectA doesn't have any constraints, so it's positioned at (0,0). RectB is not shown on the screen because it is declared to be Above RectA and is therefore pushed out of the panel.
<RelativePanel>
<Rectangle Name="RectA" Fill="Red" Height="40" Width="40"/>
<Rectangle Name="RectB" Fill="Blue" Height="40" Width="40"
RelativePanel.Above="RectA"/>
</RelativePanel>A circular dependency occurs when two elements inside a RelativePanel declare relationships with each other in any direction. For example, this XAML results in a design-time exception, "RelativePanel error: Circular dependency detected. Layout could not complete."
<RelativePanel>
<Rectangle Name="RectA" Fill="Red" Height="40" Width="40"
RelativePanel.Above="RectB"/>
<Rectangle Name="RectB" Fill="Blue" Height="40" Width="40"
RelativePanel.Below="RectA"/>
</RelativePanel>If you set multiple relationships that target the same edge of an element, you might have conflicting relationships in your layout as a result. When this happens, the relationships are applied in the following order of priority:
- Panel alignment relationships (AlignTopWithPanel, AlignLeftWithPanel, …) are applied first.
- Sibling alignment relationships (AlignTopWith, AlignLeftWith, …) are applied second.
- Sibling positional relationships (Above, Below, RightOf, LeftOf) are applied last.
The panel-center alignment properties (AlignVerticalCenterWith, AlignHorizontalCenterWithPanel, ...) are typically used independently of other constraints and are applied if there is no conflict.
The HorizontalAlignment and VerticalAlignment properties on UI elements are applied after relationship properties are evaluated and applied. These properties control the placement of the element within the available size for the element, if the desired size is smaller than the available size.
RelativePanel defines border properties that let you draw a border around the RelativePanel without using an additional Border element. The properties are RelativePanel.BorderBrush, RelativePanel.BorderThickness, RelativePanel.CornerRadius, and RelativePanel.Padding.
<RelativePanel BorderBrush="Red" BorderThickness="2" CornerRadius="10" Padding="12">
<TextBox x:Name="textBox1" RelativePanel.AlignLeftWithPanel="True"/>
<Button Content="Submit" RelativePanel.Below="textBox1"/>
</RelativePanel>RelativePanel 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 |
|---|---|
| Above | Gets or sets a target element that this element is positioned above. |
| AlignBottomWith | Gets or sets a target element that this element's bottom edge is aligned with. |
| AlignBottomWithPanel | Gets or sets a value that indicates whether this element's bottom edge is touching the panel's bottom edge. |
| AlignHorizontalCenterWith | Gets or sets a target element that this element's horizontal center is aligned with. |
| AlignHorizontalCenterWithPanel | Gets or sets a value that indicates whether this element's horizontal axis is touching the panel's horizontal axis. |
| AlignLeftWith | Gets or sets a target element that this element's left edge is aligned with. |
| AlignLeftWithPanel | Gets or sets a value that indicates whether this element's left edge is touching the panel's left edge. |
| AlignRightWith | Gets or sets a target element that this element's right edge is aligned with. |
| AlignRightWithPanel | Gets or sets a value that indicates whether this element's right edge is touching the panel's right edge. |
| AlignTopWith | Gets or sets a target element that this element's top edge is aligned with. |
| AlignTopWithPanel | Gets or sets a value that indicates whether this element's top edge is touching the panel's top edge. |
| AlignVerticalCenterWith | Gets or sets a target element that this element's vertical center is aligned with. |
| AlignVerticalCenterWithPanel | Gets or sets a value that indicates whether this element's vertical axis is touching the panel's horizontal axis. |
| Below | Gets or sets a target element that this element is positioned below. |
| LeftOf | Gets or sets a target element that this element is positioned to the left of. |
| RightOf | Gets or sets a target element that this element is positioned to the right of. |
| Windows version | SDK version | Value added |
|---|---|---|
| 1809 | 17763 | BackgroundSizing |
Tip
For more info, design guidance, and code examples, see Layout panels.
If you have the WinUI 2 Gallery app installed, click here to open the app and see the RelativePanel in action.
Panel, Define layouts with XAML, Quickstart: Adding layout controls, Alignment, margin, and padding, Canvas, Grid, StackPanel, VariableSizedWrapGrid, Controls list, Controls by function