Class ElementWithCaptionLayoutPanel

A specialized layout panel that arranges two child elements in a caption-body relationship with configurable positioning.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
LayoutPanel
ElementWithCaptionLayoutPanel
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.Layouts
Assembly: Telerik.WinControls.dll

Syntax

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

ElementWithCaptionLayoutPanel provides a structured layout for controls that require a caption or header element paired with a main body element. The panel automatically manages the spatial relationship between these two elements, supporting both top-caption and bottom-caption arrangements.

Key features include:

  • Automatic identification of caption and body elements through attached properties
  • Flexible caption positioning (top or bottom relative to the body)
  • Dynamic caption visibility control with layout adjustment
  • Intelligent space distribution between caption and body areas
  • Consistent sizing and alignment of both elements

This layout panel is commonly used in controls like group boxes, panels with titles, tabbed interfaces, and any UI elements where a descriptive caption needs to be consistently positioned relative to main content. Child elements are automatically categorized as either caption or body elements based on the CaptionElement attached property.

Constructors

ElementWithCaptionLayoutPanel()

Declaration
public ElementWithCaptionLayoutPanel()

Fields

CaptionElementProperty

Declaration
public static RadProperty CaptionElementProperty
Field Value
RadProperty

CaptionOnTopProperty

Declaration
public static RadProperty CaptionOnTopProperty
Field Value
RadProperty

ShowCaptionProperty

Declaration
public static RadProperty ShowCaptionProperty
Field Value
RadProperty

Properties

CaptionOnTop

Gets or sets a value indicating whether the caption element should be positioned above the body element.

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

true if the caption should be positioned at the top; false if it should be positioned at the bottom. The default value is false.
Remarks

When CaptionOnTop is true, the caption element is arranged at the top of the layout area and the body element occupies the remaining space below. When false, the body element fills the upper area and the caption is positioned at the bottom.

Changing this property triggers a layout invalidation, causing all child elements to be repositioned according to the new arrangement.

ShowCaption

Gets or sets a value indicating whether the caption element should be visible and participate in layout.

Declaration
[RadPropertyDefaultValue("ShowCaption", typeof(ElementWithCaptionLayoutPanel))]
public bool ShowCaption { get; set; }
Property Value
System.Boolean

true if the caption should be visible and allocated space in the layout; false if it should be hidden. The default value is true.
Remarks

When ShowCaption is set to false, the caption element's visibility is set to Collapsed, causing it to be completely removed from the layout calculations. The body element will then occupy the entire available space.

Setting this property to true restores the caption element's visibility to Visible and re-includes it in layout calculations.

This property automatically initializes elements when changed to ensure proper caption and body identification.

Methods

ArrangeOverride(SizeF)

Positions and sizes the caption and body elements within the final layout area according to the current 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 the same as finalSize.
Overrides
Remarks

This method performs the final layout arrangement by:

  1. Initializing and identifying caption and body elements
  2. Calculating space requirements for both elements
  3. Positioning elements based on the CaptionOnTop setting
  4. Ensuring minimum caption height of 8 pixels when visible
  5. Distributing remaining space to the body element

The caption element receives its desired height (minimum 8 pixels), while the body element gets the remaining vertical space. Both elements span the full width of the layout area.

MeasureOverride(SizeF)

Measures the size required to accommodate both caption and body elements within the specified constraints.

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

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

A System.Drawing.SizeF representing the minimum size needed to display both caption and body elements, constrained by the available size.
Overrides
Remarks

This method calculates the total space requirements by:

  1. Initializing and identifying caption and body elements
  2. Measuring both elements using the base measurement logic
  3. Calculating combined width (maximum of both elements) and height (sum of both elements)
  4. Constraining the result within the available size limits

The resulting size ensures that both elements can be displayed with their desired dimensions, with the width being the maximum needed by either element and the height being the sum of both.

OnPropertyChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

Extension Methods