Class Control

Namespace
Forma
Assembly
Forma.dll

Retained-mode UI element modelled after Godot's Control. Coordinates are relative to the parent; anchors and offsets are resolved during layout.

public class Control : IAddChild<Control>, IAddChild, INotifyPropertyChanged
Inheritance
Control
Implements
Derived
Inherited Members

Constructors

Control() 

public Control()

Properties

AccessibilityActions 

public virtual AccessibilityActions AccessibilityActions { get; }

Property Value

AccessibilityActions

AccessibilityBounds 

public Rectangle AccessibilityBounds { get; }

Property Value

Rectangle

AccessibilityId

Identity for this control instance, unique within the process and stable for its whole lifetime. Assigned at construction and never reassigned, so it survives a template reload: reloading rebuilds a template's visual children, not the templated control itself.

This is what lets an accessibility tree be diffed rather than re-walked, and what lets an out-of-process client refer to a node it saw earlier. It is deliberately not an author-facing identifier - use AutomationId for that, since this value is allocation-ordered and so differs between runs. 

public int AccessibilityId { get; }

Property Value

int

AccessibilityLabel 

public string AccessibilityLabel { get; set; }

Property Value

string

AccessibilityName 

public virtual string AccessibilityName { get; }

Property Value

string

AccessibilityPeer 

public AccessibilityPeer AccessibilityPeer { get; }

Property Value

AccessibilityPeer

AccessibilityRole 

public virtual AccessibilityRole AccessibilityRole { get; }

Property Value

AccessibilityRole

AccessibilityStates 

public virtual AccessibilityStates AccessibilityStates { get; }

Property Value

AccessibilityStates

AccessibilityValue 

public virtual string AccessibilityValue { get; }

Property Value

string

AnchorBottom 

public float AnchorBottom { get; }

Property Value

float

AnchorLeft 

public float AnchorLeft { get; }

Property Value

float

AnchorRight 

public float AnchorRight { get; }

Property Value

float

AnchorTop 

public float AnchorTop { get; }

Property Value

float

AspectRatio 

public float AspectRatio { get; set; }

Property Value

float

AutomationId

Stable, author-assigned identifier for tests and automation to target, independent of anything the user sees. Name doubles as the accessible name and so changes when a control is relabelled or localized; an automation id is a contract that does not. Empty by default, in which case callers fall back to role and name.

public string AutomationId { get; set; }

Property Value

string

Bounds 

public Rectangle Bounds { get; }

Property Value

Rectangle

Children 

public ReadOnlyCollection<Control> Children { get; }

Property Value

ReadOnlyCollection<Control>

Classes 

public ControlClassList Classes { get; }

Property Value

ControlClassList

Clip 

public Geometry Clip { get; set; }

Property Value

Geometry

ClipContents 

public bool ClipContents { get; set; }

Property Value

bool

ClipToBounds 

public bool ClipToBounds { get; set; }

Property Value

bool

Context 

public UIContext Context { get; }

Property Value

UIContext

Cursor 

public Cursor Cursor { get; set; }

Property Value

Cursor

CustomMaximumSize 

public Vector2 CustomMaximumSize { get; set; }

Property Value

Vector2

CustomMinimumSize 

public Vector2 CustomMinimumSize { get; set; }

Property Value

Vector2

DataContext 

public object DataContext { get; set; }

Property Value

object

Effect 

public VisualEffect Effect { get; set; }

Property Value

VisualEffect

EffectiveCursor 

public Cursor EffectiveCursor { get; }

Property Value

Cursor

EffectiveLayoutDirection 

public LayoutDirection EffectiveLayoutDirection { get; }

Property Value

LayoutDirection

Enabled 

public bool Enabled { get; set; }

Property Value

bool

FocusBounds 

public Rectangle FocusBounds { get; }

Property Value

Rectangle

FocusMode 

public FocusMode FocusMode { get; set; }

Property Value

FocusMode

FocusNeighborBottom

Optional directional focus neighbor.

public Control FocusNeighborBottom { get; set; }

Property Value

Control

FocusNeighborLeft

Optional directional focus neighbor.

public Control FocusNeighborLeft { get; set; }

Property Value

Control

FocusNeighborRight

Optional directional focus neighbor.

public Control FocusNeighborRight { get; set; }

Property Value

Control

FocusNeighborTop

Optional directional focus neighbor.

public Control FocusNeighborTop { get; set; }

Property Value

Control

FocusNext

Optional explicit focus order used before tree traversal.

public Control FocusNext { get; set; }

Property Value

Control

FocusPrevious

Optional reverse focus order used before tree traversal.

public Control FocusPrevious { get; set; }

Property Value

Control

FontFamily 

public UIFontFamily FontFamily { get; set; }

Property Value

UIFontFamily

FontSize 

public float FontSize { get; set; }

Property Value

float

FontStretch 

public UIFontStretch FontStretch { get; set; }

Property Value

UIFontStretch

FontStyle 

public UIFontStyle FontStyle { get; set; }

Property Value

UIFontStyle

FontWeight 

public UIFontWeight FontWeight { get; set; }

Property Value

UIFontWeight

Foreground 

public Color? Foreground { get; set; }

Property Value

Color?

GlobalPosition 

public Vector2 GlobalPosition { get; }

Property Value

Vector2

HGrowDirection

Matches Godot's Control.GrowHorizontal (default GROW_DIRECTION_END): how the horizontal position compensates when the anchor-resolved width is clamped up to the minimum size.

public GrowDirection HGrowDirection { get; set; }

Property Value

GrowDirection

HasLocalDataContext 

public bool HasLocalDataContext { get; }

Property Value

bool

Height 

public float Height { get; set; }

Property Value

float

HorizontalAlignment 

public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

HorizontalSizeFlags 

public SizeFlags HorizontalSizeFlags { get; set; }

Property Value

SizeFlags

IsEffectivelyEnabled 

public bool IsEffectivelyEnabled { get; }

Property Value

bool

IsHitTestVisible 

public bool IsHitTestVisible { get; set; }

Property Value

bool

IsPixelSnappingEnabled 

public bool IsPixelSnappingEnabled { get; }

Property Value

bool

Language 

public string Language { get; set; }

Property Value

string

LayoutDirection

Controls bidirectional layout inheritance for containers and alignment-aware controls.

public LayoutDirection LayoutDirection { get; set; }

Property Value

LayoutDirection

Margin 

public Thickness Margin { get; set; }

Property Value

Thickness

Margins 

public Thickness Margins { get; set; }

Property Value

Thickness

MaxHeight 

public float MaxHeight { get; set; }

Property Value

float

MaxWidth 

public float MaxWidth { get; set; }

Property Value

float

MinHeight 

public float MinHeight { get; set; }

Property Value

float

MinWidth 

public float MinWidth { get; set; }

Property Value

float

MouseFilter 

public MouseFilter MouseFilter { get; set; }

Property Value

MouseFilter

Name 

public string Name { get; set; }

Property Value

string

OffsetBottom 

public float OffsetBottom { get; }

Property Value

float

OffsetLeft 

public float OffsetLeft { get; }

Property Value

float

OffsetRight 

public float OffsetRight { get; }

Property Value

float

OffsetTop 

public float OffsetTop { get; }

Property Value

float

Opacity 

public float Opacity { get; set; }

Property Value

float

OpacityMask 

public Brush OpacityMask { get; set; }

Property Value

Brush

Parent 

public Control Parent { get; }

Property Value

Control

PixelSnapping 

public PixelSnapping PixelSnapping { get; set; }

Property Value

PixelSnapping

Position 

public Vector2 Position { get; set; }

Property Value

Vector2

RenderTransform 

public Transform RenderTransform { get; set; }

Property Value

Transform

Resources 

public ResourceDictionary Resources { get; }

Property Value

ResourceDictionary

Size 

public Vector2 Size { get; set; }

Property Value

Vector2

SizeFlagsStretchRatio 

public float SizeFlagsStretchRatio { get; set; }

Property Value

float

ThemeOverride

Optional theme applied to this control and inherited by its descendants while drawing.

public Theme ThemeOverride { get; set; }

Property Value

Theme

ThemeStyleOverrides 

public IDictionary<string, StyleBox> ThemeStyleOverrides { get; }

Property Value

IDictionary<string, StyleBox>

ToolTip 

public object ToolTip { get; set; }

Property Value

object

TooltipText

Text presented by UIContext after the pointer rests over this control.

public string TooltipText { get; set; }

Property Value

string

TransformOrigin 

public Vector2 TransformOrigin { get; set; }

Property Value

Vector2

VGrowDirection

Matches Godot's Control.GrowVertical (default GROW_DIRECTION_END): how the vertical position compensates when the anchor-resolved height is clamped up to the minimum size.

public GrowDirection VGrowDirection { get; set; }

Property Value

GrowDirection

VerticalAlignment 

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

VerticalSizeFlags 

public SizeFlags VerticalSizeFlags { get; set; }

Property Value

SizeFlags

Visibility 

public Visibility Visibility { get; set; }

Property Value

Visibility

Visible

Matches Godot's Control.visible: toggling it requeues the parent's layout, since Container wires each child's visibility_changed signal to queue_sort().

public bool Visible { get; set; }

Property Value

bool

VisualBounds 

public Rectangle VisualBounds { get; }

Property Value

Rectangle

VisualParent 

public Control VisualParent { get; }

Property Value

Control

Width 

public float Width { get; set; }

Property Value

float

ZIndex

Drawing and pointer-picking order. Higher values are painted above and receive input before lower values; equal values retain tree insertion order.

public int ZIndex { get; set; }

Property Value

int

Methods

AcceptEvent()

Matches Godot's Control::accept_event(): marks the current input event as handled for just this one dispatch, stopping propagation to ancestors independent of MouseFilter (which only governs every future event). Unlike setting MouseFilter to Stop, this does not affect later events.

protected void AcceptEvent()

AddChild(Control) 

public virtual void AddChild(Control child)

Parameters

child Control

AddThemeIconOverride(string, ThemeIcon)

Adds a local decorative theme-icon override. Existing content-icon properties are unaffected.

public void AddThemeIconOverride(string itemName, ThemeIcon icon)

Parameters

itemName string
icon ThemeIcon

AddThemeStyleOverride(string, StyleBox)

Sets a local StyleBox override, equivalent to Godot's add_theme_style_override.

public void AddThemeStyleOverride(string itemName, StyleBox styleBox)

Parameters

itemName string
styleBox StyleBox

ArrangeChildren() 

protected virtual void ArrangeChildren()

BringIntoView(Rectangle?) 

public void BringIntoView(Rectangle? targetBounds = null)

Parameters

targetBounds Rectangle?

CanDropData(Point, object)

Returns whether this control accepts the supplied data at the screen position.

public virtual bool CanDropData(Point position, object data)

Parameters

position Point
data object

Returns

bool

ClearDataContext() 

public void ClearDataContext()

ContainsPoint(Point) 

public virtual bool ContainsPoint(Point point)

Parameters

point Point

Returns

bool

CreateAccessibilityPeer() 

protected virtual AccessibilityPeer CreateAccessibilityPeer()

Returns

AccessibilityPeer

DropData(Point, object)

Receives data accepted by CanDropData(Point, object).

public virtual void DropData(Point position, object data)

Parameters

position Point
data object

FindName<T>(string) 

public T FindName<T>(string name) where T : class

Parameters

name string

Returns

T

Type Parameters

T

GetAccessibilityChildren() 

public virtual IReadOnlyList<AccessibilityPeer> GetAccessibilityChildren()

Returns

IReadOnlyList<AccessibilityPeer>

GetBoundDesiredSize()

Returns the desired size clamped to this control's minimum and combined maximum sizes.

public Vector2 GetBoundDesiredSize()

Returns

Vector2

GetCombinedMaximumSize() 

public Vector2 GetCombinedMaximumSize()

Returns

Vector2

GetCursorAt(Point)

Cursor for one pointer position, in the same global coordinates pointer events receive. Controls with a sub-region that behaves differently from the rest of their surface - a split container's dragger, a resize grip - override this so the pointer advertises that region before it is pressed; everything else applies EffectiveCursor across its whole extent. Mirrors Godot's Control._get_cursor_shape.

public virtual Cursor GetCursorAt(Point position)

Parameters

position Point

Returns

Cursor

GetDesiredSize()

Returns this control's preferred size before minimum-size clamping, matching Godot's virtual get_desired_size().

public virtual Vector2 GetDesiredSize()

Returns

Vector2

GetDragData(Point)

Returns data to drag, or null to decline starting a drag.

public virtual object GetDragData(Point position)

Parameters

position Point

Returns

object

GetMaximumSize()

Returns this control's intrinsic maximum size; negative components are unbounded.

public virtual Vector2 GetMaximumSize()

Returns

Vector2

GetMinimumSize() 

public virtual Vector2 GetMinimumSize()

Returns

Vector2

GetNodeOrNull(string) 

public Control GetNodeOrNull(string name)

Parameters

name string

Returns

Control

GetThemeIcon(string)

Resolves a decorative icon from local overrides, ancestor themes, and the context theme.

public ThemeIcon? GetThemeIcon(string itemName)

Parameters

itemName string

Returns

ThemeIcon?

GetThemeIcon(string, string) 

protected ThemeIcon? GetThemeIcon(string itemName, string preferredTypeName)

Parameters

itemName string
preferredTypeName string

Returns

ThemeIcon?

GetThemeStyleBox(string) 

public StyleBox GetThemeStyleBox(string itemName)

Parameters

itemName string

Returns

StyleBox

GetTooltip(Point)

Returns the tooltip at a global pointer position. Override to provide dynamic help text.

public virtual string GetTooltip(Point position)

Parameters

position Point

Returns

string

GrabFocus() 

public void GrabFocus()

IsLayoutRtl()

Whether this control resolves to right-to-left layout.

public bool IsLayoutRtl()

Returns

bool

IsPseudoStateActive(string) 

public virtual bool IsPseudoStateActive(string state)

Parameters

state string

Returns

bool

MoveChild(Control, int)

Moves an existing child to a different sibling index without changing its parent or UI context.

public void MoveChild(Control child, int toIndex)

Parameters

child Control
toIndex int

NotifyPseudoStateChanged(string) 

protected void NotifyPseudoStateChanged(string state)

Parameters

state string

OnContextChanged(UIContext, UIContext)

Called when this control enters, exits, or moves between retained UI contexts.

protected virtual void OnContextChanged(UIContext previous, UIContext current)

Parameters

previous UIContext
current UIContext

OnPropertyChanged(string) 

protected virtual void OnPropertyChanged(string propertyName)

Parameters

propertyName string

OnThemeChanged() 

protected virtual void OnThemeChanged()

PerformAccessibilityAction(AccessibilityActions, object)

Performs one advertised accessibility action, returning whether it was handled.

Overrides must route through the same code the corresponding real input runs, never a parallel implementation. An invoked press that takes a shortcut would make a test pass while telling you nothing about whether a person clicking the thing works. 

public virtual bool PerformAccessibilityAction(AccessibilityActions action, object argument = null)

Parameters

action AccessibilityActions
argument object

Returns

bool

PointerMoved(Point)

The pointer moved over this control, in global coordinates.

protected virtual void PointerMoved(Point position)

Parameters

position Point

PointerPressed(Point)

A pointer press landed on this control, in global coordinates.

Protected as well as internal so a control defined outside this assembly can take part in pointer input. Without that, an app hosting its own drawing surface has to read raw mouse state instead, which bypasses hit-testing, modal gating and the injection side-channel — so such a surface cannot be driven by a test at all. 

protected virtual void PointerPressed(Point position)

Parameters

position Point

PointerReleased(Point, bool)

The pointer was released, with whether it was still inside this control.

protected virtual void PointerReleased(Point position, bool isInside)

Parameters

position Point
isInside bool

QueueLayout() 

public void QueueLayout()

ReleaseFocus() 

public void ReleaseFocus()

RemoveChild(Control) 

public bool RemoveChild(Control child)

Parameters

child Control

Returns

bool

RemoveFromParent() 

public void RemoveFromParent()

RemoveThemeIconOverride(string)

Removes a local icon override so theme inheritance becomes visible again.

public void RemoveThemeIconOverride(string itemName)

Parameters

itemName string

RemoveThemeStyleOverride(string) 

public void RemoveThemeStyleOverride(string itemName)

Parameters

itemName string

SetAnchor(Side, float, bool, bool)

Matches Godot's Control::set_anchor exactly: by default (keepOffset false) the offset is recomputed so the control's resolved position does not jump when only the anchor changes, an anchor is never allowed to cross its opposite anchor (clamped to it, or pushing the opposite anchor along when pushOppositeAnchor is set), and geometry is refreshed via QueueLayout().

public void SetAnchor(Side side, float anchor, bool keepOffset = false, bool pushOppositeAnchor = false)

Parameters

side Side
anchor float
keepOffset bool
pushOppositeAnchor bool

SetAnchorsAndOffsets(float, float, float, float) 

public void SetAnchorsAndOffsets(float left, float top, float right, float bottom)

Parameters

left float
top float
right float
bottom float

SetOffset(Side, float) 

public void SetOffset(Side side, float offset)

Parameters

side Side
offset float

SetPseudoState(string, bool) 

protected void SetPseudoState(string state, bool active)

Parameters

state string
active bool

SuppressThemeIcon(string)

Suppresses a decorative theme icon on this control without affecting content icons.

public void SuppressThemeIcon(string itemName)

Parameters

itemName string

TryFindResource(string, out object) 

public bool TryFindResource(string key, out object value)

Parameters

key string
value object

Returns

bool

Events

AccessibilityChanged 

public event EventHandler<AccessibilityChangedEventArgs> AccessibilityChanged

Event Type

EventHandler<AccessibilityChangedEventArgs>

Attached 

public event EventHandler Attached

Event Type

EventHandler

BringIntoViewRequested 

public event EventHandler<BringIntoViewRequestedEventArgs> BringIntoViewRequested

Event Type

EventHandler<BringIntoViewRequestedEventArgs>

ChildAdded 

public event Action<Control, Control> ChildAdded

Event Type

Action<Control, Control>

ChildRemoved 

public event Action<Control, Control> ChildRemoved

Event Type

Action<Control, Control>

DataContextChanged 

public event EventHandler<DataContextChangedEventArgs> DataContextChanged

Event Type

EventHandler<DataContextChangedEventArgs>

Detached 

public event EventHandler Detached

Event Type

EventHandler

DragEnded

Raised when a drag started by this control ends; the boolean indicates whether it was accepted.

public event Action<Control, bool> DragEnded

Event Type

Action<Control, bool>

DragStarted

Raised when this control supplies drag data after the pointer passes the drag threshold.

public event Action<Control, object> DragStarted

Event Type

Action<Control, object>

EnabledChanged 

public event EventHandler EnabledChanged

Event Type

EventHandler

FocusEntered 

public event EventHandler FocusEntered

Event Type

EventHandler

FocusExited 

public event EventHandler FocusExited

Event Type

EventHandler

LayoutChanged 

public event EventHandler LayoutChanged

Event Type

EventHandler

MouseEntered 

public event EventHandler MouseEntered

Event Type

EventHandler

MouseExited 

public event EventHandler MouseExited

Event Type

EventHandler

NameChanged 

public event EventHandler NameChanged

Event Type

EventHandler

ParentChanged 

public event EventHandler<ControlParentChangedEventArgs> ParentChanged

Event Type

EventHandler<ControlParentChangedEventArgs>

PropertyChanged 

public event PropertyChangedEventHandler PropertyChanged

Event Type

PropertyChangedEventHandler

PseudoStateChanged 

public event EventHandler<ControlPseudoStateChangedEventArgs> PseudoStateChanged

Event Type

EventHandler<ControlPseudoStateChangedEventArgs>
Edit this page