Class WrapLayoutPanel

A layout panel that arranges child elements in sequential position with automatic wrapping and flexible sizing capabilities.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
LayoutPanel
WrapLayoutPanel
IntegralScrollWrapPanel
RadCommandBarOverflowPanel
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.Layout
Assembly: Telerik.WinControls.dll

Syntax

public class WrapLayoutPanel : LayoutPanel, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode
Remarks

Provides advanced flow layout capabilities where elements are positioned sequentially and automatically wrap to new rows or columns when space is exceeded. Supports both horizontal and vertical orientations with uniform sizing through ItemWidth and ItemHeight properties, element stretching, and RTL layout support.

Constructors

WrapLayoutPanel()

Declaration
public WrapLayoutPanel()

Fields

ItemHeightProperty

Declaration
public static readonly RadProperty ItemHeightProperty
Field Value
RadProperty

ItemWidthProperty

Declaration
public static readonly RadProperty ItemWidthProperty
Field Value
RadProperty

OrientationProperty

Declaration
public static readonly RadProperty OrientationProperty
Field Value
RadProperty

Properties

ItemHeight

Gets or sets the uniform height that should be applied to all child elements.

Declaration
public float ItemHeight { get; set; }
Property Value
System.Single

The height in pixels for all child elements, or NaN to use each element's desired height. The default value is NaN.
Remarks

When ItemHeight is set to a specific value, all child elements will be constrained to that height during layout, creating a uniform appearance. If set to NaN (default), each element will use its natural desired height.

This property is particularly useful for creating grid-like layouts where visual consistency is important, such as icon grids, thumbnail galleries, or uniform button layouts.

Changes to this property trigger layout invalidation and re-measurement of the panel and all its child elements.

ItemWidth

Gets or sets the uniform width that should be applied to all child elements.

Declaration
public float ItemWidth { get; set; }
Property Value
System.Single

The width in pixels for all child elements, or NaN to use each element's desired width. The default value is NaN.
Remarks

When ItemWidth is set to a specific value, all child elements will be constrained to that width during layout, creating a uniform appearance. If set to NaN (default), each element will use its natural desired width.

This property works in conjunction with ItemHeight to create consistently sized elements throughout the layout. It's especially useful for creating structured layouts like toolbars, navigation menus, or card-based interfaces.

Changes to this property trigger layout invalidation and re-measurement of the panel and all its child elements.

Orientation

Gets or sets the orientation that determines the primary flow direction of child elements.

Declaration
public Orientation Orientation { get; set; }
Property Value
System.Windows.Forms.Orientation

An System.Windows.Forms.Orientation value that specifies the layout direction. The default value is System.Windows.Forms.Orientation.Horizontal.
Remarks

The orientation determines how elements flow within the panel:

  • System.Windows.Forms.Orientation.Horizontal: Elements flow left-to-right (or right-to-left in RTL mode) and wrap to new rows when space is exceeded
  • System.Windows.Forms.Orientation.Vertical: Elements flow top-to-bottom and wrap to new columns when space is exceeded

Changing the orientation affects how ItemWidth and ItemHeight are applied, how wrapping calculations are performed, and how the StretchItems behavior distributes available space among elements.

Setting this property triggers a complete layout recalculation for optimal performance.

StretchItems

Gets or sets a value indicating whether child elements should be stretched to fill available space within each wrapped line.

Declaration
public bool StretchItems { get; set; }
Property Value
System.Boolean

true if child elements should be stretched to fill the available space; otherwise, false. The default value is false.
Remarks

When StretchItems is enabled, the layout panel calculates the optimal size for elements within each wrapped line to ensure they collectively fill the available space. This creates a justified layout effect where elements are evenly distributed.

The stretching algorithm respects each element's desired size and only stretches elements that are smaller than the calculated uniform size, preventing smaller elements from being compressed below their natural size.

Setting this property invalidates the layout and triggers a re-measurement of all child elements.

Methods

ArrangeOverride(SizeF)

Positions and sizes all child elements within the final layout area, implementing the wrapping and alignment behavior based on the current panel configuration.

Declaration
protected override SizeF ArrangeOverride(SizeF finalSize)
Parameters
System.Drawing.SizeF finalSize

The final area within the parent that the panel should use to arrange itself and its children.
Returns
System.Drawing.SizeF

The actual size used by the panel, which is typically the same as finalSize.
Overrides
Remarks

This method performs the final layout arrangement by:

  1. Determining line breaks based on available space and element sizes
  2. Applying uniform sizing constraints from ItemWidth and ItemHeight
  3. Positioning elements within each line according to the current Orientation
  4. Implementing StretchItems behavior when enabled
  5. Handling right-to-left layout adjustments for proper content flow

The arrangement process ensures that elements are optimally distributed within each wrapped line while maintaining visual consistency and respecting the panel's sizing and alignment settings.

InitializeFields()

Declaration
protected override void InitializeFields()
Overrides

MeasureOverride(SizeF)

Measures the size required to accommodate all child elements within the specified constraints, accounting for wrapping behavior and uniform sizing settings.

Declaration
protected override SizeF MeasureOverride(SizeF constraint)
Parameters
System.Drawing.SizeF constraint

The maximum available size that the panel can use.
Returns
System.Drawing.SizeF

A System.Drawing.SizeF representing the minimum size needed to display all child elements with proper wrapping and spacing.
Overrides
Remarks

This method implements the core measurement logic for the wrap layout:

  1. Measures each child element using available space constraints
  2. Simulates the wrapping behavior to determine line breaks
  3. Calculates total space requirements including wrapped lines
  4. Applies uniform sizing constraints from ItemWidth and ItemHeight

The measurement process respects the current Orientation setting and adjusts calculations accordingly. Elements that exceed the constraint in the primary direction cause line wrapping, while the secondary direction accumulates the total space needed.

Extension Methods