New to Telerik UI for WinForms? Start a free 30-day trial

A layout panel that arranges child elements in a sophisticated grid structure with configurable rows, columns, spanning, and advanced sizing modes.

GridLayout provides comprehensive grid-based layout capabilities that rival modern CSS Grid and HTML table functionality. It supports column and row definitions with multiple sizing modes including proportional sizing, fixed pixel dimensions, auto-sizing based on content, and star-sizing for flexible space distribution.

Advanced features include:

  • Row and column spanning for elements that need to occupy multiple grid cells
  • Individual cell padding control for precise element positioning within cells
  • Proportional sizing with star notation for responsive column and row widths
  • Auto-sizing columns and rows based on their content requirements
  • Stretch modes for filling available horizontal and vertical space
  • DPI-aware scaling for consistent appearance across different display densities

GridLayout is extensively used for creating complex, table-like layouts such as forms, data entry screens, dashboard layouts, property grids, and any UI where precise row and column control with responsive behavior is required. The layout system automatically handles cell positioning, sizing calculations, and element arrangement based on the defined grid structure and content requirements.

Definition

Namespace:Telerik.WinControls.Layouts

Assembly:Telerik.WinControls.dll

Syntax:

C#
public class GridLayout : LayoutPanel, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode

Inheritance: objectDisposableObjectRadObjectRadElementLayoutPanelGridLayout...

Implements: ICustomTypeDescriptorIDisposableINotifyPropertyChangedIStylableNodeISupportSystemSkin

Inherited Members RadElement.BoundsPropertyRadElement.BorderThicknessPropertyRadElement.PaddingPropertyRadElement.MarginPropertyRadElement.AlignmentPropertyRadElement.AutoSizeModePropertyRadElement.FitToSizeModePropertyRadElement.MinSizePropertyRadElement.EnabledPropertyRadElement.CanFocusPropertyRadElement.IsItemFocusedPropertyRadElement.IsFocusedPropertyRadElement.IsMouseOverPropertyRadElement.IsMouseOverElementPropertyRadElement.IsMouseDownPropertyRadElement.ShouldPaintPropertyRadElement.VisibilityPropertyRadElement.NamePropertyRadElement.ClassPropertyRadElement.ClipDrawingPropertyRadElement.ShapePropertyRadElement.MouseClickedEventRadElement.MouseDoubleClickedEventRadElement.MouseDownEventRadElement.MouseUpEventRadElement.MouseWheelEventRadElement.ChildElementAddedEventRadElement.ParentChangedEventRadElement.BoundsChangedEventRadElement.VisibilityChangingEventRadElement.EnabledChangedEventRadElement.ControlChangedEventRadElement.BackgroundShapePropertyRadElement.BackgroundShapePaintModePropertyRadElement.ContainsFocusPropertyRadElement.ContainsMousePropertyRadElement.MaxSizePropertyRadElement.RightToLeftPropertyRadElement.AutoSizePropertyRadElement.ZIndexPropertyRadElement.AngleTransformPropertyRadElement.ScaleTransformPropertyRadElement.PositionOffsetPropertyRadElement.TagPropertyRadElement.StretchHorizontallyPropertyRadElement.StretchVerticallyPropertyRadElement.UseCompatibleTextRenderingPropertyRadElement.ClickModePropertyRadElement.styleVersionRadElement.paintSystemSkinRadElement.SetPropertyValueCommandRadElement.GetPropertyValueCommandRadElement.StylePropertyRadElement.CallCreateChildElements()RadElement.SuspendReferenceUpdate()RadElement.ResumeReferenceUpdate()RadElement.InitializeFields()RadElement.CreateChildElements()RadElement.OnLoad(bool)RadElement.LoadCore()RadElement.OnLoaded()RadElement.OnUnload(ComponentThemableElementTree, bool)RadElement.UnloadCore(ComponentThemableElementTree)RadElement.OnUnloaded(ComponentThemableElementTree)RadElement.OnElementTreeChanged(ComponentThemableElementTree)RadElement.OnBeginDispose()RadElement.SetParent(RadElement)RadElement.OnParentChanged(RadElement)RadElement.UpdateReferences(ComponentThemableElementTree, bool, bool)RadElement.ResetLayout(bool)RadElement.HasInvisibleAncestor()RadElement.ResetLayoutCore()RadElement.InvalidateArrange()RadElement.InvalidateArrange(bool)RadElement.InvalidateMeasure()RadElement.InvalidateMeasure(bool)RadElement.UpdateLayout()RadElement.SuspendLayout()RadElement.SuspendLayout(bool)RadElement.ResumeLayout(bool)RadElement.ResumeLayout(bool, bool)RadElement.Arrange(RectangleF)RadElement.Measure(SizeF)RadElement.SetBounds(Rectangle)RadElement.SetBounds(int, int, int, int)RadElement.GetBoundingRectangle(Size)RadElement.GetBoundingRectangle(Rectangle)RadElement.GetDesiredSize(bool)RadElement.PointToScreen(Point)RadElement.PointFromScreen(Point)RadElement.PointToControl(Point)RadElement.PointFromControl(Point)RadElement.LocationToControl()RadElement.RectangleToScreen(Rectangle)RadElement.HitTest(Point)RadElement.OnRenderSizeChanged(SizeChangedInfo)RadElement.OnChildDesiredSizeChanged(RadElement)RadElement.OnLayoutPropertyChanged(RadPropertyChangedEventArgs)RadElement.ArrangeCore(RectangleF)RadElement.MeasureCore(SizeF)RadElement.ShouldArrangeChild(RadElement)RadElement.ShouldMeasureChild(RadElement)RadElement.MeasureChildren(SizeF)RadElement.GetArrangeRect(RectangleF)RadElement.CanExecuteLayoutOperation()RadElement.CalcLayoutOffset(PointF)RadElement.LockBounds()RadElement.UnlockBounds()RadElement.SetBoundsCore(Rectangle)RadElement.IsInValidState(bool)RadElement.Invalidate()RadElement.Invalidate(bool)RadElement.GetInvalidateBounds()RadElement.NotifyInvalidate(RadElement)RadElement.OnTransformationInvalidated()RadElement.PerformLayoutTransformation(ref RadMatrix)RadElement.PerformPaintTransformation(ref RadMatrix)RadElement.IsInGetAsBitmap()RadElement.PaintElement(IGraphics, float, SizeF)RadElement.PaintElementSkin(IGraphics)RadElement.PaintOverride(IGraphics, Rectangle, float, SizeF, bool)RadElement.PrePaintElement(IGraphics)RadElement.PostPaintElement(IGraphics)RadElement.PaintBackgroundShape(IGraphics)RadElement.PostPaintChildren(IGraphics, Rectangle, float, SizeF)RadElement.PaintChildren(IGraphics, Rectangle, float, SizeF, bool)RadElement.PaintChild(RadElement, IGraphics, Rectangle, float, SizeF, bool)RadElement.PaintShadow(RadElement, IGraphics)RadElement.PaintShadowCore(Graphics, Rectangle, RadItem)RadElement.GetShadowRect(ref Rectangle, int)RadElement.PaintFocusCues(IGraphics, Rectangle)RadElement.GetAsBitmap(IGraphics, Brush, float, SizeF)RadElement.GetAsTransformedBitmap(IGraphics, Brush, float, SizeF)RadElement.GetAsTransformedBitmap(Brush, float, SizeF)RadElement.GetAsTransformedBitmap(Rectangle, Brush, float, SizeF)RadElement.GetAsBitmapEx(Color, float, SizeF)RadElement.GetAsBitmapEx(Brush, float, SizeF)RadElement.GetAsBitmap(Brush, float, SizeF)RadElement.IsInVisibleClipBounds(Rectangle)RadElement.SetClipping(Graphics)RadElement.GetClipRect()RadElement.ShouldPaintChild(RadElement)RadElement.GetFocusRect()RadElement.GetCurrentShape()RadElement.GetPaintRectangle(float, float, SizeF)RadElement.GetPatchedRect(RectangleF, float, SizeF)RadElement.GetXPVisualStyle()RadElement.GetVistaVisualStyle()RadElement.InitializeSystemSkinPaint()RadElement.UnitializeSystemSkinPaint()RadElement.GetSystemSkinPaintBounds()RadElement.OnUseSystemSkinChanged(EventArgs)RadElement.ShouldPaintSystemSkin()RadElement.ComposeShouldPaintSystemSkin()RadElement.GetStylablePropertiesFilter()RadElement.ResetStyleSettings(bool)RadElement.ResetStyleSettings(bool, RadProperty)RadElement.ProcessBehaviors(RadPropertyChangedEventArgs)RadElement.AddBehavior(PropertyChangeBehavior)RadElement.GetBehaviors()RadElement.RemoveBehavior(PropertyChangeBehavior)RadElement.ClearBehaviors()RadElement.AddRangeBehavior(PropertyChangeBehaviorCollection)RadElement.SetThemeApplied(bool)RadElement.OnStyleChanged(RadPropertyChangedEventArgs)RadElement.UnapplyStyle()RadElement.RemoveRangeBehaviors(PropertyChangeBehaviorCollection)RadElement.RemoveBehaviors(PropertyChangeBehavior)RadElement.RemoveRangeRoutedEventBehaviors(RoutedEventBehaviorCollection)RadElement.GetThemeEffectiveType()RadElement.GetChildrenByType(Type)RadElement.GetChildrenByBaseType(Type)RadElement.FindAncestorByThemeEffectiveType(Type)RadElement.FindAncestor<T>()RadElement.IsAncestorOf(RadElement)RadElement.FindDescendant<T>()RadElement.FindDescendant(Predicate<RadElement>)RadElement.FindDescendant(Type)RadElement.EnumDescendants(TreeTraversalMode)RadElement.EnumDescendants(Predicate<RadElement>, TreeTraversalMode)RadElement.EnumDescendants(Filter, TreeTraversalMode)RadElement.GetDescendants(Predicate<RadElement>, TreeTraversalMode)RadElement.GetDescendants(Filter, TreeTraversalMode)RadElement.GetAncestors(Filter)RadElement.GetAncestors(Predicate<RadElement>)RadElement.RaiseRoutedEvent(RadElement, RoutedEventArgs)RadElement.RaiseTunnelEvent(RadElement, RoutedEventArgs)RadElement.RaiseBubbleEvent(RadElement, RoutedEventArgs)RadElement.OnTunnelEvent(RadElement, RoutedEventArgs)RadElement.OnBubbleEvent(RadElement, RoutedEventArgs)RadElement.IsEventInProcess(RaisedRoutedEvent)RadElement.RegisterRoutedEvent(string, Type)RadElement.GetRegisterRoutedEvent(string, Type)RadElement.GetRegisterRoutedEvent(string, string)RadElement.GetRegisterRoutedEvent(string)RadElement.OnChildrenChanged(RadElement, ItemsChangeOperation)RadElement.GetChildren(ChildrenListOptions)RadElement.SendToBack()RadElement.BringToFront()RadElement.IsChildOf(RadElement)RadElement.Focus()RadElement.Focus(bool)RadElement.SetFocusPropertySafe(bool)RadElement.KillFocus()RadElement.OnCLREventsRise(RoutedEventArgs)RadElement.OnMouseMove(MouseEventArgs)RadElement.OnMouseHover(EventArgs)RadElement.OnEnabledChanged(RadPropertyChangedEventArgs)RadElement.OnParentEnabledChanged(RadPropertyChangedEventArgs)RadElement.OnMouseDown(MouseEventArgs)RadElement.OnMouseUp(MouseEventArgs)RadElement.OnLostMouseCapture(MouseEventArgs)RadElement.OnClick(EventArgs)RadElement.OnDoubleClick(EventArgs)RadElement.OnMouseEnter(EventArgs)RadElement.OnMouseLeave(EventArgs)RadElement.PerformClick()RadElement.OnMouseWheel(MouseEventArgs)RadElement.DoMouseWheel(MouseEventArgs)RadElement.DoClick(EventArgs)RadElement.DoDoubleClick(EventArgs)RadElement.IsInputKey(InputKeyEventArgs)RadElement.MouseEventArgsFromControl(MouseEventArgs)RadElement.DoMouseDown(MouseEventArgs)RadElement.DoMouseUp(MouseEventArgs)RadElement.DoMouseMove(MouseEventArgs)RadElement.ShowScreenTip(ScreenTipNeededEventArgs)RadElement.HideScreenTip()RadElement.DoMouseHover(EventArgs)RadElement.OnShowScreenTip(ComponentInputBehavior)RadElement.RaiseClick(EventArgs)RadElement.RaiseDoubleClick(EventArgs)RadElement.RaiseMouseWheel(MouseEventArgs)RadElement.UpdateContainsFocus(bool)RadElement.DoMouseEnter(EventArgs)RadElement.DoMouseLeave(EventArgs)RadElement.GetValue(RadProperty)RadElement.AddStylePropertySetting(IPropertySetting)RadElement.SetValueCore(RadPropertyValue, object, object, ValueSource)RadElement.NotifyChildren(RadPropertyChangedEventArgs)RadElement.OnBoundsChanged(RadPropertyChangedEventArgs)RadElement.OnLocationChanged(RadPropertyChangedEventArgs)RadElement.OnDisplayPropertyChanged(RadPropertyChangedEventArgs)RadElement.OnPropertyChanged(RadPropertyChangedEventArgs)RadElement.CanRaisePropertyChangeNotifications(RadPropertyValue)RadElement.IsPropertyCancelable(RadPropertyMetadata)RadElement.OnParentPropertyChanged(RadPropertyChangedEventArgs)RadElement.ReplaceDefaultDescriptors(PropertyDescriptorCollection)RadElement.ToString()RadElement.DisposeManagedResources()RadElement.PerformDispose(bool)RadElement.DisposeChildren()RadElement.GetStylableChildrenHierarchy()RadElement.GetStylableChildren()RadElement.GetClientRectangle(SizeF)RadElement.GetBorderThickness(BorderPrimitive)RadElement.ElementStateRadElement.DesiredSizeRadElement.IsLayoutSuspendedRadElement.BoundingRectangleRadElement.ControlBoundingRectangleRadElement.BypassLayoutPoliciesRadElement.IsArrangeValidRadElement.IsMeasureValidRadElement.TreeLevelRadElement.TransformRadElement.TotalTransformRadElement.ShouldPaintUsingParentShapeRadElement.UseSystemSkinRadElement.CanHaveOwnStyleRadElement.PropagateStyleToChildrenRadElement.ThemeEffectiveTypeRadElement.ElementTreeRadElement.ChildrenRadElement.ChildrenHierarchyRadElement.ParentRadElement.RoutedEventBehaviorsRadElement.LayoutableChildrenCountRadElement.ContainsFocusRadElement.ShouldHandleMouseInputRadElement.NotifyParentOnMouseInputRadElement.IsAbleToRespondToMouseEventsRadElement.AutoSizeRadElement.BoundsRadElement.LocationRadElement.SizeRadElement.BorderThicknessRadElement.PaddingRadElement.MarginRadElement.AlignmentRadElement.AutoSizeModeRadElement.FitToSizeModeRadElement.EnabledRadElement.CanFocusRadElement.IsFocusedRadElement.IsMouseOverRadElement.IsMouseOverElementRadElement.IsMouseDownRadElement.InvalidateChildrenOnChildChangedRadElement.ShouldPaintRadElement.VisibilityRadElement.IsElementVisibleRadElement.NameRadElement.ClassRadElement.ClipDrawingRadElement.ShapeRadElement.MinSizeRadElement.MaxSizeRadElement.ZIndexRadElement.RightToLeftRadElement.UseCompatibleTextRenderingRadElement.BackgroundShapeRadElement.BackgroundShapePaintModeRadElement.ContainsMouseRadElement.CaptureRadElement.ScaleTransformRadElement.AngleTransformRadElement.PositionOffsetRadElement.SerializePropertiesRadElement.SerializeElementRadElement.SerializeChildrenRadElement.RenderingMaxFramerateRadElement.IsThemeAppliedRadElement.ShouldApplyThemeRadElement.UseCenteredAngleTransformRadElement.TagRadElement.StretchHorizontallyRadElement.StretchVerticallyRadElement.ClickModeRadElement.DoubleClickEnabledRadElement.CaptureOnMouseDownRadElement.IsItemHoveredRadElement.StyleRadElement.ToolTipTextRadElement.AutoToolTipRadElement.ScreenTipRadElement.AutoNumberKeyTipRadElement.DpiScaleFactorRadElement.LayoutUpdatedRadElement.MouseHoverRadElement.MouseMoveRadElement.MouseDownRadElement.MouseUpRadElement.ClickRadElement.DoubleClickRadElement.MouseEnterRadElement.MouseWheelRadElement.EnabledChangedRadElement.MouseLeaveRadElement.ChildrenChangedRadElement.LostMouseCaptureRadObject.BindingContextPropertyRadObject.RadTypeRadObject.ClearPropertyStore()RadObject.SuspendPropertyNotifications()RadObject.ResumePropertyNotifications()RadObject.GetPropertyValue(RadProperty)RadObject.SetDefaultValueOverride(RadProperty, object)RadObject.SetValue(RadProperty, object)RadObject.ResetValue(RadProperty)RadObject.ResetLocalValue(RadProperty)RadObject.ResetValue(RadProperty, ValueResetFlags)RadObject.UpdateValue(RadProperty)RadObject.GetValueSource(RadProperty)RadObject.GetRegisteredRadProperty(string)RadObject.UpdateValueCore(RadPropertyValue)RadObject.ResetValueCore(RadPropertyValue, ValueResetFlags)RadObject.GetDefaultValue(RadPropertyValue, object)RadObject.CoerceValue(RadPropertyValue, object)RadObject.ShouldSerializeProperty(RadProperty)RadObject.BindProperty(RadProperty, RadObject, RadProperty, PropertyBindingOptions)RadObject.UnbindProperty(RadProperty)RadObject.GetInheritedValue(RadProperty)RadObject.OnPropertyChanging(RadPropertyChangingEventArgs)RadObject.OnNotifyPropertyChanged(string)RadObject.OnNotifyPropertyChanged(PropertyChangedEventArgs)RadObject.OnShouldSerializeProperty(ShouldSerializePropertyEventArgs)RadObject.PropertyValuesRadObject.PropertyFilterRadObject.RadObjectTypeRadObject.BindingContextRadObject.PropertyChangedRadObject.RadPropertyChangedRadObject.RadPropertyChangingDisposableObject.GetBitState(long)DisposableObject.SetBitState(long, bool)DisposableObject.OnBitStateChanged(long, bool, bool)DisposableObject.Dispose()DisposableObject.Dispose(bool)DisposableObject.DisposeUnmanagedResources()DisposableObject.BitStateDisposableObject.EventsDisposableObject.IsDisposingDisposableObject.IsDisposedDisposableObject.DisposedDisposableObject.Disposing...

Constructors

Initializes a new instance of the GridLayout class with a single cell (1x1 grid).

C#
public GridLayout()

This constructor creates a minimal grid layout with one column and one row, both configured with default sizing behavior. This is ideal for simple layouts that may be expanded later by adding additional rows and columns to the Columns and Rows collections.

Initializes a new instance of the GridLayout class with the specified number of columns and rows.

C#
public GridLayout(int columnsCount, int rowsCount)
Parameters:columnsCountint

The number of columns to create in the grid. Must be greater than 0.

rowsCountint

The number of rows to create in the grid. Must be greater than 0.

This constructor creates a grid layout with the specified dimensions. Each row and column initially uses Proportional sizing; configure its sizing mode and related dimensions through the Rows and Columns collections.

This is the most efficient way to create a grid when you know the required dimensions in advance, as it pre-allocates the internal collections and avoids dynamic resizing during layout operations.

Fields

Identifies the attached property that adds padding inside a child's grid cell, reducing its available measurement and arrangement area.

C#
public static readonly RadProperty CellPaddingProperty

Identifies the attached property that sets how many consecutive columns a child occupies; the default is 1.

C#
public static readonly RadProperty ColSpanProperty

Identifies the attached property that selects a child's zero-based column in Columns.

C#
public static readonly RadProperty ColumnIndexProperty

Identifies the attached property that selects a child's zero-based row in Rows.

C#
public static readonly RadProperty RowIndexProperty

Identifies the attached property that sets how many consecutive rows a child occupies; the default is 1.

C#
public static readonly RadProperty RowSpanProperty

Properties

Gets or sets the collection of column definitions that determine the width and sizing behavior of grid columns.

C#
public List<GridLayoutColumn> Columns { get; set; }
Property Value:

A List<T> of GridLayoutColumn objects that define the grid's column structure.

Each GridLayoutColumn in this collection represents a column in the grid and provides configuration for width sizing behavior including:

  • Fixed pixel widths for precise column sizing
  • Proportional star-sizing for flexible width distribution
  • Auto-sizing based on column content requirements

Modifying this collection triggers layout invalidation and re-measurement to accommodate the new column structure. The column index of child elements should correspond to valid indices within this collection.

Gets or sets the collection of row definitions that determine the height and sizing behavior of grid rows.

C#
public List<GridLayoutRow> Rows { get; set; }
Property Value:

A List<T> of GridLayoutRow objects that define the grid's row structure.

Each GridLayoutRow in this collection represents a row in the grid and provides configuration for height sizing behavior including:

  • Fixed pixel heights for precise row sizing
  • Proportional star-sizing for flexible height distribution
  • Auto-sizing based on row content requirements

Modifying this collection triggers layout invalidation and re-measurement to accommodate the new row structure. The row index of child elements should correspond to valid indices within this collection.

Methods

Arranges each child in the cell area defined by its row, column, span, and cell padding.

C#
protected override SizeF ArrangeOverride(SizeF finalSize)
Parameters:finalSizeSizeF

The final size assigned to the grid.

Returns:

SizeF

The size assigned to the grid.

Overrides: RadElement.ArrangeOverride(SizeF)

Handles DPI scaling changes by invalidating layout measurements and updating the grid structure.

C#
public override void DpiScaleChanged(SizeF scaleFactor)
Parameters:scaleFactorSizeF

The scaling factor applied due to DPI changes.

Overrides: RadElement.DpiScaleChanged(SizeF)

This method ensures that the grid layout responds appropriately to DPI changes by:

  • Invalidating existing measurements to force recalculation with new DPI
  • Triggering a complete layout update to apply DPI-scaled dimensions
  • Ensuring fixed-size columns and rows are properly scaled

This maintains visual consistency and proper proportions when the application is moved between displays with different DPI settings or when system DPI scaling changes.

Calculates row and column sizes, then measures each child within its spanned cell area.

C#
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters:availableSizeSizeF

The size available for measurement.

Returns:

SizeF

The desired size computed from the row and column dimensions and child measurements.

Overrides: RadElement.MeasureOverride(SizeF)

Panel padding and border thickness are subtracted from the available size before row and column sizing.