Table of Contents

Class UIElement

Namespace
Icy.UI
Assembly
IcyUI.dll

Represents the base class for all UI elements in the game interface.

public class UIElement : DependencyObject, INotifyPropertyChanging, IBindingTarget, INotifyPropertyChanged, INotifyFocusChanged
Inheritance
UIElement
Implements
Derived
Inherited Members
Extension Methods

Remarks

UIElement is the fundamental building block of the UI system, providing layout, rendering, and input handling capabilities. All visual elements in the game interface derive from this class.

This class implements a property references system for efficient property change notification and value inheritance. It also provides a comprehensive event system for handling user input and state changes.

Properties

ActualBounds

Gets or sets the actual bounds of the UIElement instance.

[Browsable(false)]
[JsonIgnore]
public Rectangle ActualBounds { get; protected set; }

Property Value

Rectangle

Canvas

Gets or sets an instance of Canvas that is used as the root for the hierarchy for this UIElement instance.

[Browsable(false)]
[JsonIgnore]
public Canvas? Canvas { get; protected set; }

Property Value

Canvas

ClipToBounds

Gets or sets a value indicating whether the control contents should be clipped to the actual bounds when rendering.

public bool ClipToBounds { get; set; }

Property Value

bool

Configuration

Gets the library configuration for the Canvas instance the UIElement is attached to.

protected IcyConfiguration? Configuration { get; }

Property Value

IcyConfiguration

ControlState

Gets or sets the combination of ControlState flags currently active on this element.

public ControlState ControlState { get; set; }

Property Value

ControlState

Remarks

Setting this re-evaluates every group registered via RegisterStateGroup(VisualStateGroup), switching each group's active VisualState (if any) to whichever state's flags form the largest subset of the new value.

DataContext

Gets or sets the data object this UIElement and the bindings on it resolve against.

public object? DataContext { get; set; }

Property Value

object

Remarks

An element that never sets this inherits its nearest ancestor's value by walking Parent on every read - there is no eager push-down of the value itself, only of the fact that it changed (see DataContextChanged). Setting it here stops the inheritance at this element: descendants see this value instead of continuing further up the tree.

A {Binding} markup extension with no explicit Source or ElementName resolves against this - see BindingExtension.

DesiredSize

Gets or sets the size the UIElement instance wants to be.

[Browsable(false)]
[JsonIgnore]
public Size DesiredSize { get; protected set; }

Property Value

Size

Foreground

Gets or sets the foreground color of the UIElement instance.

public Color Foreground { get; set; }

Property Value

Color

HasResources

Gets a value indicating whether Resources has been allocated - reading it never allocates on its own, unlike reading Resources itself.

[Browsable(false)]
[JsonIgnore]
public bool HasResources { get; }

Property Value

bool

Height

Gets or sets the height of the UIElement instance.

[Range(0, Infinity)]
public float Height { get; set; }

Property Value

float

Remarks

If set to NaN, the UIElement instance will size to its content.

Must be at least 0; NaN (the default) means unset.

HorizontalAlignment

Gets or sets the horizontal alignment of the UIElement instance.

public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

Remarks

Determines how the UIElement instance is positioned horizontally within its parent.

IsArrangeInvalid

Gets or sets a value indicating whether whether the arrangement of the UIElement is invalid.

protected bool IsArrangeInvalid { get; set; }

Property Value

bool

IsAttached

Gets a value indicating whether the UIElement is attached to any Canvas instance.

[JsonIgnore]
[Browsable(false)]
[MemberNotNullWhen(true, "Configuration")]
public bool IsAttached { get; }

Property Value

bool

IsEnabled

Gets or sets a value indicating whether this element responds to input.

public bool IsEnabled { get; set; }

Property Value

bool

Remarks

true by default. Setting this to false sets Disabled (for theming) and composes into IsHitTestVisible/ IsFocusable's own getters - a disabled element's entire subtree becomes unreachable by HitTest(Point) (the exact subtree-skip IsHitTestVisible already performs for a drag-and-drop preview ghost) and this element itself is excluded from MoveFocus(bool)'s candidate list (but descendants that are independently IsFocusable remain focusable, matching the non-cascading semantics of both properties), with no change to either property's own stored value - re-enabling restores whatever they were set to independently. Deliberately does not cascade a visual "disabled" look to descendants; only this element's own Disabled flag (and therefore its own themed appearance) is affected.

IsFocusScope

Gets or sets a value indicating whether this element is a focus scope — a boundary that keyboard/gamepad focus traversal (Tab, FocusNext/FocusPrevious) won't cross, and whose last-focused descendant is restored when focus returns to the scope from outside it.

public bool IsFocusScope { get; set; }

Property Value

bool

Remarks

Useful for modal dialogs (Window), dropdowns, and context menus — anything that should trap focus while it's open.

IsFocusable

Gets or sets a value indicating whether this element can receive focus.

public bool IsFocusable { get; set; }

Property Value

bool

Remarks

Defaults to false — most elements (decorative ones like Border or TextBlock-like content) aren't focus targets. Interactive controls set this to true.

IsFocused

Gets a value indicating whether the element is focused.

[Browsable(false)]
[JsonIgnore]
public bool IsFocused { get; }

Property Value

bool

IsHitTestVisible

Gets or sets a value indicating whether this element can be returned by HitTest(Point).

public bool IsHitTestVisible { get; set; }

Property Value

bool

Remarks

true by default. Set to false for a purely visual overlay (e.g. a drag-and-drop preview) that must never itself become a hit-test/click/drop target - the entire subtree is skipped, letting whatever's visually underneath it be hit instead.

IsMeasureInvalid

Gets or sets a value indicating whether the measure of the UIElement is invalid.

protected bool IsMeasureInvalid { get; set; }

Property Value

bool

IsTransformInvalid

Gets or sets a value indicating whether the transform of the UIElement is invalid.

protected bool IsTransformInvalid { get; set; }

Property Value

bool

IsVisible

Gets or sets a value indicating whether the UIElement instance is visible.

public bool IsVisible { get; set; }

Property Value

bool

Remarks

When set to false, the UIElement instance and its children are not rendered.

IsVisualInvalid

Gets or sets a value indicating whether the visual configuration of the UIElement is invalid.

protected bool IsVisualInvalid { get; set; }

Property Value

bool

LayoutInvalid

Gets or sets the flags that indicate whether the UIElement instance should recalculate any of layout properties.

protected UIElement.UpdateFlags LayoutInvalid { get; set; }

Property Value

UIElement.UpdateFlags

LayoutOffset

Gets or sets the offset applied to the UIElement at layout.

public Vector2 LayoutOffset { get; set; }

Property Value

Vector2

Remarks

The value represents pixels offset from the original layout location for the UIElement instance.

LayoutRotation

Gets or sets the rotation of the UIElement instance in degrees.

[Range(0, 360)]
public float LayoutRotation { get; set; }

Property Value

float

Remarks

Values are normalized to the range 0-360 degrees.

LayoutScale

Gets or sets the scale of the UIElement instance.

public Vector2 LayoutScale { get; set; }

Property Value

Vector2

Remarks

A scale of (1,1) represents the original size.

LayoutTransformOrigin

Gets or sets the origin point for transforms applied to UIElement after layout.

public Vector2 LayoutTransformOrigin { get; set; }

Property Value

Vector2

Remarks

The origin is specified as a relative point, where (0,0) is the top-left and (1,1) is the bottom-right of the UIElement instance.

LogicalParent

Gets the logical parent of the UIElement instance.

[JsonIgnore]
[Browsable(false)]
public IContainerLayout? LogicalParent { get; }

Property Value

IContainerLayout

Margin

Gets or sets the margin around the UIElement instance.

public Thickness Margin { get; set; }

Property Value

Thickness

Remarks

The margin is the space between this UIElement instance and its parent or adjacent UIElement instances.

When the element and its margin don't fit into the space its container arranges it in, and the element can't shrink (see MinWidth), the margin on that axis is scaled down proportionally while the element keeps its size.

MaxHeight

Gets or sets the maximal UIElement height.

[Range(0, Infinity)]
public float MaxHeight { get; set; }

Property Value

float

Remarks

NaN (the default) means no limit. A value below MinHeight is ignored: the minimum wins, so a conflicting pair never breaks layout.

Must be at least 0; NaN (the default) means unset.

MaxWidth

Gets or sets the maximal UIElement width.

[Range(0, Infinity)]
public float MaxWidth { get; set; }

Property Value

float

Remarks

NaN (the default) means no limit. A value below MinWidth is ignored: the minimum wins, so a conflicting pair never breaks layout.

Must be at least 0; NaN (the default) means unset.

MinHeight

Gets or sets the minimal UIElement height.

[Range(0, Infinity)]
public float MinHeight { get; set; }

Property Value

float

Remarks

NaN (the default) means unset: no lower limit.

This property also decides whether the element may shrink when it doesn't fit into the space its container arranges it in. This applies unless the element stretches with an unset Height, which always fills the available space instead:

  • Unset: the element keeps its measured height and overflows; only its Margin on that axis is scaled down. Popups, toolbars and other content-sized elements rely on this.
  • Set, and the available height (the container minus the margin) is at least this value: the element shrinks to the available height, still limited by MaxHeight.
  • Set, but the available height is smaller than this value: the element keeps its height, as when unset.

Set it to 0 to let an element shrink as far as needed.

Must be at least 0; NaN (the default) means unset.

MinWidth

Gets or sets the minimal UIElement width.

[Range(0, Infinity)]
public float MinWidth { get; set; }

Property Value

float

Remarks

NaN (the default) means unset: no lower limit.

This property also decides whether the element may shrink when it doesn't fit into the space its container arranges it in. This applies unless the element stretches with an unset Width, which always fills the available space instead:

  • Unset: the element keeps its measured width and overflows; only its Margin on that axis is scaled down. Popups, toolbars and other content-sized elements rely on this.
  • Set, and the available width (the container minus the margin) is at least this value: the element shrinks to the available width, still limited by MaxWidth.
  • Set, but the available width is smaller than this value: the element keeps its width, as when unset.

Set it to 0 to let an element shrink as far as needed.

Must be at least 0; NaN (the default) means unset.

Name

Gets or sets the name of the UIElement instance.

public string? Name { get; set; }

Property Value

string

Opacity

Gets or sets the opacity of the UIElement instance.

[Range(0, 1)]
public float Opacity { get; set; }

Property Value

float

Remarks

Values must be between 0.0 (fully transparent) and 1.0 (fully opaque).

Padding

Gets or sets the padding of the UIElement instance.

public Thickness Padding { get; set; }

Property Value

Thickness

Parent

Gets the parent of this UIElement instance.

[Browsable(false)]
[JsonIgnore]
public UIElement? Parent { get; }

Property Value

UIElement

PassesUnclaimedInput

Gets or sets a value indicating whether a wheel scroll or a drag that nothing in this overlay takes falls through to the elements beneath it.

public bool PassesUnclaimedInput { get; set; }

Property Value

bool

Remarks

Only consulted on the root of a canvas overlay. When a wheel scroll reaches no element of the overlay that consumes it (see OnScroll(ScrollInfo)), or a starting drag finds no element of the overlay that claims it (see GetDragAxes(in DragClaimContext)), the canvas hit-tests again below the overlay and routes the input there.

Hover, taps, clicks, drag-and-drop sources and focus never fall through. false by default, so an ordinary overlay, such as a modal dialog's backdrop, keeps blocking the page beneath it. Tools use it for a layer that takes some gestures but should let the page scroll, like the design-time editor's capture layer.

RenderOffset

Gets or sets the offset applied to the UIElement at rendering.

public Vector2 RenderOffset { get; set; }

Property Value

Vector2

Remarks

The value represents pixels offset from the original rendering location for the UIElement instance.

The RenderOffset is used only at rendering and does not affect real element layout.

RenderRotation

Gets or sets the rotation of the UIElement instance in degrees, applied to element while rendering.

[Range(0, 360)]
public float RenderRotation { get; set; }

Property Value

float

Remarks

Values are normalized to the range 0-360 degrees.

The RenderRotation is used only at rendering and does not affect real element layout.

RenderScale

Gets or sets the rendering scale of the UIElement instance.

public Vector2 RenderScale { get; set; }

Property Value

Vector2

Remarks

A scale of (1,1) represents the original size.

The RenderScale is used only at rendering and does not affect real element layout.

RenderSize

Gets the actual render size of the component.

[Browsable(false)]
[JsonIgnore]
public Size RenderSize { get; }

Property Value

Size

RenderTransformOrigin

Gets or sets the origin point for transforms used at UIElement rendering.

public Vector2 RenderTransformOrigin { get; set; }

Property Value

Vector2

Remarks

The origin is specified as a relative point, where (0,0) is the top-left and (1,1) is the bottom-right of the UIElement instance.

The RenderTransformOrigin is used only at rendering and does not affect real element layout.

Resources

Gets the resources this element declares - Styles, Timelines, or anything else keyed by name for {StaticResource} lookup within this element's subtree.

[Browsable(false)]
[JsonIgnore]
public ResourceDictionary Resources { get; }

Property Value

ResourceDictionary

Remarks

Lazily allocated - reading this on an element with no declared resources never allocates. See ResourceDictionary's remarks for how lookup walks the element tree.

Style

Gets or sets the style applied to the UIElement instance.

public Style? Style { get; set; }

Property Value

Style

Remarks

An implicit (keyless, type-targeted) style applies automatically whenever Style is null at attach (see IImplicitResourceKey and implicit-style resolution), so "no style" and "never explicitly set" are the same state - an element that wants to opt out of an ambient implicit style needs its own no-op Style (e.g. new Style(typeof(YourType)) with no setters), not Style = null, since null is exactly the state that triggers implicit-style lookup.

A style that isn't the theme's own is applied on top of the theme's style for this element's type, which the canvas holds: the theme supplies what the style doesn't set, such as the template. A style whose ReplacesTheme is set, or that is based on the theme's style already, is applied on its own.

VerticalAlignment

Gets or sets the vertical alignment of the UIElement instance.

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

Remarks

Determines how the UIElement is positioned vertically within its parent.

Width

Gets or sets the width of the UIElement instance.

[Range(0, Infinity)]
public float Width { get; set; }

Property Value

float

Remarks

If set to NaN, the UIElement will size to its content.

Must be at least 0; NaN (the default) means unset.

ZIndex

Gets or sets the Z-layer position of the UIElement instance. The less the number, the closer UIElement instance to the screen front.

public float ZIndex { get; set; }

Property Value

float

Remarks

Controls with the same Z-index are placed in visual tree order – those that are closer to root are farther from the screen.

Methods

Arrange()

Arranges the UIElement instance within its LogicalParent's ContentBounds, per its own Margin/alignment.

public void Arrange()

Arrange(Rectangle)

Arranges the UIElement instance within containerBounds, per its own Margin/alignment.

public void Arrange(Rectangle containerBounds)

Parameters

containerBounds Rectangle

The bounds to arrange within. Callers that need to hand a child a specific target rect - e.g. a Grid placing a child into a particular cell - pass that rect directly instead of the default overload's LogicalParent-wide ContentBounds. Margin and HorizontalAlignment/VerticalAlignment still apply exactly as usual, just relative to this rect instead of the whole parent - e.g. a child can still center itself within its assigned cell, or stretch to fill it.

ArrangeContent()

Handles custom arrange logic when overridden in any UIElement instance.

protected virtual 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.

BringIntoView()

Scrolls every enclosing scrollable ancestor (such as a ScrollViewer) just enough to show this element, innermost first.

public void BringIntoView()

Remarks

  • An element above or left of a viewport is aligned with its leading edge; one below or right, with its trailing edge.
  • An element larger than a viewport is aligned with its leading edge.
  • An element already fully visible doesn't scroll anything.
  • Does nothing while this element isn't attached to a Canvas.

Canvas calls this after moving focus with the keyboard or a gamepad (Tab and spatial moves), but not after a tap or a programmatic Focus(UIElement?).

CanHitTestChildren()

Gets a value indicating whether HitTest(Vector2) descends into this element's children.

protected virtual bool CanHitTestChildren()

Returns

bool

true by default. Returning false makes the element itself the hit target for every point inside it - e.g. a scrolling list during a fling, so the press that stops it doesn't reach an item.

Draw(IRenderContext)

Draws the UIElement instance using specified render context.

public void Draw(IRenderContext context)

Parameters

context IRenderContext

The context to render UIElement with.

EnumerateVisualSubtree()

Enumerates this element and its entire visual subtree (self first, then children depth-first, via GetVisualChildren()), in paint order.

public IEnumerable<UIElement> EnumerateVisualSubtree()

Returns

IEnumerable<UIElement>

This element followed by every descendant in the visual tree.

GetDefaultRenderOptions()

Computes the default local-space TextureRenderingOptions for this UIElement instance, covering its full ActualBounds at full opacity/white tint, ready to hand to an IBrush.

protected TextureRenderingOptions GetDefaultRenderOptions()

Returns

TextureRenderingOptions

The default rendering options for this element's content area.

GetDragAxes(in DragClaimContext)

Returns the axes along which this element wants to own a drag that starts on it or a descendant.

protected virtual DragAxes GetDragAxes(in DragClaimContext context)

Parameters

context DragClaimContext

The starting drag.

Returns

DragAxes

The claimed axes; the base implementation returns None.

Remarks

When a drag starts, Canvas asks the hit element and each ancestor in turn. The innermost element whose answer contains the drag's main axis (the larger component of LocalDirection) owns the gesture. If none does, the innermost element with any answer owns it. Only the owner receives OnDragStarted(Point), OnDragPerforming(Point), OnDragFling(Vector2) and OnDragEnded(Point).

An element that handles drags must override this method: overriding OnDragStarted(Point) alone receives nothing.

GetVisualChildren()

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

protected virtual 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.

HitTest(Vector2)

Determines which element — this one, one of its descendants, or none — contains the specified point.

public UIElement? HitTest(Vector2 pointInParentLocalSpace)

Parameters

pointInParentLocalSpace Vector2

A point expressed in this element's parent's own local (post-Draw(IRenderContext)-transform) space — the same space a child's Draw(IRenderContext) call receives via context.Transform once the parent's own layout/render transform has been applied.

Returns

UIElement

The topmost hit-testable element containing the point, or null if none does.

Remarks

Tests GetVisualChildren() in reverse order (topmost/last-painted first — see ZIndex), so a child that visually overlaps and paints on top of a sibling is hit before that sibling. Only accounts for LayoutOffset/LayoutRotation/ LayoutScale (the same transform that determines ActualBounds) — RenderOffset/RenderRotation/RenderScale are treated as purely cosmetic for v1 and don't affect where clicks land.

An element that is hidden (IsVisible is false), fully transparent (Opacity is 0 or less), or explicitly excluded from hit-testing (IsHitTestVisible is false) is skipped along with its entire subtree.

InvalidateArrange()

Invalidates UIElement arrange to recalculate on next draw call.

public void InvalidateArrange()

InvalidateMeasure()

Invalidates UIElement measure to recalculate on next draw call.

public void InvalidateMeasure()

InvalidateTransform()

Invalidates UIElement transform to recalculate on next draw call.

public void InvalidateTransform()

InvalidateVisual()

Invalidates visual configuration of the UIElement to recalculate it on next rendering.

public void InvalidateVisual()

Measure()

Calculates desired UIElement size.

public Size Measure()

Returns

Size

Size recommended to display the UIElement instance.

MeasureContent()

Handles custom measure logic when overridden in any UIElement instance.

protected virtual 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.

OnActivate()

Invoked by Canvas for an activation press (Enter, gamepad A) while this element or one of its descendants has focus.

protected virtual bool OnActivate()

Returns

bool

true to claim the press; Canvas then stops calling further ancestors. The base implementation returns false.

OnArrangeUpdated()

Raises the ArrangeUpdated event.

protected virtual void OnArrangeUpdated()

OnAttached()

Raises the Attached event.

protected virtual void OnAttached()

Remarks

Propagates Canvas to every element in GetVisualChildren() - this is what makes attaching a whole pre-built subtree (the common pattern: build children, then attach the root once via Add(UIElement)) reach every descendant, not just the immediate root. Each child's own Canvas setter recurses into its children the same way, so this walks the full subtree regardless of depth. Container-specific child-add paths (e.g. OnChildAdded(object?, GenericEventArgs<UIElement>)) still assign Canvas directly for children added after the parent is already attached - this cascade is what covers everything built beforehand.

OnDataContextChanged()

Raises DataContextChanged, then recurses into every element in GetVisualChildren() that has no DataContext of its own.

protected virtual void OnDataContextChanged()

Remarks

Mirrors OnAttached()'s cascade through the visual tree, but propagates a change notification instead of the value itself - preferred over pushing the value down eagerly, since DataContext is read lazily by walking Parent anyway (see its remarks). A descendant that set its own DataContext keeps it and stops the cascade there: nothing about its own effective value changed.

OnDetached()

Raises the Detached event.

protected virtual void OnDetached()

Remarks

Propagates null to every element in GetVisualChildren(), mirroring OnAttached() - see its remarks.

OnDragCanceled(Point)

Called on the element that owns a drag when the gesture recognizer cancels it (a second pointer, lost focus) instead of completing it.

protected virtual void OnDragCanceled(Point screenPoint)

Parameters

screenPoint Point

The last pointer position, in screen space.

Remarks

The base implementation calls OnDragEnded(Point), so an element that doesn't care about the difference releases its drag state the same way. Override it to undo whatever the drag did, rather than commit it.

OnDragEnded(Point)

Invoked by Canvas when a drag sequence owned by this element (see GetDragAxes(in DragClaimContext)) has ended - released or canceled. The base implementation does nothing.

protected virtual void OnDragEnded(Point screenPoint)

Parameters

screenPoint Point

The drag's ending position, in screen/window space.

OnDragFling(Vector2)

Invoked by Canvas on the owner of a drag that completed (was released), right before OnDragEnded(Point). It isn't invoked when the drag is canceled. The base implementation does nothing.

protected virtual void OnDragFling(Vector2 screenVelocity)

Parameters

screenVelocity Vector2

The release velocity, in physical pixels per second.

OnDragPerforming(Point)

Invoked by Canvas whenever the pointer moves during a drag sequence owned by this element (see GetDragAxes(in DragClaimContext)). The base implementation does nothing.

protected virtual void OnDragPerforming(Point screenPoint)

Parameters

screenPoint Point

The drag's current position, in screen/window space.

OnDragStarted(Point)

Invoked by Canvas when a drag sequence starts and this element owns it (see GetDragAxes(in DragClaimContext); overriding this method alone receives nothing). The base implementation does nothing.

protected virtual void OnDragStarted(Point screenPoint)

Parameters

screenPoint Point

The drag's starting position, in screen/window space.

OnLocationChanged()

Raises the LocationChanged event.

protected virtual void OnLocationChanged()

OnNavigate(Vector2)

Invoked by Canvas for a directional navigation press (arrow keys, D-pad, left stick) while this element or one of its descendants has focus.

protected virtual bool OnNavigate(Vector2 direction)

Parameters

direction Vector2

The pressed direction: one of the four unit vectors, in UI space (+Y down).

Returns

bool

true to claim the press. Canvas calls the focused element first, then each ancestor, and stops at the first claim. When nothing claims it, focus moves to the nearest control in direction (see MoveFocus(Vector2)). The base implementation returns false.

Remarks

Claim only what you use, and let presses go at your edges (a list at its last row, a caret at the end of its text), so focus can move on to the next control.

OnOpacityChanged()

Raises the OpacityChanged event.

protected virtual void OnOpacityChanged()

OnRender(IRenderContext)

Handles custom render logic when overridden in any UIElement instance.

protected virtual void OnRender(IRenderContext context)

Parameters

context IRenderContext

The context to render with.

OnScroll(ScrollInfo)

Invoked by Canvas when the mouse wheel/touch-swipe scrolls (see Scroll) while this element (or a descendant) is hovered. The base implementation does nothing and returns false.

protected virtual bool OnScroll(ScrollInfo info)

Parameters

info ScrollInfo

The scroll delta and axis.

Returns

bool

true if this element actually consumed the scroll (e.g. a ScrollViewer that had room left to scroll further in info's direction) - Canvas stops dispatching to further ancestors once an element returns true, so one nested scrollable region doesn't also scroll every scrollable ancestor around it. Returning false (e.g. already scrolled to the limit in that direction) lets the event bubble up to an outer scrollable ancestor, which is what makes "overscroll" naturally hand off to it.

OnSizeChanged()

Raises the SizeChanged event.

protected virtual void OnSizeChanged()

OnTap()

Invoked by Canvas when this element (or a descendant) is the target of a completed tap (see Tap). The base implementation does nothing.

protected virtual void OnTap()

Remarks

Called on the hit-tested element and every one of its ancestors (bubbling, with no "handled" flag in v1) - so e.g. a Button reacts to a tap on its label TextBlock just as it would to a tap on its own background.

OnTransformUpdated()

Raises the TransformUpdated event.

protected virtual void OnTransformUpdated()

OnVisibilityChanged()

Raises the VisibilityChanged event.

protected virtual void OnVisibilityChanged()

PointToLocal(Point)

Converts a point in screen/window space (the same space pointer/touch/drag positions arrive in) into this element's own local space (relative to its ActualBounds origin), composing every ancestor's transform from the Canvas down.

public Vector2 PointToLocal(Point screenPoint)

Parameters

screenPoint Point

A point in screen/window space.

Returns

Vector2

The equivalent point in this element's own local space, or Zero if this element isn't currently attached to a Canvas.

Remarks

This is the same math HitTest(Vector2) uses internally during its recursive descent, exposed for controls (e.g. a Slider thumb) that need to react to raw drag points rather than a routed hit-test result.

PointToScreen(Vector2)

Converts a point in this element's own local space (relative to its ActualBounds origin) into screen/window space - the exact inverse of PointToLocal(Point), composing every ancestor's VisualState-independent layout transform up through the Canvas.

public Point PointToScreen(Vector2 localPoint)

Parameters

localPoint Vector2

A point in this element's own local space.

Returns

Point

The equivalent point in screen/window space, or Empty if this element isn't currently attached to a Canvas.

Remarks

Like PointToLocal(Point), only LayoutOffset/LayoutRotation/ LayoutScale are accounted for - RenderOffset/RenderRotation/ RenderScale are treated as purely cosmetic and don't affect the result, matching HitTest(Vector2)'s own scope.

PointToSurface(Vector2)

Converts a point in this element's own local space into the canvas's surface space - the logical, EffectiveScale-independent coordinates that overlays and popups are laid out in.

public Point PointToSurface(Vector2 localPoint)

Parameters

localPoint Vector2

A point in this element's own local space.

Returns

Point

The equivalent point in surface units, or Empty if this element isn't currently attached to a Canvas.

Remarks

Equals PointToScreen(Vector2) divided by EffectiveScale. Use it to position overlay content (dropdowns, popups) relative to this element; use PointToScreen(Vector2) when comparing against raw pointer positions.

RegisterStateGroup(VisualStateGroup)

Registers a visual-state group on this element, immediately applying whichever of its states best matches the current ControlState.

public void RegisterStateGroup(VisualStateGroup group)

Parameters

group VisualStateGroup

The group to register.

Remarks

  • Within a group, the state whose flags form the largest subset of ControlState is active; between equally large matches, the one declared last wins.
  • When active states of several groups set the same property, the group registered last provides the value. Leaving its state hands the property back to the next group's active state, if any.
  • A group registered here ranks above every group a Style registers, whenever that style is applied, the same way a local value outranks a style's. It's never replaced by a style's group of the same Name: name replacement only happens between the groups of the theme's style, a style's BasedOn chain and the style itself.

ResetTransform()

Resets the transform to its default values.

public void ResetTransform()

ResetVisual()

Resets the rendering transform to its default values.

public void ResetVisual()

UnregisterStateGroup(VisualStateGroup)

Unregisters a visual-state group previously added via RegisterStateGroup(VisualStateGroup) or by a Style, clearing whichever of its states is currently active.

public void UnregisterStateGroup(VisualStateGroup group)

Parameters

group VisualStateGroup

The group to unregister.

UpdateTransformMatrix()

Calculates transform matrix and inverse matrix based on the current transform properties.

protected void UpdateTransformMatrix()

UpdateVisual()

Recalculates the render transform based on the current RenderOffset, RenderRotation, RenderTransformOrigin, and RenderScale properties.

protected void UpdateVisual()

Events

ArrangeUpdated

Occurs when the UIElement arrange is updated.

public event EventHandler? ArrangeUpdated

Event Type

EventHandler

Attached

Occurs when the UIElement is attached to the Canvas instance.

public event EventHandler? Attached

Event Type

EventHandler

DataContextChanged

Occurs when the effective DataContext changes - including when it changes only because an ancestor's did, since an element with no DataContext of its own inherits one.

public event EventHandler? DataContextChanged

Event Type

EventHandler

Detached

Occurs when the UIElement is detached from the Canvas instance.

public event EventHandler? Detached

Event Type

EventHandler

FocusChanged

Occurs when the value of the IsFocused property changed.

public event EventHandler? FocusChanged

Event Type

EventHandler

LocationChanged

Occurs when the location of the UIElement is changed.

public event EventHandler? LocationChanged

Event Type

EventHandler

OpacityChanged

Occurs when the value of the Opacity property of the UIElement is changed.

public event EventHandler? OpacityChanged

Event Type

EventHandler

SizeChanged

Occurs when the UIElement size is updated.

public event EventHandler? SizeChanged

Event Type

EventHandler

TransformUpdated

Occurs when the UIElement transform is updated.

public event EventHandler? TransformUpdated

Event Type

EventHandler

VisibilityChanged

Occurs when the value of the IsVisible property of the UIElement is changed.

public event EventHandler? VisibilityChanged

Event Type

EventHandler

Operators

implicit operator UIElement?(string?)

Converts text to a TextBlock showing it, so a string can be used wherever an element is expected: new Button { Content = "Play" }, panel.Children.Add("Score: 0").

public static implicit operator UIElement?(string? text)

Parameters

text string

The text to show; null converts to null.

Returns

UIElement

A new TextBlock whose Text is text.

Remarks

Markup attributes (Content="Play") and bindings (Content="{Binding Title}") convert the same way. A binding creates a new TextBlock each time its value changes; for text that changes often, put a TextBlock in the content and bind its Text instead.