Table of Contents

Class UIElement

Namespace
PluginUI
Assembly
PluginUI.dll

Base class of everything in the visual tree: layout (measure/arrange), rendering, hit testing and input.

public abstract class UIElement
Inheritance
UIElement
Derived
Inherited Members

Remarks

Coordinates. Bounds are absolute DIPs in host space after layout: rendering and hit testing need no coordinate transforms.

Layout. WPF-like two-pass layout: Measure(Size) computes DesiredSize from MeasureOverride(Size), Arrange(Rect) assigns Bounds and calls ArrangeOverride(Rect). Explicit Width/Height, min/max sizes, Margin and alignments are applied by the base class.

Extending. Override OnRender(DrawingContext) to draw, MeasureOverride(Size) to report a natural size, and the On… input methods to react to the mouse and keyboard.

Threading. UI thread only. Use Post(Action) to marshal work from other threads.

Properties

AllowFileDrop

Accepts files dropped from the shell (raises OnFilesDropped(FilesDroppedEventArgs)).

public bool AllowFileDrop { get; set; }

Property Value

bool

Bounds

Arranged rectangle in host DIPs, margins excluded.

[Browsable(false)]
public Rect Bounds { get; }

Property Value

Rect

ClipToBounds

Clips children to Bounds.

public bool ClipToBounds { get; set; }

Property Value

bool

Column

Column inside a Grid.

public int Column { get; set; }

Property Value

int

ColumnSpan

Columns spanned inside a Grid.

public int ColumnSpan { get; set; }

Property Value

int

ContextMenu

Context menu shown on right click (unless the click is handled).

[Browsable(false)]
public IList<MenuItem>? ContextMenu { get; set; }

Property Value

IList<MenuItem>

Cursor

Cursor over this element (Default inherits).

public StandardCursor Cursor { get; set; }

Property Value

StandardCursor

DesiredSize

Size requested by the last Measure(Size), margins included.

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

Property Value

Size

Dock

Docking side inside a DockPanel.

public Side Dock { get; set; }

Property Value

Side

Focusable

Can receive keyboard focus.

public bool Focusable { get; set; }

Property Value

bool

Height

Explicit height in DIPs (NaN = automatic).

public float Height { get; set; }

Property Value

float

HorizontalAlignment

Horizontal placement in the layout slot.

public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

Host

Host this element is attached to (null when detached).

[Browsable(false)]
public UIHost? Host { get; }

Property Value

UIHost

IsEffectivelyEnabled

true if this element and all its ancestors are enabled.

public bool IsEffectivelyEnabled { get; }

Property Value

bool

IsEnabled

Accepts input when true; drawn dimmed otherwise.

public bool IsEnabled { get; set; }

Property Value

bool

IsFocused

true if this element has keyboard focus.

public bool IsFocused { get; }

Property Value

bool

IsHitTestVisible

Participates in hit testing when true.

public bool IsHitTestVisible { get; set; }

Property Value

bool

IsMouseCaptured

true if this element holds the mouse capture.

public bool IsMouseCaptured { get; }

Property Value

bool

IsMouseOver

true while the mouse is over this element or one of its descendants.

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

Property Value

bool

IsVisible

Visible and taking layout space when true; collapsed otherwise.

public bool IsVisible { get; set; }

Property Value

bool

Left

X position inside a Canvas.

public float Left { get; set; }

Property Value

float

Margin

Outer spacing.

public Thickness Margin { get; set; }

Property Value

Thickness

MaxHeight

Maximum height.

public float MaxHeight { get; set; }

Property Value

float

MaxWidth

Maximum width.

public float MaxWidth { get; set; }

Property Value

float

MinHeight

Minimum height.

public float MinHeight { get; set; }

Property Value

float

MinWidth

Minimum width.

public float MinWidth { get; set; }

Property Value

float

Name

Optional name (used by the live editor, FindByName(string) and as field name by PluginUIEditor).

public string? Name { get; set; }

Property Value

string

Opacity

Opacity multiplier (0..1) applied to the element and its children.

public float Opacity { get; set; }

Property Value

float

Parent

Parent element (null for the root and popups).

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

Property Value

UIElement

Row

Row inside a Grid.

public int Row { get; set; }

Property Value

int

RowSpan

Rows spanned inside a Grid.

public int RowSpan { get; set; }

Property Value

int

Strings

Texts of the user interface language in effect (Strings), or those of DefaultLanguage while the element is not attached to a host.

protected UIStrings Strings { get; }

Property Value

UIStrings

Tag

Free user data.

[Browsable(false)]
public object? Tag { get; set; }

Property Value

object

TextMeasurer

Text measurement (device-accurate when attached, approximate otherwise).

public ITextMeasurer TextMeasurer { get; }

Property Value

ITextMeasurer

Theme

Theme in effect (host theme, or the default dark theme when detached).

public Theme Theme { get; }

Property Value

Theme

ToolTip

Tooltip text shown after hovering.

public string? ToolTip { get; set; }

Property Value

string

Top

Y position inside a Canvas.

public float Top { get; set; }

Property Value

float

UseOpacityLayer

Applies Opacity through an offscreen layer: the element and its children are drawn opaque, then blended as one image, so overlapping children do not show through each other. Costs a layer per frame; by default opacity is a cheaper global alpha (as in VSTGUI). Children of a LayeredPanel use layers automatically (CompositeLayers).

public bool UseOpacityLayer { get; set; }

Property Value

bool

VerticalAlignment

Vertical placement in the layout slot.

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

VisualChildren

Child elements in drawing order (back to front).

public virtual IReadOnlyList<UIElement> VisualChildren { get; }

Property Value

IReadOnlyList<UIElement>

Width

Explicit width in DIPs (NaN = automatic).

public float Width { get; set; }

Property Value

float

Methods

Arrange(Rect)

Assigns the final layout slot (margins included) and arranges children.

public void Arrange(Rect slot)

Parameters

slot Rect

ArrangeOverride(Rect)

Arranges children inside the final bounds.

protected virtual void ArrangeOverride(Rect bounds)

Parameters

bounds Rect

CaptureMouse()

Captures the mouse: move/up events go to this element until released.

public void CaptureMouse()

DescendantsAndSelf()

Enumerates this element and all descendants (depth first).

public IEnumerable<UIElement> DescendantsAndSelf()

Returns

IEnumerable<UIElement>

FindByName(string)

Finds a descendant (or this element) by Name.

public UIElement? FindByName(string name)

Parameters

name string

Returns

UIElement

Focus()

Gives keyboard focus to this element.

public bool Focus()

Returns

bool

GetToolTipText()

Tooltip actually shown: ToolTip by default. Override to supply a computed or localized text (for example from Strings) when ToolTip is not set.

protected virtual string? GetToolTipText()

Returns

string

The text to show, or null / empty for no tooltip.

HitTest(Point)

Returns true if the point hits this element (children excluded). Default: inside Bounds.

public virtual bool HitTest(Point point)

Parameters

point Point

Returns

bool

HitTestTree(Point)

Deepest visible, enabled, hit-testable element under the point.

public UIElement? HitTestTree(Point point)

Parameters

point Point

Returns

UIElement

InvalidateMeasure()

Requests a new layout pass.

public void InvalidateMeasure()

InvalidateVisual()

Requests a repaint.

public void InvalidateVisual()

IsAncestorOf(UIElement?)

true if element is this element or one of its descendants.

public bool IsAncestorOf(UIElement? element)

Parameters

element UIElement

Returns

bool

Measure(Size)

Computes DesiredSize for the given available size (margins included).

public void Measure(Size available)

Parameters

available Size

MeasureOverride(Size)

Natural size of the content for the available size (margins excluded).

protected virtual Size MeasureOverride(Size available)

Parameters

available Size

Returns

Size

OnAttached()

Called when the element joins a host (subscribe to external events here).

protected virtual void OnAttached()

OnCaptureLost()

The mouse capture was lost without a button release.

protected virtual void OnCaptureLost()

OnDetached()

Called when the element leaves its host (unsubscribe here).

protected virtual void OnDetached()

OnDragLeave()

Internal drag left this element.

protected virtual void OnDragLeave()

OnDragOver(DragEventArgs)

Internal drag over this element: set Accept to accept.

protected virtual void OnDragOver(DragEventArgs e)

Parameters

e DragEventArgs

OnDrop(DragEventArgs)

Internal drop on this element.

protected virtual void OnDrop(DragEventArgs e)

Parameters

e DragEventArgs

OnFilesDropped(FilesDroppedEventArgs)

Files dropped from the shell (requires AllowFileDrop on this element or an ancestor).

protected virtual void OnFilesDropped(FilesDroppedEventArgs e)

Parameters

e FilesDroppedEventArgs

OnGotFocus()

Received keyboard focus.

protected virtual void OnGotFocus()

OnKeyDown(KeyEventArgs)

Key pressed while focused (bubbles to parents).

protected virtual void OnKeyDown(KeyEventArgs e)

Parameters

e KeyEventArgs

OnKeyUp(KeyEventArgs)

Key released while focused.

protected virtual void OnKeyUp(KeyEventArgs e)

Parameters

e KeyEventArgs

OnLostFocus()

Lost keyboard focus.

protected virtual void OnLostFocus()

OnMouseDown(MouseEventArgs)

Mouse button pressed over the element (or captured).

protected virtual void OnMouseDown(MouseEventArgs e)

Parameters

e MouseEventArgs

OnMouseEnter()

The mouse entered the element.

protected virtual void OnMouseEnter()

OnMouseLeave()

The mouse left the element.

protected virtual void OnMouseLeave()

OnMouseMove(MouseEventArgs)

Mouse moved over the element (or captured).

protected virtual void OnMouseMove(MouseEventArgs e)

Parameters

e MouseEventArgs

OnMouseUp(MouseEventArgs)

Mouse button released.

protected virtual void OnMouseUp(MouseEventArgs e)

Parameters

e MouseEventArgs

OnMouseWheel(MouseEventArgs)

Mouse wheel over the element.

protected virtual void OnMouseWheel(MouseEventArgs e)

Parameters

e MouseEventArgs

OnRender(DrawingContext)

Draws the element (below its children).

protected virtual void OnRender(DrawingContext dc)

Parameters

dc DrawingContext

OnRenderOverlay(DrawingContext)

Draws above the children (focus rings, overlays...).

protected virtual void OnRenderOverlay(DrawingContext dc)

Parameters

dc DrawingContext

OnTextInput(TextInputEventArgs)

Character typed while focused.

protected virtual void OnTextInput(TextInputEventArgs e)

Parameters

e TextInputEventArgs

OnVisibilityChanged()

Called when IsVisible changes.

protected virtual void OnVisibilityChanged()

ReleaseMouseCapture()

Releases the mouse capture held by this element.

public void ReleaseMouseCapture()

SetBounds(float, float, float, float)

Positions and sizes the element (absolute layout inside a Canvas).

public void SetBounds(float x, float y, float width, float height)

Parameters

x float
y float
width float
height float

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

Events

KeyDown

Raised on key press.

public event Action<UIElement, KeyEventArgs>? KeyDown

Event Type

Action<UIElement, KeyEventArgs>

MouseDown

Raised on mouse button press (after OnMouseDown(MouseEventArgs)).

public event Action<UIElement, MouseEventArgs>? MouseDown

Event Type

Action<UIElement, MouseEventArgs>

MouseMove

Raised on mouse move.

public event Action<UIElement, MouseEventArgs>? MouseMove

Event Type

Action<UIElement, MouseEventArgs>

MouseUp

Raised on mouse button release.

public event Action<UIElement, MouseEventArgs>? MouseUp

Event Type

Action<UIElement, MouseEventArgs>

MouseWheel

Raised on mouse wheel.

public event Action<UIElement, MouseEventArgs>? MouseWheel

Event Type

Action<UIElement, MouseEventArgs>
Edit this page