Search Results for

    Show / Hide Table of Contents

    Class UIElement

    Represents a base class for all UI elements.

    Inheritance
    object
    DispatcherObject
    UIElement
    Control
    Image
    InkCanvas
    Panel
    Text
    TextFlow
    Shape
    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)
    LogDispatcher.GetCurrentClassLogger(object)
    LogDispatcher.GetCurrentClassLogger(object)
    LogDispatcher.GetCurrentClassLogger(object)
    LogDispatcher.GetCurrentClassLogger(object)
    LogDispatcher.GetCurrentClassLogger(object)
    LogDispatcher.GetCurrentClassLogger(object)
    LogDispatcher.GetCurrentClassLogger(object)
    LogDispatcher.GetCurrentClassLogger(object)
    LogDispatcher.GetCurrentClassLogger(object)
    In This Article
    Back to top Copyright © 2023 nanoFramework Contributors
    Generated by DocFX