Table of Contents

Class Panel

Namespace
Icy.UI
Assembly
IcyUI.dll

Represents a container element that can hold other UI elements.

[ContentProperty("Children")]
public class Panel : UIElement, INotifyPropertyChanging, IBindingTarget, INotifyPropertyChanged, INotifyFocusChanged, IContainerElement, IContainerLayout
Inheritance
Panel
Implements
Derived
Inherited Members
Extension Methods

Remarks

The Panel class is a container element that can hold other UIElement objects. It provides events and methods for managing the child elements.

Constructors

Panel()

Initializes a new instance of the Panel class.

public Panel()

Remarks

The constructor sets up event handlers for the Children collection.

Properties

Children

Gets the collection of child elements.

public UIElementCollection Children { get; }

Property Value

UIElementCollection

The collection of child elements.

ContentBounds

Gets the content bounds of the panel, which is the actual bounds minus the padding.

public Rectangle ContentBounds { get; }

Property Value

Rectangle

The content bounds of the panel.

Methods

ArrangeContent()

Handles custom arrange logic when overridden in any UIElement instance.

protected override void ArrangeContent()

Remarks

This method is called during the arrange pass to position and size the element's content within its final bounds. The element's position and size are already determined by the layout system and available in the ActualBounds property.

When implementing this method:

  • Position child elements within the available space;
  • Respect the element's padding when positioning content;
  • Handle any content-specific layout requirements;
  • Call Arrange() on child elements if needed.

GetVisualChildren()

Enumerates this element's immediate visual children, in paint order (back-to-front), for hit-testing and tree traversal.

protected override IEnumerable<UIElement> GetVisualChildren()

Returns

IEnumerable<UIElement>

The element's immediate children. The base implementation yields none (a leaf element).

Remarks

Container elements (e.g. Panel, Border) override this to expose their children, in the exact order they're drawn in — HitTest(Vector2) depends on this matching actual paint order, or clicks will target the wrong, visually-obscured element.

MeasureContent()

Handles custom measure logic when overridden in any UIElement instance.

protected override Size MeasureContent()

Returns

Size

Size recommended to display the UIElement.

Remarks

This method is called during the measure pass to determine the desired size of the element. The returned size should represent the natural size of the element's content, without considering any constraints, margins, or padding.

When implementing this method:

  • Return the natural size needed to display the content;
  • Do not include padding, margins, or borders in the returned size;
  • Consider the content's actual dimensions (e.g., text length, image size);
  • Return Empty if the element has no content.

OnChildAdded(object?, GenericEventArgs<UIElement>)

Raises the ChildAdded event.

protected virtual void OnChildAdded(object? sender, GenericEventArgs<UIElement> e)

Parameters

sender object

The source of the event.

e GenericEventArgs<UIElement>

The GenericEventArgs<T> instance containing the event data.

OnChildAdding(object?, CancellableEventArgs<UIElement>)

Raises the ChildAdding event.

protected virtual void OnChildAdding(object? sender, CancellableEventArgs<UIElement> e)

Parameters

sender object

The source of the event.

e CancellableEventArgs<UIElement>

The CancellableEventArgs<T> instance containing the event data.

OnChildRemoved(object?, GenericEventArgs<UIElement>)

Raises the ChildRemoved event.

protected virtual void OnChildRemoved(object? sender, GenericEventArgs<UIElement> e)

Parameters

sender object

The source of the event.

e GenericEventArgs<UIElement>

The GenericEventArgs<T> instance containing the event data.

OnChildRemoving(object?, CancellableEventArgs<UIElement>)

Raises the ChildRemoving event.

protected virtual void OnChildRemoving(object? sender, CancellableEventArgs<UIElement> e)

Parameters

sender object

The source of the event.

e CancellableEventArgs<UIElement>

The CancellableEventArgs<T> instance containing the event data.

OnChildrenReset(object?, EventArgs)

Raises the ChildrenReset event.

protected virtual void OnChildrenReset(object? sender, EventArgs e)

Parameters

sender object

The source of the event.

e EventArgs

The EventArgs instance containing the event data.

OnChildrenResetting(object?, CancelEventArgs)

Raises the ChildrenResetting event, then - unless a subscriber cancels it - detaches every current child (Parent/Canvas both cleared) before ClearItems() actually empties Children.

protected virtual void OnChildrenResetting(object? sender, CancelEventArgs e)

Parameters

sender object

The source of the event.

e CancelEventArgs

The CancelEventArgs instance containing the event data.

Remarks

Detachment has to happen here, not in OnChildrenUpdated(object?, NotifyCollectionChangedEventArgs)'s Reset branch - ClearItems() raises that NotifyCollectionChangedEventArgs with a null OldItems (Reset never carries the removed items), so by the time OnChildrenUpdated(object?, NotifyCollectionChangedEventArgs) sees it, both that and Children itself are already empty - this event fires beforehand, while Children still holds what's about to be cleared.

OnChildrenUpdated(object?, NotifyCollectionChangedEventArgs)

Raises the ChildrenUpdated event.

protected virtual void OnChildrenUpdated(object? sender, NotifyCollectionChangedEventArgs e)

Parameters

sender object

The source of the event.

e NotifyCollectionChangedEventArgs

The NotifyCollectionChangedEventArgs instance containing the event data.

Remarks

A Reset (i.e. Children cleared) needs no per-item detachment here - see OnChildrenResetting(object?, CancelEventArgs)'s remarks for why that already happened before this ran.

OnRender(IRenderContext)

Handles custom render logic when overridden in any UIElement instance.

protected override void OnRender(IRenderContext context)

Parameters

context IRenderContext

The context to render with.

Remarks

Draws the panel itself, then each visual child in order.

Events

ChildAdded

Occurs when a child element is added to the Children collection.

public event DataEventHandler<UIElement>? ChildAdded

Event Type

DataEventHandler<UIElement>

Remarks

This event is raised after a child element is added to the Children collection.

ChildAdding

Occurs when a child element is being added to the Children collection.

public event CancellableEventHandler<UIElement>? ChildAdding

Event Type

CancellableEventHandler<UIElement>

Remarks

This event is raised before a child element is added to the Children collection. The event can be canceled to prevent the addition of the child element.

ChildRemoved

Occurs when a child element is removed from the Children collection.

public event DataEventHandler<UIElement>? ChildRemoved

Event Type

DataEventHandler<UIElement>

Remarks

This event is raised after a child element is removed from the Children collection.

ChildRemoving

Occurs when a child element is being removed from the Children collection.

public event CancellableEventHandler<UIElement>? ChildRemoving

Event Type

CancellableEventHandler<UIElement>

Remarks

This event is raised before a child element is removed from the Children collection. The event can be canceled to prevent the removal of the child element.

ChildrenReset

Occurs when the Children collection is reset.

public event EventHandler? ChildrenReset

Event Type

EventHandler

Remarks

This event is raised when the entire Children collection is reset.

ChildrenResetting

Occurs when the Children collection is about to be reset.

public event CancelEventHandler? ChildrenResetting

Event Type

CancelEventHandler

Remarks

This event is raised before the entire Children collection is reset. The event can be canceled to prevent the reset.

ChildrenUpdated

Occurs when the Children collection is updated.

public event NotifyCollectionChangedEventHandler? ChildrenUpdated

Event Type

NotifyCollectionChangedEventHandler

Remarks

This event is raised whenever the Children collection is updated, such as when an element is added, removed, or the collection is reset.