Table of Contents

Class UIElement

Namespace
Stride.UI
Assembly
Stride.UI.dll

Provides a base class for all the User Interface elements in Stride applications.

[DataContract(Inherited = true)]
[CategoryOrder(10, "Appearance", Expand = ExpandRule.Auto)]
[CategoryOrder(20, "Behavior", Expand = ExpandRule.Auto)]
[CategoryOrder(30, "Layout", Expand = ExpandRule.Auto)]
[CategoryOrder(100, "Misc", Expand = ExpandRule.Auto)]
public abstract class UIElement : IUIElementUpdate, IUIElementChildren, IIdentifiable
Inheritance
UIElement
Implements
Derived
Extension Methods

Constructors

UIElement()

Creates a new instance of UIElement.

protected UIElement()

Fields

AppearanceCategory 

protected const string AppearanceCategory = "Appearance"

Field Value

string

ArrangeChanged 

protected bool ArrangeChanged

Field Value

bool

BehaviorCategory 

protected const string BehaviorCategory = "Behavior"

Field Value

string

InputCategory 

protected const string InputCategory = "Input"

Field Value

string

LayoutCategory 

protected const string LayoutCategory = "Layout"

Field Value

string

LocalMatrixChanged 

protected bool LocalMatrixChanged

Field Value

bool

MarginInternal 

protected Thickness MarginInternal

Field Value

Thickness

MiscCategory 

protected const string MiscCategory = "Misc"

Field Value

string

PanelCategory 

protected const string PanelCategory = "Panel"

Field Value

string

Properties

ActualDepth

Gets the rendered depth of this element.

public float ActualDepth { get; }

Property Value

float

ActualHeight

Gets the rendered height of this element.

public float ActualHeight { get; }

Property Value

float

ActualWidth

Gets the rendered width of this element.

public float ActualWidth { get; }

Property Value

float

BackgroundColor

The background color of the element.

[DataMember]
[Display(null, "Appearance")]
public Color BackgroundColor { get; set; }

Property Value

Color

CanBeHitByUser

Indicate if the UIElement can be hit by the user. If this property is true, the UI system performs hit test on the UIElement.

[DataMember]
[Display(null, "Behavior")]
public bool CanBeHitByUser { get; set; }

Property Value

bool

ClipToBounds

Gets or sets a value indicating whether to clip the content of this element (or content coming from the child elements of this element) to fit into the size of the containing element.

[DataMember]
[Display(null, "Appearance")]
public bool ClipToBounds { get; set; }

Property Value

bool

Exceptions

ArgumentOutOfRangeException

The value has to be positive and finite.

DefaultDepth

Gets or sets the default width of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float DefaultDepth { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

DefaultHeight

Gets or sets the default height of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float DefaultHeight { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

DefaultWidth

Gets or sets the default width of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float DefaultWidth { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

DependencyProperties

The list of the dependency properties attached to the UI element.

[DataMember]
public PropertyContainerClass DependencyProperties { get; }

Property Value

PropertyContainerClass

Depth

Gets or sets the user suggested depth of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float Depth { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

DepthAlignment

Gets or sets the depth alignment of this element.

[DataMember]
[Display(null, "Layout")]
public DepthAlignment DepthAlignment { get; set; }

Property Value

DepthAlignment

DepthBias

The final depth bias value of the element resulting from the parent/children z order update.

public int DepthBias { get; }

Property Value

int

DesiredSize

Gets the size that this element computed during the measure pass of the layout process.

public Vector3 DesiredSize { get; }

Property Value

Vector3

Remarks

This value does not contain possible Margin

DesiredSizeWithMargins

Gets the size that this element computed during the measure pass of the layout process.

public Vector3 DesiredSizeWithMargins { get; }

Property Value

Vector3

Remarks

This value contains possible Margin

DrawLayerNumber

The number of layers used to draw this element. This value has to be modified by the user when he redefines the default element renderer, so that DepthBias values of the relatives keeps enough spaces to draw the different layers.

[DataMember]
[Display(null, "Appearance")]
public int DrawLayerNumber { get; set; }

Property Value

int

Height

Gets or sets the user suggested height of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float Height { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

HitableChildren

The list of the children of the element that can be hit by the user.

protected virtual FastCollection<UIElement> HitableChildren { get; }

Property Value

FastCollection<UIElement>

HorizontalAlignment

Gets or sets the horizontal alignment of this element.

[DataMember]
[Display(null, "Layout")]
public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

Id

A unique ID defining the UI element.

[DataMember]
[Display(null, null, Browsable = false)]
public Guid Id { get; set; }

Property Value

Guid

IsArrangeValid

Gets a value indicating whether the computed size and position of child elements in this element's layout are valid.

public bool IsArrangeValid { get; }

Property Value

bool

IsCollapsed

Gets a value indicating whether this element takes some place in the user interface.

public bool IsCollapsed { get; }

Property Value

bool

IsEnabled

Gets or sets a value indicating whether this element is enabled in the user interface (UI).

[DataMember]
[Display(null, "Behavior")]
public virtual bool IsEnabled { get; set; }

Property Value

bool

IsHierarchyEnabled

Gets the value indicating whether this element and all its upper hierarchy are enabled or not.

public bool IsHierarchyEnabled { get; }

Property Value

bool

IsMeasureValid

Gets a value indicating whether the current size returned by layout measure is valid.

public bool IsMeasureValid { get; }

Property Value

bool

IsTouched

Gets a value indicating whether the UIElement is currently touched by the user.

public bool IsTouched { get; }

Property Value

bool

IsVisible

Gets a value indicating whether this element is visible in the user interface (UI).

public bool IsVisible { get; }

Property Value

bool

LayoutingContext

The ratio between the element real size on the screen and the element virtual size.

protected LayoutingContext LayoutingContext { get; set; }

Property Value

LayoutingContext

LocalMatrix

Gets or sets the LocalMatrix of this element.

public Matrix LocalMatrix { get; set; }

Property Value

Matrix

Remarks

The local transform is not taken is account during the layering. The transformation is purely for rendering effects.

Margin

Gets or sets the margins of this element.

[DataMember]
[Display(null, "Layout")]
public Thickness Margin { get; set; }

Property Value

Thickness

MaximumDepth

Gets or sets the maximum height of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float MaximumDepth { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, PositiveInfinity].

MaximumHeight

Gets or sets the maximum height of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float MaximumHeight { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, PositiveInfinity].

MaximumWidth

Gets or sets the maximum width of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float MaximumWidth { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, PositiveInfinity].

MinimumDepth

Gets or sets the minimum height of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float MinimumDepth { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

MinimumHeight

Gets or sets the minimum height of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float MinimumHeight { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

MinimumWidth

Gets or sets the minimum width of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float MinimumWidth { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

MouseOverState

Gets the current state of the mouse over the UI element.

public MouseOverState MouseOverState { get; }

Property Value

MouseOverState

Remarks

Only elements that can be clicked by user can have the MouseOverState.MouseOverElement value. That is element that have CanBeHitByUser set to true

Name

Gets or sets the name of this element.

[DataMember]
[Display(null, "Misc")]
public string Name { get; set; }

Property Value

string

Opacity

Gets or sets the opacity factor applied to the entire UIElement when it is rendered in the user interface (UI).

[DataMember]
[DataMemberRange(0, 1, 0.009999999776482582, 0.10000000149011612, 2)]
[Display(null, "Appearance")]
public float Opacity { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, 1].

Parent

Gets the logical parent of this element.

public UIElement Parent { get; protected set; }

Property Value

UIElement

RenderOffsets

The rendering offsets caused by the UIElement margins and alignments.

public Vector3 RenderOffsets { get; }

Property Value

Vector3

RenderOpacity

The opacity used to render element.

public float RenderOpacity { get; }

Property Value

float

RenderSize

Gets (or sets, but see Remarks) the final render size of this element.

public Vector3 RenderSize { get; }

Property Value

Vector3

RequiresMouseOverUpdate

Gets or sets whether this element requires a mouse over check.

public bool RequiresMouseOverUpdate { get; set; }

Property Value

bool

Remarks

By default, the engine does not check whether MouseOverState of the element is changed while the cursor is still. This behavior is overriden when this parameter is set to true, which forces the engine to check for changes of MouseOverState. The engine sets this to true when the layout of the element changes.

Size

Gets or sets the size of the element. Same as setting separately Width, Height, and Depth

public Vector3 Size { get; set; }

Property Value

Vector3

VerticalAlignment

Gets or sets the vertical alignment of this element.

[DataMember]
[Display(null, "Layout")]
public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

Visibility

Gets or sets the user interface (UI) visibility of this element.

[DataMember]
[Display(null, "Appearance")]
public Visibility Visibility { get; set; }

Property Value

Visibility

VisualChildren

Get a enumerable to the visual children of the UIElement.

public IReadOnlyList<UIElement> VisualChildren { get; }

Property Value

IReadOnlyList<UIElement>

Remarks

Inherited classes are in charge of overriding this method to return their children.

VisualChildrenCollection

The visual children of this element.

protected UIElementCollection VisualChildrenCollection { get; }

Property Value

UIElementCollection

Remarks

If the class is inherited it is the responsibility of the descendant class to correctly update this collection

VisualParent

Gets the visual parent of this element.

public UIElement VisualParent { get; protected set; }

Property Value

UIElement

Width

Gets or sets the user suggested width of this element.

[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float Width { get; set; }

Property Value

float

Remarks

The value is coerced in the range [0, MaxValue].

WorldMatrix

The world matrix of the UIElement. The origin of the element is the center of the object's bounding box defined by RenderSize.

public Matrix WorldMatrix { get; }

Property Value

Matrix

Methods

AddHandler<T>(RoutedEvent<T>, EventHandler<T>, bool)

Adds a routed event handler for a specified routed event, adding the handler to the handler collection on the current element. Specify handledEventsToo as true to have the provided handler be invoked for routed event that had already been marked as handled by another element along the event route.

public void AddHandler<T>(RoutedEvent<T> routedEvent, EventHandler<T> handler, bool handledEventsToo = false) where T : RoutedEventArgs

Parameters

routedEvent RoutedEvent<T>

An identifier for the routed event to be handled.

handler EventHandler<T>

A reference to the handler implementation.

handledEventsToo bool

true to register the handler such that it is invoked even when the routed event is marked handled in its event data; false to register the handler with the default condition that it will not be invoked if the routed event is already marked handled.

Type Parameters

T

Exceptions

ArgumentNullException

Provided handler or routed event is null.

Arrange(Vector3, bool)

Positions child elements and determines the size of the UIElement. This method constitutes the second pass of a layout update.

public void Arrange(Vector3 finalSizeWithMargins, bool isParentCollapsed)

Parameters

finalSizeWithMargins Vector3

The final size that the parent computes for the child element with the margins.

isParentCollapsed bool

Boolean indicating if one of the parents of the element is currently collapsed.

ArrangeOverride(Vector3)

When overridden in a derived class, positions possible child elements and determines a size for a UIElement derived class.

protected virtual Vector3 ArrangeOverride(Vector3 finalSizeWithoutMargins)

Parameters

finalSizeWithoutMargins Vector3

The final area within the parent that this element should use to arrange itself and its children.

Returns

Vector3

The actual size used.

CalculateAdjustmentOffsets(ref Thickness, ref Vector3, ref Vector3)

Computes the (X,Y,Z) offsets to position correctly the UI element given the total provided space to it.

protected Vector3 CalculateAdjustmentOffsets(ref Thickness thickness, ref Vector3 providedSpace, ref Vector3 usedSpaceWithoutThickness)

Parameters

thickness Thickness

The thickness around the element to position.

providedSpace Vector3

The total space given to the child element by the parent

usedSpaceWithoutThickness Vector3

The space used by the child element without the thickness included in it.

Returns

Vector3

The offsets

CalculateSizeWithThickness(ref Vector3, ref Thickness)

Add the thickness values into the size calculation of a UI element.

protected static Vector3 CalculateSizeWithThickness(ref Vector3 sizeWithoutMargins, ref Thickness thickness)

Parameters

sizeWithoutMargins Vector3

The size without the thickness included

thickness Thickness

The thickness to add to the space

Returns

Vector3

The size with the margins included

CalculateSizeWithoutThickness(ref Vector3, ref Thickness)

Remove the thickness values into the size calculation of a UI element.

protected static Vector3 CalculateSizeWithoutThickness(ref Vector3 sizeWithMargins, ref Thickness thickness)

Parameters

sizeWithMargins Vector3

The size with the thickness included

thickness Thickness

The thickness to remove in the space

Returns

Vector3

The size with the margins not included

CollapseOverride()

When overridden in a derived class, collapse possible child elements and derived class.

protected virtual void CollapseOverride()

EnumerateChildren()

Enumerates the children of this element.

protected virtual IEnumerable<IUIElementChildren> EnumerateChildren()

Returns

IEnumerable<IUIElementChildren>

A sequence containing all the children of this element.

Remarks

This method is used by the implementation of the IUIElementChildren interface.

FindName(string)

Finds an element that has the provided identifier name in the element children.

public UIElement FindName(string name)

Parameters

name string

The name of the requested element.

Returns

UIElement

The requested element. This can be null if no matching element was found.

Remarks

If several elements with the same name exist return the first found

Intersects(ref Ray, out Vector3)

Calculate the intersection of the UI element and the ray.

protected virtual bool Intersects(ref Ray ray, out Vector3 intersectionPoint)

Parameters

ray Ray

The ray in world space coordinate

intersectionPoint Vector3

The intersection point in world space coordinate

Returns

bool

true if the two elements intersects, false otherwise

InvalidateArrange()

Invalidates the arrange state (layout) for the element.

protected void InvalidateArrange()

InvalidateMeasure()

Invalidates the measurement state (layout) for the element.

protected void InvalidateMeasure()

Measure(Vector3)

Updates the DesiredSize of a UIElement. Parent elements call this method from their own implementations to form a recursive layout update. Calling this method constitutes the first pass (the "Measure" pass) of a layout update.

public void Measure(Vector3 availableSizeWithMargins)

Parameters

availableSizeWithMargins Vector3

The available space that a parent element can allocate a child element with its margins. A child element can request a larger space than what is available; the provided size might be accommodated if scrolling is possible in the content model for the current element.

MeasureOverride(Vector3)

When overridden in a derived class, measures the size in layout required for possible child elements and determines a size for the UIElement-derived class.

protected virtual Vector3 MeasureOverride(Vector3 availableSizeWithoutMargins)

Parameters

availableSizeWithoutMargins Vector3

The available size that this element can give to child elements. Infinity can be specified as a value to indicate that the element will size to whatever content is available.

Returns

Vector3

The size desired by the children

OnNameChanged()

This method is call when the name of the UIElement changes. This method can be overridden in inherited classes to perform class specific actions on Name changes.

protected virtual void OnNameChanged()

OnPreviewTouchDown(TouchEventArgs)

The class handler of the event PreviewTouchDown. This method can be overridden in inherited classes to perform actions common to all instances of a class.

protected virtual void OnPreviewTouchDown(TouchEventArgs args)

Parameters

args TouchEventArgs

The arguments of the event

OnPreviewTouchMove(TouchEventArgs)

The class handler of the event PreviewTouchMove. This method can be overridden in inherited classes to perform actions common to all instances of a class.

protected virtual void OnPreviewTouchMove(TouchEventArgs args)

Parameters

args TouchEventArgs

The arguments of the event

OnPreviewTouchUp(TouchEventArgs)

The class handler of the event PreviewTouchUp. This method can be overridden in inherited classes to perform actions common to all instances of a class.

protected virtual void OnPreviewTouchUp(TouchEventArgs args)

Parameters

args TouchEventArgs

The arguments of the event

OnTouchDown(TouchEventArgs)

The class handler of the event TouchDown. This method can be overridden in inherited classes to perform actions common to all instances of a class.

protected virtual void OnTouchDown(TouchEventArgs args)

Parameters

args TouchEventArgs

The arguments of the event

OnTouchEnter(TouchEventArgs)

The class handler of the event TouchEnter. This method can be overridden in inherited classes to perform actions common to all instances of a class.

protected virtual void OnTouchEnter(TouchEventArgs args)

Parameters

args TouchEventArgs

The arguments of the event

OnTouchLeave(TouchEventArgs)

The class handler of the event TouchLeave. This method can be overridden in inherited classes to perform actions common to all instances of a class.

protected virtual void OnTouchLeave(TouchEventArgs args)

Parameters

args TouchEventArgs

The arguments of the event

OnTouchMove(TouchEventArgs)

The class handler of the event TouchMove. This method can be overridden in inherited classes to perform actions common to all instances of a class.

protected virtual void OnTouchMove(TouchEventArgs args)

Parameters

args TouchEventArgs

The arguments of the event

OnTouchUp(TouchEventArgs)

The class handler of the event TouchUp. This method can be overridden in inherited classes to perform actions common to all instances of a class.

protected virtual void OnTouchUp(TouchEventArgs args)

Parameters

args TouchEventArgs

The arguments of the event

PropagateCollapseToChild(UIElement)

Propagate the collapsing to a child element element.

protected void PropagateCollapseToChild(UIElement element)

Parameters

element UIElement

A child element to which propagate the collapse.

Exceptions

InvalidOperationException

element is not a child of this element.

RaiseEvent(RoutedEventArgs)

Raises a specific routed event. The RoutedEvent to be raised is identified within the RoutedEventArgs instance that is provided (as the RoutedEvent property of that event data).

public void RaiseEvent(RoutedEventArgs e)

Parameters

e RoutedEventArgs

A RoutedEventArgs that contains the event data and also identifies the event to raise.

Exceptions

ArgumentNullException

e is null.

InvalidOperationException

The type of the routed event argument e does not match the event handler second argument type.

RemoveHandler<T>(RoutedEvent<T>, EventHandler<T>)

Removes the specified routed event handler from this element.

public void RemoveHandler<T>(RoutedEvent<T> routedEvent, EventHandler<T> handler) where T : RoutedEventArgs

Parameters

routedEvent RoutedEvent<T>

The identifier of the routed event for which the handler is attached.

handler EventHandler<T>

The specific handler implementation to remove from the event handler collection on this element.

Type Parameters

T

Exceptions

ArgumentNullException

Provided handler or routed event is null.

SetParent(UIElement, UIElement)

Set the parent to a child.

protected static void SetParent(UIElement child, UIElement parent)

Parameters

child UIElement

The child to which set the parent.

parent UIElement

The parent of the child.

SetVisualParent(UIElement, UIElement)

Set the visual parent to a child.

protected static void SetVisualParent(UIElement child, UIElement parent)

Parameters

child UIElement

The child to which set the visual parent.

parent UIElement

The parent of the child.

Update(GameTime)

Method called by Update(GameTime). This method can be overridden by inherited classes to perform time-based actions. This method is not in charge to recursively call the update on child elements, this is automatically done.

protected virtual void Update(GameTime time)

Parameters

time GameTime

The current time of the game

UpdateWorldMatrix(ref Matrix, bool)

Method called by UpdateWorldMatrix(ref Matrix, bool). Parents are in charge of recursively calling this function on their children.

protected virtual void UpdateWorldMatrix(ref Matrix parentWorldMatrix, bool parentWorldChanged)

Parameters

parentWorldMatrix Matrix

The world matrix of the parent.

parentWorldChanged bool

Boolean indicating if the world matrix provided by the parent changed

Events

KeyDown

Occurs when the element has the focus and the user maintains a key pressed on the keyboard.

public event EventHandler<KeyEventArgs> KeyDown

Event Type

EventHandler<KeyEventArgs>

Remarks

A key down event is bubbling

KeyPressed

Occurs when the element has the focus and the user press a key on the keyboard.

public event EventHandler<KeyEventArgs> KeyPressed

Event Type

EventHandler<KeyEventArgs>

Remarks

A key pressed event is bubbling

KeyReleased

Occurs when the element has the focus and the user release a key on the keyboard.

public event EventHandler<KeyEventArgs> KeyReleased

Event Type

EventHandler<KeyEventArgs>

Remarks

A key released event is bubbling

MouseOverStateChanged

Occurs when the value of the MouseOverState property changed.

public event PropertyChangedHandler<MouseOverState> MouseOverStateChanged

Event Type

PropertyChangedHandler<MouseOverState>

Remarks

This event is not a routed event

PreviewTouchDown

Occurs when the user starts touching the UIElement. That is when he moves its finger down from the element.

public event EventHandler<TouchEventArgs> PreviewTouchDown

Event Type

EventHandler<TouchEventArgs>

Remarks

A click event is tunneling

PreviewTouchMove

Occurs when the user moves its finger on the UIElement. That is when his finger was already on the element and moved from its previous position.

public event EventHandler<TouchEventArgs> PreviewTouchMove

Event Type

EventHandler<TouchEventArgs>

Remarks

A click event is tunneling

PreviewTouchUp

Occurs when the user stops touching the UIElement. That is when he moves its finger up from the element.

public event EventHandler<TouchEventArgs> PreviewTouchUp

Event Type

EventHandler<TouchEventArgs>

Remarks

A click event is tunneling

TouchDown

Occurs when the user starts touching the UIElement. That is when he moves its finger down from the element.

public event EventHandler<TouchEventArgs> TouchDown

Event Type

EventHandler<TouchEventArgs>

Remarks

A click event is bubbling

TouchEnter

Occurs when the user enters its finger into UIElement. That is when his finger was on the screen outside of the element and moved inside the element.

public event EventHandler<TouchEventArgs> TouchEnter

Event Type

EventHandler<TouchEventArgs>

Remarks

A click event is bubbling

TouchLeave

Occurs when the user leaves its finger from the UIElement. That is when his finger was inside of the element and moved on the screen outside of the element.

public event EventHandler<TouchEventArgs> TouchLeave

Event Type

EventHandler<TouchEventArgs>

Remarks

A click event is bubbling

TouchMove

Occurs when the user move its finger inside the UIElement. That is when his finger was already on the element and moved from its previous position.

public event EventHandler<TouchEventArgs> TouchMove

Event Type

EventHandler<TouchEventArgs>

Remarks

A click event is bubbling

TouchUp

Occurs when the user stops touching the UIElement. That is when he moves its finger up from the element.

public event EventHandler<TouchEventArgs> TouchUp

Event Type

EventHandler<TouchEventArgs>

Remarks

A click event is bubbling

Edit this page