Class UIElement

Represents a base class for all UI elements.

Inheritance

object

UIElement

Inherited Members

DispatcherObject.Dispatcher

DispatcherObject.CheckAccess()

DispatcherObject.VerifyAccess()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: nanoFramework.Presentation

Assembly: nanoFramework.Graphics.dll

Syntax

public abstract class UIElement : DispatcherObject

Constructors

UIElement()

Initializes a new instance of the UIElement class.

Declaration

protected UIElement()

Fields

_horizontalAlignment

Gets or sets the horizontal alignment of the element.

Declaration

protected HorizontalAlignment _horizontalAlignment

Field Value

Type	Description
HorizontalAlignment

_verticalAlignment

Gets or sets the vertical alignment of the element.

Declaration

protected VerticalAlignment _verticalAlignment

Field Value

Type	Description
VerticalAlignment

Properties

ActualHeight

Gets the actual height of the UIElement.

Declaration

public int ActualHeight { get; }

Property Value

Type	Description
int

ActualWidth

Gets the actual width of the UIElement.

Declaration

public int ActualWidth { get; }

Property Value

Type	Description
int

Height

Gets or sets the height of the UIElement.

Declaration

public int Height { get; set; }

Property Value

Type	Description
int

HorizontalAlignment

Gets or sets the horizontal alignment of the element.

Declaration

public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

Type	Description
HorizontalAlignment

InstanceEventHandlersStore

Ensure the store has been created.

Declaration

protected Hashtable InstanceEventHandlersStore { get; }

Property Value

Type	Description
Hashtable

IsArrangeValid

Determines if the RenderSize and position of child elements is valid.

Declaration

public bool IsArrangeValid { get; }

Property Value

Type	Description
bool

Remarks

A developer can force arrangement to be invalidated by calling InvalidateArrange. IsArrangeValid and IsMeasureValid are related, in that arrangement cannot be valid without measurement first being valid.

IsEnabled

Gets or sets a value indicating whether the element is enabled.

Declaration

public bool IsEnabled { get; set; }

Property Value

Type	Description
bool

IsFocused

A property indicating if the button is focused on this element or not.

Declaration

public bool IsFocused { get; }

Property Value

Type	Description
bool

IsMeasureValid

Determines if the DesiredSize is valid.

Declaration

public bool IsMeasureValid { get; }

Property Value

Type	Description
bool

Remarks

A developer can force arrangement to be invalidated by calling InvalidateMeasure. IsArrangeValid and IsMeasureValid are related, in that arrangement cannot be valid without measurement first being valid.

IsVisible

Gets a value indicating whether the element is currently visible.

Declaration

public bool IsVisible { get; }

Property Value

Type	Description
bool

LogicalChildren

Gets the collection of child elements of the UIElement.

Declaration

protected UIElementCollection LogicalChildren { get; }

Property Value

Type	Description
UIElementCollection

Parent

Gets the parent UIElement of this UIElement.

Declaration

public UIElement Parent { get; }

Property Value

Type	Description
UIElement

RootUIElement

Gets the root UIElement of this UIElement.

Declaration

public UIElement RootUIElement { get; }

Property Value

Type	Description
UIElement

VerticalAlignment

Gets or sets the vertical alignment of the element.

Declaration

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

Type	Description
VerticalAlignment

Visibility

Gets or sets the visibility of the element.

Declaration

public Visibility Visibility { get; set; }

Property Value

Type	Description
Visibility

Width

Gets or sets the width of the UIElement.

Declaration

public int Width { get; set; }

Property Value

Type	Description
int

Methods

AddHandler(RoutedEvent, RoutedEventHandler, bool)

Adds a routed event handler for the particular RoutedEvent

Declaration

public void AddHandler(RoutedEvent routedEvent, RoutedEventHandler handler, bool handledEventsToo)

Parameters

Type	Name	Description
RoutedEvent	routedEvent	RoutedEvent for which the handler is attached
RoutedEventHandler	handler	The handler that will be invoked on this object when the RoutedEvent is raised
bool	handledEventsToo	Flag indicating whether or not the listener wants to hear about events that have already been handled

Remarks

The handler added thus is also known as an instance handler

NOTE: It is not an error to add a handler twice (handler will simply be called twice)

Input parameters RoutedEvent and handler cannot be null

handledEventsToo input parameter when false means that listener does not care about already handled events. Hence the handler will not be invoked on the target if the RoutedEvent has already been Handled

handledEventsToo input parameter when true means that the listener wants to hear about all events even if they have already been handled. Hence the handler will be invoked irrespective of the event being Handled

AddToEventRoute(EventRoute, RoutedEventArgs)

Add the event handlers for this element to the route.

Declaration

public void AddToEventRoute(EventRoute route, RoutedEventArgs args)

Parameters

Type	Name	Description
EventRoute	route	The route event.
RoutedEventArgs	args	The route event arguments.

Arrange(int, int, int, int)

Parents or system call this method to arrange the internals of children on a second pass of layout update.

Declaration

public void Arrange(int finalRectX, int finalRectY, int finalRectWidth, int finalRectHeight)

Parameters

Type	Name	Description
int	finalRectX	This is the final X location that parent or system wants this UIElement to assume.
int	finalRectY	This is the final Y location that parent or system wants this UIElement to assume.
int	finalRectWidth	This is the Width that parent or system wants this UIElement to assume.
int	finalRectHeight	This is the height that parent or system wants this UIElement to assume.

Remarks

This method internally calls ArrangeOverride override, giving the derived class opportunity to arrange its children and/or content using final computed size. In their ArrangeOverride overrides, derived class is supposed to create its visual structure and prepare itself for rendering. Arrange is called by parents from their implementation of ArrangeOverride or by system when needed. This method sets Bounds=finalSize before calling ArrangeOverride.

ArrangeOverride(int, int)

ArrangeOverride allows for the customization of the final sizing and positioning of children.

Declaration

protected virtual void ArrangeOverride(int arrangeWidth, int arrangeHeight)

Parameters

Type	Name	Description
int	arrangeWidth	Final width
int	arrangeHeight	Final height

Remarks

UIElement authors should override this method, call Arrange on each visible child UIElement, to size and position each child UIElement by passing a rectangle reserved for the child within parent space. Note: It is required that a parent UIElement calls Arrange on each child or they won't be rendered. Typical override follows a pattern roughly like this (pseudo-code):

protected override void ArrangeOverride(int arrangeWidth, int arrangeHeight)
{

    foreach (UIElement child in VisualChildren)
    {
        child.Arrange(new Rect(childX, childY, childWidth, childHeight);
    }
}</code></pre>

ChildElementFromPoint(int, int)

Given x, y co-ordinates of the parent UIElement, find the child control that is directly underneath that point. If there are multiple such controls, the one that was created/inserted into the list last wins. This is because we don't have explicit z-ordering right now.

Declaration

public UIElement ChildElementFromPoint(int x, int y)

Parameters

Type	Name	Description
int	x
int	y

Returns

Type	Description
UIElement

ContainsPoint(int, int)

Determines whether the point (x, y) is contained within the UIElement.

Declaration

public bool ContainsPoint(int x, int y)

Parameters

Type	Name	Description
int	x	The x-coordinate of the point.
int	y	The y-coordinate of the point.

Returns

Type	Description
bool	True if the point is contained within the UIElement; otherwise, false.

GetDesiredSize(out int, out int)

Gets the desired size of this element.

Declaration

public void GetDesiredSize(out int width, out int height)

Parameters

Type	Name	Description
int	width	When this method returns, contains the desired width of this element.
int	height	When this method returns, contains the desired height of this element.

GetLayoutOffset(out int, out int)

Gets the X and Y offset of the UIElement's layout.

Declaration

public void GetLayoutOffset(out int x, out int y)

Parameters

Type	Name	Description
int	x	The X offset of the UIElement's layout.
int	y	The Y offset of the UIElement's layout.

GetMargin(out int, out int, out int, out int)

Gets the margin thickness of this element.

Declaration

public void GetMargin(out int left, out int top, out int right, out int bottom)

Parameters

Type	Name	Description
int	left	When this method returns, contains the left margin thickness of this element.
int	top	When this method returns, contains the top margin thickness of this element.
int	right	When this method returns, contains the right margin thickness of this element.
int	bottom	When this method returns, contains the bottom margin thickness of this element.

GetPointerTarget(int, int)

Retrieves the UIElement that is the target of a pointer event at the given point (x, y).

Declaration

public UIElement GetPointerTarget(int x, int y)

Parameters

Type	Name	Description
int	x	The x-coordinate of the pointer event.
int	y	The y-coordinate of the pointer event.

Returns

Type	Description
UIElement	The UIElement that is the target of the pointer event; otherwise, null.

GetRenderSize(out int, out int)

Gets the width and height of the UIElement's rendered content.

Declaration

public void GetRenderSize(out int width, out int height)

Parameters

Type	Name	Description
int	width	The width of the UIElement's rendered content.
int	height	The height of the UIElement's rendered content.

GetUnclippedSize(out int, out int)

Retrieves the unclipped size of the UIElement.

Declaration

public void GetUnclippedSize(out int width, out int height)

Parameters

Type	Name	Description
int	width	Output parameter for the unclipped width.
int	height	Output parameter for the unclipped height.

Invalidate()

Invalidates the entire layout of the UIElement.

Declaration

public void Invalidate()

InvalidateArrange()

Invalidates the arrange state for the UIElement. The UIElement will be queued for an update layout that will occur asynchronously. MeasureOverride will not be called unless InvalidateMeasure is also called - or that something else caused the measure state to be invalidated.

Declaration

public void InvalidateArrange()

InvalidateMeasure()

Invalidates the measurement state for the UIElement. This has the effect of also invalidating the arrange state for the UIElement. The UIElement will be queued for an update layout that will occur asynchronously.

Declaration

public void InvalidateMeasure()

InvalidateRect(int, int, int, int)

Marks a region of the UIElement as dirty and invalidates the layout.

Declaration

public void InvalidateRect(int x, int y, int w, int h)

Parameters

Type	Name	Description
int	x	The x-coordinate of the upper-left corner of the region.
int	y	The y-coordinate of the upper-left corner of the region.
int	w	The width of the region.
int	h	The height of the region.

Measure(int, int)

Updates DesiredSize of the UIElement. Must be called by parents from their MeasureOverride, to form recursive update. This is first pass of layout update.

Declaration

public void Measure(int availableWidth, int availableHeight)

Parameters

Type	Name	Description
int	availableWidth	Available width that parent can give to the child. May be MaxValue (when parent wants to measure to content). This is soft constraint. Child can return bigger size to indicate that it wants bigger space and hope that parent can throw in scrolling...
int	availableHeight	Available height that parent can give to the child. May be MaxValue (when parent wants to measure to content). This is soft constraint. Child can return bigger size to indicate that it wants bigger space and hope that parent can throw in scrolling...

Remarks

Measure is called by parents on their children. Internally, Measure calls MeasureOverride override on the same object, giving it opportunity to compute its DesiredSize.

This method will return immediately if child is not Dirty, previously measured and availableSize is the same as cached.

This method also resets the IsMeasureinvalid bit on the child.

In case when "unbounded measure to content" is needed, parent can use availableSize as double.PositiveInfinity. Any returned size is OK in this case.

MeasureOverride(int, int, out int, out int)

Measurement override. Implement your size-to-content logic here.

Declaration

protected virtual void MeasureOverride(int availableWidth, int availableHeight, out int desiredWidth, out int desiredHeight)

Parameters

Type	Name	Description
int	availableWidth	Available size that parent can give to the child. May be MaxValue(when parent wants to measure to content). This is soft constraint. Child can return bigger size to indicate that it wants bigger space and hope that parent can throw in scrolling...
int	availableHeight
int	desiredWidth
int	desiredHeight

Remarks

MeasureOverride is designed to be the main customizability point for size control of layout. UIElement authors should override this method, call Measure on each child UIElement, and compute their desired size based upon the measurement of the children. The return value should be the desired size.

Note: It is required that a parent UIElement calls Measure on each child or they won't be sized/arranged. Typical override follows a pattern roughly like this (pseudo-code):

protected override void MeasureOverride(int avialableWidth, int availableHeight, out int desiredWidth, out int desiredHeight)
{
foreach (UIElement child in VisualChildren)
{
child.Measure(availableSize);
availableSize.Deflate(child.DesiredSize);
_cache.StoreInfoAboutChild(child);
}
    Size desired = CalculateBasedOnCache(_cache);
    return desired;
}</code></pre>

The key aspects of this snippet are:

You must call Measure on each child UIElement
It is common to cache measurement information between the MeasureOverride and ArrangeOverride method calls
Calling base.MeasureOverride is not required.
Calls to Measure on children are passing either the same availableSize as the parent, or a subset of the area depending on the type of layout the parent will perform (for example, it would be valid to remove the area for some border or padding).

OnButtonDown(ButtonEventArgs)

Occurs when a button is pressed on the control.

Declaration

protected virtual void OnButtonDown(ButtonEventArgs e)

Parameters

Type	Name	Description
ButtonEventArgs	e	The ButtonEventArgs instance containing the event data.

OnButtonUp(ButtonEventArgs)

Occurs when a button is released on the control.

Declaration

protected virtual void OnButtonUp(ButtonEventArgs e)

Parameters

Type	Name	Description
ButtonEventArgs	e	The ButtonEventArgs instance containing the event data.

OnChildDesiredSizeChanged(UIElement)

Notification that is called by Measure of a child when it ends up with different desired size for the child.

Declaration

protected virtual void OnChildDesiredSizeChanged(UIElement child)

Parameters

Type	Name	Description
UIElement	child

Remarks

Default implementation simply calls invalidateMeasure(), assuming that layout of a parent should be updated after child changed its size.

Finer point: this method can only be called in the scenario when the system calls Measure on a child, not when parent calls it since if parent calls it, it means parent has dirty layout and is recalculating already.

OnChildrenChanged(UIElement, UIElement, int)

Called when the UIElementCollection of the UIElement is edited.

Declaration

protected virtual void OnChildrenChanged(UIElement added, UIElement removed, int indexAffected)

Parameters

Type	Name	Description
UIElement	added	The UIElement that was added to the collection.
UIElement	removed	The UIElement that was removed from the collection.
int	indexAffected	The index at which the collection was edited.

OnGenericEvent(GenericEventArgs)

Raises the GenericEvent event.

Declaration

protected virtual void OnGenericEvent(GenericEventArgs e)

Parameters

Type	Name	Description
GenericEventArgs	e	Provides data for the GenericEvent event.

OnGotFocus(FocusChangedEventArgs)

Occurs when the control receives focus.

Declaration

protected virtual void OnGotFocus(FocusChangedEventArgs e)

Parameters

Type	Name	Description
FocusChangedEventArgs	e	The FocusChangedEventArgs instance containing the event data.

OnLostFocus(FocusChangedEventArgs)

Occurs when the control loses focus.

Declaration

protected virtual void OnLostFocus(FocusChangedEventArgs e)

Parameters

Type	Name	Description
FocusChangedEventArgs	e	The FocusChangedEventArgs instance containing the event data.

OnPreviewButtonDown(ButtonEventArgs)

Occurs when a button press is previewed on the control.

Declaration

protected virtual void OnPreviewButtonDown(ButtonEventArgs e)

Parameters

Type	Name	Description
ButtonEventArgs	e	The ButtonEventArgs instance containing the event data.

OnPreviewButtonUp(ButtonEventArgs)

Occurs when a button press is previewed on the control.

Declaration

protected virtual void OnPreviewButtonUp(ButtonEventArgs e)

Parameters

Type	Name	Description
ButtonEventArgs	e	The ButtonEventArgs instance containing the event data.

OnRender(DrawingContext)

Renders the element using the specified DrawingContext.

Declaration

public virtual void OnRender(DrawingContext dc)

Parameters

Type	Name	Description
DrawingContext	dc	The drawing context.

OnTouchDown(TouchEventArgs)

Occurs when a touch event is detected on the control.

Declaration

protected virtual void OnTouchDown(TouchEventArgs e)

Parameters

Type	Name	Description
TouchEventArgs	e	The TouchEventArgs instance containing the event data.

OnTouchGestureChanged(TouchGestureEventArgs)

Occurs when a touch gesture is started on the control.

Declaration

protected virtual void OnTouchGestureChanged(TouchGestureEventArgs e)

Parameters

Type	Name	Description
TouchGestureEventArgs	e	The TouchGestureEventArgs instance containing the event data.

OnTouchGestureEnded(TouchGestureEventArgs)

Occurs when a touch gesture on the control is completed.

Declaration

protected virtual void OnTouchGestureEnded(TouchGestureEventArgs e)

Parameters

Type	Name	Description
TouchGestureEventArgs	e	The TouchGestureEventArgs instance containing the event data.

OnTouchGestureStarted(TouchGestureEventArgs)

Occurs when a touch gesture is started on the control.

Declaration

protected virtual void OnTouchGestureStarted(TouchGestureEventArgs e)

Parameters

Type	Name	Description
TouchGestureEventArgs	e	The TouchGestureEventArgs instance containing the event data.

OnTouchMove(TouchEventArgs)

Occurs when the position of a touch event changes on the control.

Declaration

protected virtual void OnTouchMove(TouchEventArgs e)

Parameters

Type	Name	Description
TouchEventArgs	e	The TouchEventArgs instance containing the event data.

OnTouchUp(TouchEventArgs)

Occurs when a touch event is completed on the control.

Declaration

protected virtual void OnTouchUp(TouchEventArgs e)

Parameters

Type	Name	Description
TouchEventArgs	e	The TouchEventArgs instance containing the event data.

PointToClient(ref int, ref int)

Translates a point from client coordinates to screen coordinates.

Declaration

public void PointToClient(ref int x, ref int y)

Parameters

Type	Name	Description
int	x	The x-coordinate of the point to be translated.
int	y	The y-coordinate of the point to be translated.

PointToScreen(ref int, ref int)

We are deviating little from their desktop counter parts, mostly for simplicity and perf.

Declaration

public void PointToScreen(ref int x, ref int y)

Parameters

Type	Name	Description
int	x
int	y

RaiseEvent(RoutedEventArgs)

Raise the events specified by RoutedEvent

Declaration

public void RaiseEvent(RoutedEventArgs args)

Parameters

Type	Name	Description
RoutedEventArgs	args	RoutedEventArgs for the event to be raised

Remarks

This method is a shorthand for This method walks up the visual tree, calling cref="UIElement.BuildRouteCore" on every cref="UIElement"

NOTE: The RoutedEvent in RoutedEventArgs and EventRoute must be matched

Once the route is built, it calls InvokeHandlers()

RenderRecursive(DrawingContext)

Renders the element and its child elements recursively using the specified DrawingContext.

Declaration

protected virtual void RenderRecursive(DrawingContext dc)

Parameters

Type	Name	Description
DrawingContext	dc	The DrawingContext to use for rendering.

SetMargin(int)

Sets the margin thickness for all four sides of this element.

Declaration

public void SetMargin(int length)

Parameters

Type	Name	Description
int	length	The thickness to set for all four sides of this element.

SetMargin(int, int, int, int)

Sets the margin thickness for each side of this element.

Declaration

public void SetMargin(int left, int top, int right, int bottom)

Parameters

Type	Name	Description
int	left	The thickness to set for the left side of this element.
int	top	The thickness to set for the top side of this element.
int	right	The thickness to set for the right side of this element.
int	bottom	The thickness to set for the bottom side of this element.

UpdateLayout()

Call this method to ensure that the whoel subtree of elements that includes this UIElement is properly updated.

Declaration

public void UpdateLayout()

Remarks

This ensures that UIElements with IsMeasureInvalid or IsArrangeInvalid will get call to their MeasureOverride and ArrangeOverride, and all computed sizes will be validated. This method does nothing if layout is clean but it does work if layout is not clean so avoid calling it after each change in the UIElement tree. It makes sense to either never call it (system will do this in a deferred manner) or only call it if you absolutely need updated sizes and positions after you do all changes.

Events

IsEnabledChanged

Event raised when the value of the IsEnabled property changes.

Declaration

public event PropertyChangedEventHandler IsEnabledChanged

Event Type

Type	Description
PropertyChangedEventHandler

IsVisibleChanged

Occurs when the value of the IsVisible property changes.

Declaration

public event PropertyChangedEventHandler IsVisibleChanged

Event Type

Type	Description
PropertyChangedEventHandler

TouchDown

Occurs when a touch-down event occurs on this element.

Declaration

public event TouchEventHandler TouchDown

Event Type

Type	Description
TouchEventHandler

TouchGestureChanged

Occurs when a touch gesture-changed event occurs on this element.

Declaration

public event TouchGestureEventHandler TouchGestureChanged

Event Type

Type	Description
TouchGestureEventHandler

TouchGestureEnd

Occurs when a touch gesture-end event occurs on this element.

Declaration

public event TouchGestureEventHandler TouchGestureEnd

Event Type

Type	Description
TouchGestureEventHandler

TouchGestureStart

Occurs when a touch gesture-start event occurs on this element.

Declaration

public event TouchGestureEventHandler TouchGestureStart

Event Type

Type	Description
TouchGestureEventHandler

TouchMove

Occurs when a touch-move event occurs on this element.

Declaration

public event TouchEventHandler TouchMove

Event Type

Type	Description
TouchEventHandler

TouchUp

Occurs when a touch-up event occurs on this element.

Declaration

public event TouchEventHandler TouchUp

Event Type

Type	Description
TouchEventHandler

Extension Methods

LogDispatcher.GetCurrentClassLogger(object)