[DisallowMultipleComponent]
[ExecuteAlways]
[RequireComponent(typeof(RectTransform))]
public abstract class LayoutGroup : UIBehaviour, ILayoutElement, ILayoutGroup, ILayoutController

Constructors

LayoutGroup()

Protected default constructor. Use UnityEngine.GameObject.AddComponent<T>() on a concrete subclass.

Declaration

protected LayoutGroup()

Fields

m_ChildAlignment

Serialized backing field for childAlignment.

Declaration

[SerializeField]
protected TextAnchor m_ChildAlignment

Field Value

Type	Description
TextAnchor

m_Padding

Serialized backing field for padding.

Declaration

[SerializeField]
protected RectOffset m_Padding

Field Value

Type	Description
RectOffset

m_Tracker

Tracks driven RectTransform properties to prevent manual editing during layout.

Declaration

protected DrivenRectTransformTracker m_Tracker

Field Value

Type	Description
DrivenRectTransformTracker

Properties

childAlignment

The alignment to use for the child layout elements in the layout group.

Declaration

public TextAnchor childAlignment { get; set; }

Property Value

Type	Description
TextAnchor

Remarks

If a layout element does not specify a flexible width or height, its child elements many not use the available space within the layout group. In this case, use the alignment settings to specify how to align child elements within their layout group.

flexibleHeight

See LayoutElement.flexibleHeight

Declaration

public virtual float flexibleHeight { get; }

Property Value

Type	Description
float

flexibleWidth

See LayoutElement.flexibleWidth

Declaration

public virtual float flexibleWidth { get; }

Property Value

Type	Description
float

layoutPriority

See LayoutElement.layoutPriority

Declaration

public virtual int layoutPriority { get; }

Property Value

Type	Description
int

maxHeight

The maximum height this layout element may be allocated.

Declaration

public virtual float maxHeight { get; }

Property Value

Type	Description
float

maxWidth

The maximum width this layout element may be allocated.

Declaration

public virtual float maxWidth { get; }

Property Value

Type	Description
float

minHeight

See LayoutElement.minHeight

Declaration

public virtual float minHeight { get; }

Property Value

Type	Description
float

minWidth

See LayoutElement.minWidth

Declaration

public virtual float minWidth { get; }

Property Value

Type	Description
float

padding

The padding to add around the child layout elements.

Declaration

public RectOffset padding { get; set; }

Property Value

Type	Description
RectOffset

preferredHeight

See LayoutElement.preferredHeight

Declaration

public virtual float preferredHeight { get; }

Property Value

Type	Description
float

preferredWidth

See LayoutElement.preferredWidth

Declaration

public virtual float preferredWidth { get; }

Property Value

Type	Description
float

rectChildren

The list of valid child RectTransforms used during layout calculations.

Declaration

protected List<RectTransform> rectChildren { get; }

Property Value

Type	Description
List<RectTransform>

rectTransform

The RectTransform of this layout group's GameObject.

Declaration

protected RectTransform rectTransform { get; }

Property Value

Type	Description
RectTransform

Methods

CalculateLayoutInputHorizontal()

Called by the layout system. This base implementation collects valid child RectTransforms. Override in subclasses to calculate the horizontal layout sizes.

Declaration

public virtual void CalculateLayoutInputHorizontal()

CalculateLayoutInputVertical()

Called by the layout system. Override in subclasses to calculate the vertical layout sizes.

Declaration

public abstract void CalculateLayoutInputVertical()

GetAlignmentOnAxis(int)

Returns the alignment on the specified axis as a fraction where 0 is left/top, 0.5 is middle, and 1 is right/bottom.

Declaration

protected float GetAlignmentOnAxis(int axis)

Parameters

Type	Name	Description
int	axis	The axis to get alignment along. 0 is horizontal and 1 is vertical.

Returns

Type	Description
float	The alignment as a fraction where 0 is left/top, 0.5 is middle, and 1 is right/bottom.

GetStartOffset(int, float)

Returns the calculated position of the first child layout element along the given axis.

Declaration

protected float GetStartOffset(int axis, float requiredSpaceWithoutPadding)

Parameters

Type	Name	Description
int	axis	The axis index. 0 is horizontal and 1 is vertical.
float	requiredSpaceWithoutPadding	The total space required on the given axis for all the layout elements including spacing and excluding padding.

Returns

Type	Description
float	The position of the first child along the given axis.

GetTotalFlexibleSize(int)

The flexible size for the layout group on the given axis.

Declaration

protected float GetTotalFlexibleSize(int axis)

Parameters

Type	Name	Description
int	axis	The axis index. 0 is horizontal and 1 is vertical.

Returns

Type	Description
float	The flexible size

GetTotalMaxSize(int)

Gets the maximum size for the layout group on the given axis.

Declaration

protected float GetTotalMaxSize(int axis)

Parameters

Type	Name	Description
int	axis	The axis index. 0 is horizontal and 1 is vertical.

Returns

Type	Description
float	The maximum size of the layout group along the specified axis.

GetTotalMinSize(int)

The min size for the layout group on the given axis.

Declaration

protected float GetTotalMinSize(int axis)

Parameters

Type	Name	Description
int	axis	The axis index. 0 is horizontal and 1 is vertical.

Returns

Type	Description
float	The min size

GetTotalPreferredSize(int)

The preferred size for the layout group on the given axis.

Declaration

protected float GetTotalPreferredSize(int axis)

Parameters

Type	Name	Description
int	axis	The axis index. 0 is horizontal and 1 is vertical.

Returns

Type	Description
float	The preferred size.

IsLayoutPending()

Checks whether this layout group has a layout rebuild queued.

Declaration

public bool IsLayoutPending()

Returns

Type	Description
bool	True if a layout rebuild is queued, otherwise false.

Remarks

The group reports on its layout root, so a nested group returns true whenever an ancestor layout is queued. A disabled component or an inactive GameObject always returns false. This covers layout only, not pending graphic rebuilds. A false result doesn't mean the geometry is final, because a script can mark the group dirty again later in the same frame.

Examples

using UnityEngine;
using UnityEngine.UI; // Required when using UI elements.

public class PanelHeightReporterExample : MonoBehaviour
{
    public VerticalLayoutGroup layoutGroup;

    // Logs the panel height, but only when the layout is up to date.
    public void LogPanelHeight()
    {
        // A queued rebuild means the current height is stale.
        if (layoutGroup.IsLayoutPending())
            return;

        RectTransform panel = layoutGroup.GetComponent<RectTransform>();
        Debug.Log("Panel height is " + panel.rect.height + ".");
    }
}

MarkAndWaitForLayoutRebuildAsync(CancellationToken)

Marks this layout group for rebuild and waits until the rebuild runs.

Declaration

public Awaitable MarkAndWaitForLayoutRebuildAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token that cancels the wait for the rebuild.

Returns

Type	Description
Awaitable	An awaitable that completes when the rebuild has run.

Remarks

Unity queues the rebuild for the next canvas update, and the awaitable completes once it runs. Calling this from a layout callback such as SetLayoutHorizontal() or SetLayoutVertical() defers the mark until the current pass finishes, because the layout system rejects a mark for an element it is already rebuilding. The wait spans an extra frame in that case. Cancellation matches WaitForLayoutAsync(CancellationToken), except that an already canceled token throws before marking the group, so the layout stays untouched.

Examples

using UnityEngine;
using UnityEngine.UI; // Required when using UI elements.

public class RowResizerExample : MonoBehaviour
{
    public VerticalLayoutGroup layoutGroup;
    public LayoutElement row;

    // Applies a new row height and reports the panel height after the rebuild.
    public async Awaitable SetRowHeightAsync(float height)
    {
        row.preferredHeight = height;

        // Queues a rebuild and waits for it to run, so the height read below is current.
        await layoutGroup.MarkAndWaitForLayoutRebuildAsync();

        RectTransform panel = layoutGroup.GetComponent<RectTransform>();
        Debug.Log("Panel height is now " + panel.rect.height + ".");
    }
}

OnChildRectTransformDimensionsChange()

Callback sent from native code whenever the RectTransform dimensions of a direct child are changed.

Declaration

protected virtual void OnChildRectTransformDimensionsChange()

OnDidApplyAnimationProperties()

Callback for when properties have been changed by animation.

Declaration

protected override void OnDidApplyAnimationProperties()

Overrides

UIBehaviour.OnDidApplyAnimationProperties()

OnDisable()

Called when it becomes disabled. Unregisters from the OnChildRectTransformDimensionsChange callback and marks this for a layout rebuild.

Declaration

protected override void OnDisable()

Overrides

UIBehaviour.OnDisable()

OnEnable()

Called when it becomes enabled. Registers for the OnChildRectTransformDimensionsChange callback and marks this for a layout rebuild.

Declaration

protected override void OnEnable()

Overrides

UIBehaviour.OnEnable()

OnRectTransformDimensionsChange()

Called when the RectTransform dimensions change. Registers for a layout rebuild.

Declaration

protected override void OnRectTransformDimensionsChange()

Overrides

UIBehaviour.OnRectTransformDimensionsChange()

OnTransformChildrenChanged()

Called when child transforms are added or removed. Registers for a layout rebuild.

Declaration

protected virtual void OnTransformChildrenChanged()

OnValidate()

Declaration

protected override void OnValidate()

Overrides

UIBehaviour.OnValidate()

Reset()

Registers this layout group's RectTransform and its descendants with the Undo system so the layout applied when the group is added or reset can be reverted in a single undo.

Declaration

protected override void Reset()

Overrides

UIBehaviour.Reset()

SetChildAlongAxis(RectTransform, int, float)

Set the position and size of a child layout element along the given axis.

Declaration

protected void SetChildAlongAxis(RectTransform rect, int axis, float pos)

Parameters

Type	Name	Description
RectTransform	rect	The RectTransform of the child layout element.
int	axis	The axis to set the position and size along. 0 is horizontal and 1 is vertical.
float	pos	The position from the left side or top.

SetChildAlongAxis(RectTransform, int, float, float)

Set the position and size of a child layout element along the given axis.

Declaration

protected void SetChildAlongAxis(RectTransform rect, int axis, float pos, float size)

Parameters

Type	Name	Description
RectTransform	rect	The RectTransform of the child layout element.
int	axis	The axis to set the position and size along. 0 is horizontal and 1 is vertical.
float	pos	The position from the left side or top.
float	size	The size.

SetChildAlongAxisWithScale(RectTransform, int, float, float)

Set the position and size of a child layout element along the given axis.

Declaration

protected void SetChildAlongAxisWithScale(RectTransform rect, int axis, float pos, float scaleFactor)

Parameters

Type	Name	Description
RectTransform	rect	The RectTransform of the child layout element.
int	axis	The axis to set the position and size along. 0 is horizontal and 1 is vertical.
float	pos	The position from the left side or top.
float	scaleFactor	The scale factor to apply to the child's size.

SetChildAlongAxisWithScale(RectTransform, int, float, float, float)

Set the position and size of a child layout element along the given axis.

Declaration

protected void SetChildAlongAxisWithScale(RectTransform rect, int axis, float pos, float size, float scaleFactor)

Parameters

Type	Name	Description
RectTransform	rect	The RectTransform of the child layout element.
int	axis	The axis to set the position and size along. 0 is horizontal and 1 is vertical.
float	pos	The position from the left side or top.
float	size	The size.
float	scaleFactor	The scale factor to apply to the child's size.

SetDirty()

Mark the LayoutGroup as dirty.

Declaration

protected void SetDirty()

SetLayoutHorizontal()

Called by the layout system. Override in subclasses to perform the horizontal layout.

Declaration

public abstract void SetLayoutHorizontal()

SetLayoutInputForAxis(float, float, float, float, int)

Set the calculated layout properties for the given axis.

Declaration

protected void SetLayoutInputForAxis(float totalMin, float totalMax, float totalPreferred, float totalFlexible, int axis)

Parameters

Type	Name	Description
float	totalMin	The min size for the layout group.
float	totalMax	The maximum size for the layout group.
float	totalPreferred	The preferred size for the layout group.
float	totalFlexible	The flexible size for the layout group.
int	axis	The axis to set sizes for. 0 is horizontal and 1 is vertical.

SetLayoutVertical()

Called by the layout system. Override in subclasses to perform the vertical layout.

Declaration

public abstract void SetLayoutVertical()

SetProperty<T>(ref T, T)

Helper method used to set a given property if it has changed.

Declaration

protected void SetProperty<T>(ref T currentValue, T newValue)

Parameters

Type	Name	Description
T	currentValue	A reference to the member value.
T	newValue	The new value.

Type Parameters

Name	Description
T	The type of the property being set.

WaitForLayoutAsync(CancellationToken)

Waits until this layout group has no layout rebuild queued.

Declaration

public Awaitable WaitForLayoutAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The token that cancels the wait. Unity combines it with this component's destroyCancellationToken.

Returns

Type	Description
Awaitable	An awaitable that completes when no layout rebuild is queued.

Remarks

The awaitable completes immediately when nothing is queued, and otherwise waits one frame at a time, so it can span several frames if a rebuild marks the layout dirty again. Disabling the component or deactivating its GameObject completes the wait, because an inactive group queues no rebuild. Destroying the component throws OperationCanceledException, as does canceling cancellationToken.

Examples

using UnityEngine;
using UnityEngine.UI; // Required when using UI elements.

public class RowSpawnerExample : MonoBehaviour
{
    public VerticalLayoutGroup layoutGroup;
    public RectTransform rowPrefab;

    // Adds a row and reports the panel height once the layout accounts for it.
    public async Awaitable AddRowAsync()
    {
        Instantiate(rowPrefab, layoutGroup.transform);

        // The new row does not affect the panel size until the queued rebuild runs.
        await layoutGroup.WaitForLayoutAsync();

        RectTransform panel = layoutGroup.GetComponent<RectTransform>();
        Debug.Log("Panel height is now " + panel.rect.height + ".");
    }
}

Implements

ILayoutElement

ILayoutGroup

ILayoutController