Definition

In this article

Positions child objects and determines a size for a UIElement. Parent objects that implement custom layout for their child elements should call this method from their layout override implementations to form a recursive layout update.

public : void Arrange(Rect finalRect)

void Arrange(Rect finalRect) const;

public void Arrange(Rect finalRect)

Public Sub Arrange(finalRect As Rect)

Parameters

The final size that the parent computes for the child in layout, provided as a Rect value.

Examples

This example shows how you would use Arrange within an ArrangeOverride implementation. The basic idea is that you should query DesiredSize on anything you attempt to call Arrange on so that you have a value for finalRect, unless your layout implementation has some specific design that alters or ignores the desired size before passing it as finalRect.

// Second arrange all children and return final size of panel
protected override Size ArrangeOverride(Size finalSize)
{
// Get the collection of children
UIElementCollection mychildren = Children;
// Get total number of children
int count = mychildren.Count;
// Arrange children
// We're only allowing 9 children in this panel. More children will get a 0x0 layout slot.
int i;
for (i = 0; i < 9; i++)
{
// Get (left, top) origin point for the element in the 3x3 block
Point cellOrigin = GetOrigin(i, 3, new Size(100, 100));
// Arrange child
// Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride.
double dw = mychildren[i].DesiredSize.Width;
double dh = mychildren[i].DesiredSize.Height;
mychildren[i].Arrange(new Rect(cellOrigin.X, cellOrigin.Y, dw, dh));
}
// Give the remaining children a 0x0 layout slot
for (i = 9; i < count; i++)
{
mychildren[i].Arrange(new Rect(0, 0, 0, 0));
}
// Return final size of the panel
return new Size(300, 300);
}

'Second arrange all children and return final size of panel
Protected Overrides Function ArrangeOverride(ByVal finalSize As Size) As Size
'Get the collection of children
Dim mychildren As UIElementCollection = Children
'Get total number of children
Dim count As Integer = mychildren.Count
'Arrange children
'only allowing 9 children in this panel. More children will get a 0x0 layout slot.
Dim i As Integer
For i = 0 To 8
'Get (left, top) origin point for the element in the 3x3 block
Dim cellOrigin As Point = GetOrigin(i, 3, New Size(100, 100))
'Arrange child
'Get desired height and width. This will not be larger than 100x100 as set in MeasureOverride.
Dim dw As Double = mychildren(i).DesiredSize.Width
Dim dh As Double = mychildren(i).DesiredSize.Height
mychildren(i).Arrange(New Rect(cellOrigin.X, cellOrigin.Y, dw, dh))
Next
For i = 9 To count - 1
'Give the remaining children a 0x0 layout slot
mychildren(i).Arrange(New Rect(0, 0, 0, 0))
Next
'Return final size of the panel
Return New Size(300, 300)
End Function
'Calculate point origin of the Block you are in
Protected Function GetOrigin(ByVal blockNum As Integer, ByVal blocksPerRow As Integer, ByVal itemSize As Size) As Point
'Get row number (zero-based)
Dim row As Integer = CInt(Math.Floor(blockNum / blocksPerRow))
'Get column number (zero-based)
Dim column As Integer = blockNum - blocksPerRow * row
'Calculate origin
Dim origin As New Point(itemSize.Width * column, itemSize.Height * row)
Return origin
End Function

Remarks

Computation of initial layout positioning in a XAML UI consists of a Measure call and an Arrange call, in that order. During the Measure call, the layout system determines an element's size requirements using the availableSize measurement. During the Arrange call, the layout system finalizes the size and position of an element's bounding box.

When a layout is first produced, it always has a Measure call that happens before Arrange. However, after the first layout pass, an Arrange call can happen without a Measure preceding it. This can happen when a property that affects only Arrange is changed (such as alignment), or when the parent receives an Arrange without a Measure.

A Measure call will automatically invalidate any Arrange information. Layout updates generally occur asynchronously (at a time determined by the layout system). An element might not immediately reflect changes to properties that affect element sizing (such as Width ).

Layout updates can be forced by app code rather than relying on the built-in layout system behavior by using the UpdateLayout method. However, that is not recommended. It is usually unnecessary and can cause poor performance if overused. In many situations where calling UpdateLayout from app code might be appropriate because of changes to properties, the layout system will probably already be processing updates. The layout system also has optimizations for dealing with cascades of layout changes through parent-child relationships, and calling UpdateLayout can work against such optimizations. Nevertheless, it's possible that layout situations exist in more complicated scenarios where calling UpdateLayout is the best option for resolving a timing issue or other issue with layout. Just use it deliberately and sparingly.