Class View

Namespace

Xui.Core.UI

Assembly

Xui.Core.dll

Base class for all UI elements in the Xui layout engine. A view participates in layout, rendering, and input hit testing, and may contain child views.

public class View : ILayerHost, IServiceProvider

Inheritance

object

View

Implements

ILayerHost

IServiceProvider

Derived

ImageView

Label

LayerView<TView, TLayer>

RootView

ScrollView

ViewCollection

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ServiceProviderExtensions.GetRequiredService<T>(IServiceProvider)

ServiceProviderExtensions.GetService<T>(IServiceProvider)

ViewExtensions.FindViewById(View, string)

ViewExtensions.FindViewsByClass(View, string, List<View>)

ViewExtensions.Parents(View)

ViewExtensions.TryFindParent<T>(View, out T?)

Fields

ClassName

The set of class names assigned to this view, used for lookup via FindViewsByClass(View, string, List<View>).

public ClassNameCollection ClassName

Field Value

ClassNameCollection

Properties

Count

Returns the number of child views. Used by layout containers and traversal logic. Leaf views should return 0.

public virtual int Count { get; }

Property Value

int

CullingFrame

Gets this view's conservative bounds in its parent coordinate space for render culling.

public virtual Rect CullingFrame { get; }

Property Value

Rect

Remarks

A container may override this when its rendered geometry differs from its layout frame. Computing the union of descendant culling frames is deliberately deferred: it can be more expensive than rendering for small subtrees.

Direction

Gets or sets the writing direction.

public Direction Direction { get; set; }

Property Value

Direction

Flags

Gets the current change flags for this view. These flags indicate which aspects (measure, arrange, render, hit test) have changed since the last time the parent acknowledged them via the corresponding Validate* method.

public View.ViewFlags Flags { get; }

Property Value

View.ViewFlags

Flow

Gets or sets the child flow behavior.

public Flow Flow { get; set; }

Property Value

Flow

Focusable

Gets whether this view can receive keyboard focus via Tab navigation.

public virtual bool Focusable { get; }

Property Value

bool

Frame

The border edge of this view in global coordinates relative to the top-left of the window.

public Rect Frame { get; protected set; }

Property Value

Rect

HorizontalAlignment

Gets or sets the horizontal alignment within the layout anchor region.

public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

Id

An optional unique identifier for this view, used for lookup via FindViewById(View, string).

public string? Id { get; set; }

Property Value

string

IsFocused

Gets whether this view currently has keyboard focus.

public bool IsFocused { get; }

Property Value

bool

this[int]

Indexer to access child views by index. Layout containers should implement this to expose their children.

public virtual View this[int index] { get; }

Parameters

index int

Property Value

View

this[Extra]

Fallback indexer for extras whose value type is not covered by a typed overload (e.g. enums). Values are boxed. Prefer the typed overloads for nint, NFloat, string, and bool where possible.

public object? this[View.Extra key] { get; set; }

Parameters

key View.Extra

Property Value

object

this[Extra<bool>]

Gets or sets a bool extra on this view.

public bool this[View.Extra<bool> key] { get; set; }

Parameters

key View.Extra<bool>

Property Value

bool

this[Extra<nint>]

Gets or sets an nint extra on this view.

public nint this[View.Extra<nint> key] { get; set; }

Parameters

key View.Extra<nint>

Property Value

nint

this[Extra<NFloat>]

Gets or sets an NFloat extra on this view.

public NFloat this[View.Extra<NFloat> key] { get; set; }

Parameters

key View.Extra<NFloat>

Property Value

NFloat

this[Extra<string?>]

Gets or sets a string extra on this view.

public string? this[View.Extra<string?> key] { get; set; }

Parameters

key View.Extra<string>

Property Value

string

Margin

Gets or sets the external spacing around the view.

public Frame Margin { get; set; }

Property Value

Frame

MaximumHeight

Gets or sets the maximum border-edge height.

public NFloat MaximumHeight { get; set; }

Property Value

NFloat

MaximumWidth

Gets or sets the maximum border-edge width.

public NFloat MaximumWidth { get; set; }

Property Value

NFloat

MinimumHeight

Gets or sets the minimum border-edge height.

public NFloat MinimumHeight { get; set; }

Property Value

NFloat

MinimumWidth

Gets or sets the minimum border-edge width.

public NFloat MinimumWidth { get; set; }

Property Value

NFloat

Parent

The parent view in the visual hierarchy. This is set automatically when the view is added to a container.

public View? Parent { get; }

Property Value

View

RenderCullingFrame

The active render culling rectangle in this view's coordinate space, if any.

protected Rect? RenderCullingFrame { get; }

Property Value

Rect?

VerticalAlignment

Gets or sets the vertical alignment within the layout anchor region.

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

WritingMode

Gets or sets the writing mode.

public WritingMode WritingMode { get; set; }

Property Value

WritingMode

Methods

AddProtectedChild(View)

Attaches a child view to this parent, setting Parent and performing basic validation. Intended for internal use by container views and single-child hosts.

protected void AddProtectedChild(View child)

Parameters

child View

Animate(TimeSpan, TimeSpan)

Advances animation state for this view and all descendants.

public void Animate(TimeSpan previousTime, TimeSpan currentTime)

Parameters

previousTime TimeSpan

currentTime TimeSpan

AnimateCore(TimeSpan, TimeSpan)

Override to animate this view and its children.

protected virtual void AnimateCore(TimeSpan previousTime, TimeSpan currentTime)

Parameters

previousTime TimeSpan

currentTime TimeSpan

AnimateShell(in LayoutFrameContext)

Performs bookkeeping and animation for this view.

protected void AnimateShell(in LayoutFrameContext frame)

Parameters

frame LayoutFrameContext

Arrange(Rect, IMeasureContext, Size?)

Arranges the view within rect, finalising its position and size.

public Rect Arrange(Rect rect, IMeasureContext context, Size? desiredSize = null)

Parameters

rect Rect

context IMeasureContext

desiredSize Size?

Returns

Rect

ArrangeCore(Rect, IMeasureContext)

Override to arrange children within this view's final frame.

protected virtual void ArrangeCore(Rect rect, IMeasureContext context)

Parameters

rect Rect

context IMeasureContext

ArrangeShell(in LayoutFrameContext, in ArrangeConstraints, ref LayoutMeasurements)

Arranges this view using the supplied immutable constraints.

protected void ArrangeShell(in LayoutFrameContext frame, in ArrangeConstraints constraints, ref LayoutMeasurements measurements)

Parameters

frame LayoutFrameContext

constraints ArrangeConstraints

measurements LayoutMeasurements

Blur()

Releases keyboard focus from this view.

public void Blur()

CapturePointer(int, IPointerGesture?)

Captures the pointer with the specified identifier so that it continues to receive pointer events even if the pointer moves outside its bounds.

public void CapturePointer(int pointerId, IPointerGesture? gesture = null)

Parameters

pointerId int

The platform-assigned pointer identifier.

gesture IPointerGesture

Optional marker describing what kind of gesture this view is tracking (e.g. Tap for a button, Drag for a slider). Ancestor containers (e.g. ScrollView) inspect this via EventRouter.GetCapturedGesture to decide whether they may steal capture.

Focus()

Requests keyboard focus for this view.

public bool Focus()

Returns

bool

GetCapturedGesture(int)

Returns the gesture marker for the view currently capturing pointerId, or null if the pointer is not captured or was captured without a gesture marker.

public IPointerGesture? GetCapturedGesture(int pointerId)

Parameters

pointerId int

Returns

IPointerGesture

GetService(Type)

Resolves a service of the given type by walking up the parent chain. Returns null if no ancestor provides the service.

public virtual object? GetService(Type serviceType)

Parameters

serviceType Type

Returns

object

GlobalToLocal(Point)

Maps a point in root/window coordinate space into this view's local coordinate space.

public Point GlobalToLocal(Point point)

Parameters

point Point

Returns

Point

HitTest(Point)

Determines whether the given point (in this view's local coordinates) hits this view's visual bounds. Used for input dispatch and hit testing.

public virtual bool HitTest(Point point)

Parameters

point Point

The point to test, relative to this view's coordinate space.

Returns

bool

true if the point is inside the view's frame; otherwise false.

Invalidate()

Invalidates every phase affected by a change to the view's layout contract. Used by the base layout properties so cached measurements cannot survive a change to constraints, alignment, or spacing.

protected void Invalidate()

InvalidateArrange()

Marks this view as having changed in a way that may cause it to arrange its children differently, even with the same rectangle and context. Causes OnChildArrangeChanged(View) to be invoked on the parent.

protected void InvalidateArrange()

InvalidateHitTest()

Marks this view as having changed in a way that may cause hit testing to yield different results, even for the same input coordinates. Causes OnChildHitTestChanged(View) to be invoked on the parent.

protected void InvalidateHitTest()

InvalidateMeasure()

Marks this view as having changed in a way that may affect its measured size. Causes OnChildMeasureChanged(View) to be invoked on the parent.

public void InvalidateMeasure()

InvalidateRender()

Marks this view as having changed visually in a way that requires re-rendering. Causes OnChildRenderChanged(View) to be invoked on the parent.

public void InvalidateRender()

InverseTransformPoint(Point)

Maps a point from this view's local coordinate space into its parent coordinate space.

public virtual Point InverseTransformPoint(Point point)

Parameters

point Point

Returns

Point

Remarks

This must be the inverse of TransformPoint(Point) for points that can be hit tested. It is separate so a view can support coordinate mappings that are not yet represented by the canvas transform API.

InverseTransformRect(Rect)

Conservatively maps an axis-aligned rectangle from this view's coordinate space into its parent coordinate space.

public virtual Rect InverseTransformRect(Rect rect)

Parameters

rect Rect

Returns

Rect

Remarks

For non-translation transforms, an override must return the smallest parent-axis-aligned rectangle that encloses every transformed corner.

LocalToGlobal(Point)

Maps a point in this view's local coordinate space into root/window coordinate space.

public Point LocalToGlobal(Point point)

Parameters

point Point

Returns

Point

Measure(Size, IMeasureContext)

Measures the view and returns the desired margin-box size.

public Size Measure(Size availableSize, IMeasureContext context)

Parameters

availableSize Size

context IMeasureContext

Returns

Size

MeasureCore(Size, IMeasureContext)

Override to compute the desired border-edge size.

protected virtual Size MeasureCore(Size availableBorderEdgeSize, IMeasureContext context)

Parameters

availableBorderEdgeSize Size

context IMeasureContext

Returns

Size

MeasureShell(in LayoutFrameContext, in MeasureConstraints, ref LayoutMeasurements)

Measures this view using the supplied immutable constraints.

protected void MeasureShell(in LayoutFrameContext frame, in MeasureConstraints constraints, ref LayoutMeasurements measurements)

Parameters

frame LayoutFrameContext

constraints MeasureConstraints

measurements LayoutMeasurements

OnActivate()

Called when this view becomes active — it will receive events, render, and animate. Override this to start animations, subscribe to data sources, or acquire resources.

protected virtual void OnActivate()

OnAttach(ref AttachEventRef)

Called when this view is added to the visual tree and platform contexts become available. Override to acquire resources that depend on text measurement or bitmap factories.

protected virtual void OnAttach(ref AttachEventRef e)

Parameters

e AttachEventRef

OnBlur()

Called when this view loses keyboard focus.

protected virtual void OnBlur()

OnChar(ref KeyEventRef)

Called when a character is input while this view has focus.

public virtual void OnChar(ref KeyEventRef e)

Parameters

e KeyEventRef

OnChildArrangeChanged(View)

Called when a direct or indirect child view has changed in a way that may affect its arrangement of children. The default implementation forwards the notification up the visual tree to the parent.

protected virtual void OnChildArrangeChanged(View child)

Parameters

child View

The child view whose arrange state has changed.

OnChildHitTestChanged(View)

Called when a direct or indirect child view has changed in a way that may cause hit testing results to change. The default implementation forwards the notification up the visual tree to the parent.

protected virtual void OnChildHitTestChanged(View child)

Parameters

child View

The child view whose hit testing state has changed.

OnChildMeasureChanged(View)

Called when a direct or indirect child view has changed in a way that may affect its measured size. The default implementation forwards the notification up the visual tree to the parent.

protected virtual void OnChildMeasureChanged(View child)

Parameters

child View

The child view whose measure state has changed.

OnChildRenderChanged(View)

Called when a direct or indirect child view has changed visually and requires re-rendering. The default implementation forwards the notification up the visual tree.

protected virtual void OnChildRenderChanged(View child)

Parameters

child View

The child view whose render state has changed.

OnChildRequestedAnimationFrame(View)

Called when a direct or indirect child has requested another animation frame for the next UI tick. The default implementation marks DescendantAnimated and forwards the notification up the visual tree.

protected virtual void OnChildRequestedAnimationFrame(View child)

Parameters

child View

The child view that requested the animation frame.

OnDeactivate()

Called when this view becomes dormant — it should stop animations, timers, and event subscriptions. The view may remain in the tree (e.g., in a virtualizing panel's recycle pool).

protected virtual void OnDeactivate()

OnDetach(ref DetachEventRef)

Called when this view is removed from the visual tree. Override to release any resources acquired in OnAttach(ref AttachEventRef).

protected virtual void OnDetach(ref DetachEventRef e)

Parameters

e DetachEventRef

OnFocus()

Called when this view receives keyboard focus.

protected virtual void OnFocus()

OnKeyDown(ref KeyEventRef)

Called when a key is pressed while this view has focus.

public virtual void OnKeyDown(ref KeyEventRef e)

Parameters

e KeyEventRef

OnPointerEvent(ref PointerEventRef, EventPhase)

Called during event dispatch to handle a pointer event in a specific event phase.

public virtual void OnPointerEvent(ref PointerEventRef e, EventPhase phase)

Parameters

e PointerEventRef

phase EventPhase

OnScrollWheel(ref ScrollWheelEventRef)

Called when a scroll wheel or trackpad scroll event is dispatched to this view. Override to handle scroll input. Set Handled to stop propagation.

public virtual void OnScrollWheel(ref ScrollWheelEventRef e)

Parameters

e ScrollWheelEventRef

ReleasePointer(int)

Releases a previously captured pointer so that pointer events are routed according to normal hit testing rules.

public void ReleasePointer(int pointerId)

Parameters

pointerId int

The platform-assigned pointer identifier.

RemoveProtectedChild(View)

Detaches a child view from this parent, clearing Parent. Intended for internal use by container views and single-child hosts.

protected void RemoveProtectedChild(View child)

Parameters

child View

Render(IContext)

Renders the view. Must be called after layout is complete.

public void Render(IContext context)

Parameters

context IContext

RenderCore(IContext)

Override to render this view and its children.

protected virtual void RenderCore(IContext context)

Parameters

context IContext

RenderShell(in LayoutFrameContext, Rect?)

Performs bookkeeping and renders this view.

protected void RenderShell(in LayoutFrameContext frame, Rect? parentCullingFrame = null)

Parameters

frame LayoutFrameContext

parentCullingFrame Rect?

RequestAnimationFrame()

Requests another animation frame for this view on the next UI tick. Sets Animated and notifies ancestors (via OnChildRequestedAnimationFrame(View)) so they carry DescendantAnimated.

public void RequestAnimationFrame()

SetDefaultRenderState(IContext)

Applies the drawing defaults used at the start of every view render. The active transform and clip are intentionally inherited from the parent.

protected virtual void SetDefaultRenderState(IContext context)

Parameters

context IContext

SetProtectedChild<T>(ref T?, T?)

Sets a single protected child field, automatically detaching the old child (if any) and attaching the new child (if any). Use this for single-child containers.

protected void SetProtectedChild<T>(ref T? field, T? value) where T : View

Parameters

field T

value T

Type Parameters

T

SetViewProperty<T>(ref T, T)

Assigns a layout-affecting property when its value changes, then invalidates the view's measure, arrange, and render state.

protected bool SetViewProperty<T>(ref T field, T value)

Parameters

field T

value T

Returns

bool

true when field changed.

Type Parameters

T

SetViewRenderProperty<T>(ref T, T)

Assigns a render-only property when its value changes.

protected bool SetViewRenderProperty<T>(ref T field, T value)

Parameters

field T

value T

Returns

bool

true when field changed.

Type Parameters

T

TransformPoint(Point)

Maps a point from this view's parent coordinate space into this view's local coordinate space.

public virtual Point TransformPoint(Point point)

Parameters

point Point

Returns

Point

Remarks

Layout still supplies frames using the existing coordinate model. The default identity mapping deliberately preserves that behaviour until a container opts into a local coordinate transform. Containers such as ScrollView can override this to map input into their content space.

TransformRect(Rect)

Conservatively maps an axis-aligned rectangle from this view's parent coordinate space into this view's coordinate space.

public virtual Rect TransformRect(Rect rect)

Parameters

rect Rect

Returns

Rect

Remarks

For non-translation transforms, an override must return the smallest parent-axis-aligned rectangle that encloses every transformed corner.

Update(in LayoutFrameContext, in LayoutUpdate, ref LayoutMeasurements)

Drives the requested passes using shared frame state and per-view constraints.

public virtual void Update(in LayoutFrameContext frame, in LayoutUpdate update, ref LayoutMeasurements measurements)

Parameters

frame LayoutFrameContext

update LayoutUpdate

measurements LayoutMeasurements

ValidateArrange()

Clears the ArrangeChanged flag on this view, indicating that a parent or container has acknowledged the child’s arrange change.

public void ValidateArrange()

ValidateHitTest()

Clears the HitTestChanged flag on this view, indicating that hit-test caches (if any) have been updated or the parent has otherwise accounted for the changed hit-test behavior.

public void ValidateHitTest()

ValidateMeasure()

Clears the MeasureChanged flag on this view, indicating that a parent or container has acknowledged the child’s measure change and handled it (e.g., decided to keep the same column width in a grid regardless of the child’s new desired size). Use this when the parent has considered the change and no re-measure is required for this child.

public void ValidateMeasure()

ValidateRender()

Clears the RenderChanged flag on this view, indicating that the parent (or the rendering pipeline) has acknowledged the visual change and re-rendering for this view has been completed.

public void ValidateRender()