Expand Minimize

UIElement.Arrange method

Applies to Windows and Windows Phone

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.

Syntax

Public Sub Arrange(
  finalRect As Rect 
)

Parameters

finalRect

Type: Rect

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

Remarks

The Arrange call potentially reaches an ArrangeOverride implementation of that specific class. Otherwise, most FrameworkElement classes have an implicit default layout behavior for Arrange.

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.

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 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

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.winmd

See also

UIElement
ArrangeOverride
MeasureOverride

 

 

Show:
© 2014 Microsoft