Table of Contents

Class UIElement

Namespace
nanoFramework.Presentation
Assembly
nanoFramework.Graphics.dll

Represents a base class for all UI elements.

public abstract class UIElement : DispatcherObject
Inheritance
UIElement
Derived
Inherited Members
Extension Methods

Constructors

UIElement()

Initializes a new instance of the UIElement class.

protected UIElement()

Fields

_horizontalAlignment

Gets or sets the horizontal alignment of the element.

protected HorizontalAlignment _horizontalAlignment

Field Value

HorizontalAlignment

_verticalAlignment

Gets or sets the vertical alignment of the element.

protected VerticalAlignment _verticalAlignment

Field Value

VerticalAlignment

Properties

ActualHeight

Gets the actual height of the UIElement.

public int ActualHeight { get; }

Property Value

int

ActualWidth

Gets the actual width of the UIElement.

public int ActualWidth { get; }

Property Value

int

Height

Gets or sets the height of the UIElement.

public int Height { get; set; }

Property Value

int

HorizontalAlignment

Gets or sets the horizontal alignment of the element.

public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

InstanceEventHandlersStore

Ensure the store has been created.

protected Hashtable InstanceEventHandlersStore { get; }

Property Value

Hashtable

IsArrangeValid

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

public bool IsArrangeValid { get; }

Property Value

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.

public bool IsEnabled { get; set; }

Property Value

bool

IsFocused

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

public bool IsFocused { get; }

Property Value

bool

IsMeasureValid

Determines if the DesiredSize is valid.

public bool IsMeasureValid { get; }

Property Value

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.

public bool IsVisible { get; }

Property Value

bool

LogicalChildren

Gets the collection of child elements of the UIElement.

protected UIElementCollection LogicalChildren { get; }

Property Value

UIElementCollection

Parent

Gets the parent UIElement of this UIElement.

public UIElement Parent { get; }

Property Value

UIElement

RootUIElement

Gets the root UIElement of this UIElement.

public UIElement RootUIElement { get; }

Property Value

UIElement

VerticalAlignment

Gets or sets the vertical alignment of the element.

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

Visibility

Gets or sets the visibility of the element.

public Visibility Visibility { get; set; }

Property Value

Visibility

Width

Gets or sets the width of the UIElement.

public int Width { get; set; }

Property Value

int

Methods

AddHandler(RoutedEvent, RoutedEventHandler, bool)

Adds a routed event handler for the particular RoutedEvent

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

Parameters

routedEvent RoutedEvent

RoutedEvent for which the handler is attached

handler RoutedEventHandler

The handler that will be invoked on this object when the RoutedEvent is raised

handledEventsToo bool

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.

public void AddToEventRoute(EventRoute route, RoutedEventArgs args)

Parameters

route EventRoute

The route event.

args RoutedEventArgs

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.

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

Parameters

finalRectX int

This is the final X location that parent or system wants this UIElement to assume.

finalRectY int

This is the final Y location that parent or system wants this UIElement to assume.

finalRectWidth int

This is the Width that parent or system wants this UIElement to assume.

finalRectHeight int

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.

protected virtual void ArrangeOverride(int arrangeWidth, int arrangeHeight)

Parameters

arrangeWidth int

Final width

arrangeHeight int

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></example>

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.

public UIElement ChildElementFromPoint(int x, int y)

Parameters

x int
y int

Returns

UIElement

ContainsPoint(int, int)

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

public bool ContainsPoint(int x, int y)

Parameters

x int

The x-coordinate of the point.

y int

The y-coordinate of the point.

Returns

bool

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

GetDesiredSize(out int, out int)

Gets the desired size of this element.

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

Parameters

width int

When this method returns, contains the desired width of this element.

height int

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.

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

Parameters

x int

The X offset of the UIElement's layout.

y int

The Y offset of the UIElement's layout.

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

Gets the margin thickness of this element.

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

Parameters

left int

When this method returns, contains the left margin thickness of this element.

top int

When this method returns, contains the top margin thickness of this element.

right int

When this method returns, contains the right margin thickness of this element.

bottom int

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).

public UIElement GetPointerTarget(int x, int y)

Parameters

x int

The x-coordinate of the pointer event.

y int

The y-coordinate of the pointer event.

Returns

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.

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

Parameters

width int

The width of the UIElement's rendered content.

height int

The height of the UIElement's rendered content.

GetUnclippedSize(out int, out int)

Retrieves the unclipped size of the UIElement.

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

Parameters

width int

Output parameter for the unclipped width.

height int

Output parameter for the unclipped height.

Invalidate()

Invalidates the entire layout of the UIElement.

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.

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.

public void InvalidateMeasure()

InvalidateRect(int, int, int, int)

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

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

Parameters

x int

The x-coordinate of the upper-left corner of the region.

y int

The y-coordinate of the upper-left corner of the region.

w int

The width of the region.

h int

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.

public void Measure(int availableWidth, int availableHeight)

Parameters

availableWidth int

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...

availableHeight int

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.

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

Parameters

availableWidth int

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...

availableHeight int
desiredWidth int
desiredHeight int

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></example>



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.

protected virtual void OnButtonDown(ButtonEventArgs e)

Parameters

e ButtonEventArgs

The ButtonEventArgs instance containing the event data.

OnButtonUp(ButtonEventArgs)

Occurs when a button is released on the control.

protected virtual void OnButtonUp(ButtonEventArgs e)

Parameters

e ButtonEventArgs

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.

protected virtual void OnChildDesiredSizeChanged(UIElement child)

Parameters

child UIElement

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.

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

Parameters

added UIElement

The UIElement that was added to the collection.

removed UIElement

The UIElement that was removed from the collection.

indexAffected int

The index at which the collection was edited.

OnGenericEvent(GenericEventArgs)

Raises the GenericEvent event.

protected virtual void OnGenericEvent(GenericEventArgs e)

Parameters

e GenericEventArgs

Provides data for the GenericEvent event.

OnGotFocus(FocusChangedEventArgs)

Occurs when the control receives focus.

protected virtual void OnGotFocus(FocusChangedEventArgs e)

Parameters

e FocusChangedEventArgs

The FocusChangedEventArgs instance containing the event data.

OnLostFocus(FocusChangedEventArgs)

Occurs when the control loses focus.

protected virtual void OnLostFocus(FocusChangedEventArgs e)

Parameters

e FocusChangedEventArgs

The FocusChangedEventArgs instance containing the event data.

OnPreviewButtonDown(ButtonEventArgs)

Occurs when a button press is previewed on the control.

protected virtual void OnPreviewButtonDown(ButtonEventArgs e)

Parameters

e ButtonEventArgs

The ButtonEventArgs instance containing the event data.

OnPreviewButtonUp(ButtonEventArgs)

Occurs when a button press is previewed on the control.

protected virtual void OnPreviewButtonUp(ButtonEventArgs e)

Parameters

e ButtonEventArgs

The ButtonEventArgs instance containing the event data.

OnRender(DrawingContext)

Renders the element using the specified DrawingContext.

public virtual void OnRender(DrawingContext dc)

Parameters

dc DrawingContext

The drawing context.

OnTouchDown(TouchEventArgs)

Occurs when a touch event is detected on the control.

protected virtual void OnTouchDown(TouchEventArgs e)

Parameters

e TouchEventArgs

The TouchEventArgs instance containing the event data.

OnTouchGestureChanged(TouchGestureEventArgs)

Occurs when a touch gesture is started on the control.

protected virtual void OnTouchGestureChanged(TouchGestureEventArgs e)

Parameters

e TouchGestureEventArgs

The TouchGestureEventArgs instance containing the event data.

OnTouchGestureEnded(TouchGestureEventArgs)

Occurs when a touch gesture on the control is completed.

protected virtual void OnTouchGestureEnded(TouchGestureEventArgs e)

Parameters

e TouchGestureEventArgs

The TouchGestureEventArgs instance containing the event data.

OnTouchGestureStarted(TouchGestureEventArgs)

Occurs when a touch gesture is started on the control.

protected virtual void OnTouchGestureStarted(TouchGestureEventArgs e)

Parameters

e TouchGestureEventArgs

The TouchGestureEventArgs instance containing the event data.

OnTouchMove(TouchEventArgs)

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

protected virtual void OnTouchMove(TouchEventArgs e)

Parameters

e TouchEventArgs

The TouchEventArgs instance containing the event data.

OnTouchUp(TouchEventArgs)

Occurs when a touch event is completed on the control.

protected virtual void OnTouchUp(TouchEventArgs e)

Parameters

e TouchEventArgs

The TouchEventArgs instance containing the event data.

PointToClient(ref int, ref int)

Translates a point from client coordinates to screen coordinates.

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

Parameters

x int

The x-coordinate of the point to be translated.

y int

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.

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

Parameters

x int
y int

RaiseEvent(RoutedEventArgs)

Raise the events specified by RoutedEvent

public void RaiseEvent(RoutedEventArgs args)

Parameters

args RoutedEventArgs

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.

protected virtual void RenderRecursive(DrawingContext dc)

Parameters

dc DrawingContext

The DrawingContext to use for rendering.

SetMargin(int)

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

public void SetMargin(int length)

Parameters

length int

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.

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

Parameters

left int

The thickness to set for the left side of this element.

top int

The thickness to set for the top side of this element.

right int

The thickness to set for the right side of this element.

bottom int

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.

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.

public event PropertyChangedEventHandler IsEnabledChanged

Event Type

PropertyChangedEventHandler

IsVisibleChanged

Occurs when the value of the IsVisible property changes.

public event PropertyChangedEventHandler IsVisibleChanged

Event Type

PropertyChangedEventHandler

TouchDown

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

public event TouchEventHandler TouchDown

Event Type

TouchEventHandler

TouchGestureChanged

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

public event TouchGestureEventHandler TouchGestureChanged

Event Type

TouchGestureEventHandler

TouchGestureEnd

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

public event TouchGestureEventHandler TouchGestureEnd

Event Type

TouchGestureEventHandler

TouchGestureStart

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

public event TouchGestureEventHandler TouchGestureStart

Event Type

TouchGestureEventHandler

TouchMove

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

public event TouchEventHandler TouchMove

Event Type

TouchEventHandler

TouchUp

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

public event TouchEventHandler TouchUp

Event Type

TouchEventHandler