Class UIElement
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
ArrangeChanged
protected bool ArrangeChanged
Field Value
BehaviorCategory
protected const string BehaviorCategory = "Behavior"
Field Value
InputCategory
protected const string InputCategory = "Input"
Field Value
LayoutCategory
protected const string LayoutCategory = "Layout"
Field Value
LocalMatrixChanged
protected bool LocalMatrixChanged
Field Value
MarginInternal
protected Thickness MarginInternal
Field Value
MiscCategory
protected const string MiscCategory = "Misc"
Field Value
PanelCategory
protected const string PanelCategory = "Panel"
Field Value
Properties
ActualDepth
Gets the rendered depth of this element.
public float ActualDepth { get; }
Property Value
ActualHeight
Gets the rendered height of this element.
public float ActualHeight { get; }
Property Value
ActualWidth
Gets the rendered width of this element.
public float ActualWidth { get; }
Property Value
BackgroundColor
The background color of the element.
[DataMember]
[Display(null, "Appearance")]
public Color BackgroundColor { get; set; }
Property Value
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
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
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
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
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
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
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
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
DepthBias
The final depth bias value of the element resulting from the parent/children z order update.
public int DepthBias { get; }
Property Value
DesiredSize
Gets the size that this element computed during the measure pass of the layout process.
public Vector3 DesiredSize { get; }
Property Value
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
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
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
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
HorizontalAlignment
Gets or sets the horizontal alignment of this element.
[DataMember]
[Display(null, "Layout")]
public HorizontalAlignment HorizontalAlignment { get; set; }
Property Value
Id
A unique ID defining the UI element.
[DataMember]
[Display(null, null, Browsable = false)]
public Guid Id { get; set; }
Property Value
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
IsCollapsed
Gets a value indicating whether this element takes some place in the user interface.
public bool IsCollapsed { get; }
Property Value
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
IsHierarchyEnabled
Gets the value indicating whether this element and all its upper hierarchy are enabled or not.
public bool IsHierarchyEnabled { get; }
Property Value
IsMeasureValid
Gets a value indicating whether the current size returned by layout measure is valid.
public bool IsMeasureValid { get; }
Property Value
IsTouched
Gets a value indicating whether the UIElement is currently touched by the user.
public bool IsTouched { get; }
Property Value
IsVisible
Gets a value indicating whether this element is visible in the user interface (UI).
public bool IsVisible { get; }
Property Value
LayoutingContext
The ratio between the element real size on the screen and the element virtual size.
protected LayoutingContext LayoutingContext { get; set; }
Property Value
LocalMatrix
Gets or sets the LocalMatrix of this element.
public Matrix LocalMatrix { get; set; }
Property Value
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
MaximumDepth
Gets or sets the maximum height of this element.
[DataMember]
[DataMemberRange(0, 3)]
[Display(null, "Layout")]
public float MaximumDepth { get; set; }
Property Value
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
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
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
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
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
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
Remarks
Only elements that can be clicked by user can have the
Name
Gets or sets the name of this element.
[DataMember]
[Display(null, "Misc")]
public string Name { get; set; }
Property Value
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
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
RenderOffsets
The rendering offsets caused by the UIElement margins and alignments.
public Vector3 RenderOffsets { get; }
Property Value
RenderOpacity
The opacity used to render element.
public float RenderOpacity { get; }
Property Value
RenderSize
Gets (or sets, but see Remarks) the final render size of this element.
public Vector3 RenderSize { get; }
Property Value
RequiresMouseOverUpdate
Gets or sets whether this element requires a mouse over check.
public bool RequiresMouseOverUpdate { get; set; }
Property Value
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
public Vector3 Size { get; set; }
Property Value
VerticalAlignment
Gets or sets the vertical alignment of this element.
[DataMember]
[Display(null, "Layout")]
public VerticalAlignment VerticalAlignment { get; set; }
Property Value
Visibility
Gets or sets the user interface (UI) visibility of this element.
[DataMember]
[Display(null, "Appearance")]
public Visibility Visibility { get; set; }
Property Value
VisualChildren
Get a enumerable to the visual children of the UIElement.
public IReadOnlyList<UIElement> VisualChildren { get; }
Property Value
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
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
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
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
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
booltrue 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
Vector3The final size that the parent computes for the child element with the margins.
isParentCollapsed
boolBoolean 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
Vector3The 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
ThicknessThe thickness around the element to position.
providedSpace
Vector3The total space given to the child element by the parent
usedSpaceWithoutThickness
Vector3The 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
Vector3The size without the thickness included
thickness
ThicknessThe 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
Vector3The size with the thickness included
thickness
ThicknessThe 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
stringThe 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
RayThe ray in world space coordinate
intersectionPoint
Vector3The 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
Vector3The 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
Vector3The 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
TouchEventArgsThe 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
TouchEventArgsThe 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
TouchEventArgsThe 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
TouchEventArgsThe 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
TouchEventArgsThe 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
TouchEventArgsThe 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
TouchEventArgsThe 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
TouchEventArgsThe arguments of the event
PropagateCollapseToChild(UIElement)
Propagate the collapsing to a child element element
.
protected void PropagateCollapseToChild(UIElement element)
Parameters
element
UIElementA 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
RoutedEventArgsA 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
SetVisualParent(UIElement, UIElement)
Set the visual parent to a child.
protected static void SetVisualParent(UIElement child, UIElement parent)
Parameters
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
GameTimeThe 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
MatrixThe world matrix of the parent.
parentWorldChanged
boolBoolean indicating if the world matrix provided by the parent changed
Events
MouseOverStateChanged
Occurs when the value of the MouseOverState property changed.
public event PropertyChangedHandler<MouseOverState> MouseOverStateChanged
Event Type
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
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
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
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
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
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
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
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
Remarks
A click event is bubbling