ClassWrapLayoutPanel
A layout panel that arranges child elements in sequential position with automatic wrapping and flexible sizing capabilities.
Definition
Namespace:Telerik.WinControls.Layout
Assembly:Telerik.WinControls.dll
Syntax:
public class WrapLayoutPanel : LayoutPanel, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNodeInheritance: objectDisposableObjectRadObjectRadElementLayoutPanelWrapLayoutPanel
Derived Classes:
Implements:
Inherited Members
Constructors
WrapLayoutPanel()
Declaration
public WrapLayoutPanel()Fields
ItemHeightProperty
Declaration
public static readonly RadProperty ItemHeightPropertyField Value
ItemWidthProperty
Declaration
public static readonly RadProperty ItemWidthPropertyField Value
OrientationProperty
Declaration
public static readonly RadProperty OrientationPropertyField Value
Properties
ItemHeight
Gets or sets the uniform height that should be applied to all child elements.
Declaration
[TypeConverter(typeof(LengthConverter))]
public float ItemHeight { get; set; }Property Value
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
[TypeConverter(typeof(LengthConverter))]
public float ItemWidth { get; set; }Property Value
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
An Orientation value that specifies the layout direction. The default value is Horizontal.
Remarks
The orientation determines how elements flow within the panel:
- Horizontal: Elements flow left-to-right (or right-to-left in RTL mode) and wrap to new rows when space is exceeded
- 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
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
finalSize
The final area within the parent that the panel should use to arrange itself and its children.
Returns
The actual size used by the panel, which is typically the same as finalSize.
Overrides
Remarks
This method performs the final layout arrangement by:
- Determining line breaks based on available space and element sizes
- Applying uniform sizing constraints from ItemWidth and ItemHeight
- Positioning elements within each line according to the current Orientation
- Implementing StretchItems behavior when enabled
- 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()
Initializes member fields to their default values. This method is called prior the CreateChildItems one and allows for initialization of members on which child elements depend.
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
constraint
The maximum available size that the panel can use.
Returns
A 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:
- Measures each child element using available space constraints
- Simulates the wrapping behavior to determine line breaks
- Calculates total space requirements including wrapped lines
- 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.