Table of Contents

Class UIElement

Namespace
GHIElectronics.Endpoint.UI
Assembly
GHIElectronics.Endpoint.UI.dll
public abstract class UIElement : DispatcherObject
Inheritance
UIElement
Derived
Inherited Members

Constructors

UIElement() 

protected UIElement()

Fields

_horizontalAlignment 

protected HorizontalAlignment _horizontalAlignment

Field Value

HorizontalAlignment

_verticalAlignment 

protected VerticalAlignment _verticalAlignment

Field Value

VerticalAlignment

Properties

ActualHeight 

public int ActualHeight { get; }

Property Value

int

ActualWidth 

public int ActualWidth { get; }

Property Value

int

Height 

public int Height { get; set; }

Property Value

int

HorizontalAlignment 

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

Fetches the value of the IsEnabled property

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

A property indicating if this element is Visible or not.

public bool IsVisible { get; }

Property Value

bool

LogicalChildren 

protected UIElementCollection LogicalChildren { get; }

Property Value

UIElementCollection

Parent 

public UIElement Parent { get; }

Property Value

UIElement

RootUIElement 

public UIElement RootUIElement { get; }

Property Value

UIElement

VerticalAlignment 

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

Visibility

Visibility accessor

public Visibility Visibility { get; set; }

Property Value

Visibility

Width 

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
args RoutedEventArgs

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>

ChildElementFromPoint(int, int) 

public UIElement ChildElementFromPoint(int x, int y)

Parameters

x int
y int

Returns

UIElement

ContainsPoint(int, int) 

public bool ContainsPoint(int x, int y)

Parameters

x int
y int

Returns

bool

GetDesiredSize(out int, out int) 

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

Parameters

width int
height int

GetLayoutOffset(out int, out int) 

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

Parameters

x int
y int

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

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

Parameters

left int
top int
right int
bottom int

GetPointerTarget(int, int) 

public UIElement GetPointerTarget(int x, int y)

Parameters

x int
y int

Returns

UIElement

GetRenderSize(out int, out int) 

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

Parameters

width int
height int

GetUnclippedSize(out int, out int) 

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

Parameters

width int
height int

Invalidate() 

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) 

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

Parameters

x int
y int
w int
h int

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

An event reporting a button was pressed.

protected virtual void OnButtonDown(ButtonEventArgs e)

Parameters

e ButtonEventArgs

OnButtonUp(ButtonEventArgs)

An event reporting a button was released.

protected virtual void OnButtonUp(ButtonEventArgs e)

Parameters

e ButtonEventArgs

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)

OnChildrenChanged is called when the UIElementCollection of the UIElement is edited.

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

Parameters

added UIElement
removed UIElement
indexAffected int

OnGenericEvent(GenericEventArgs) 

protected virtual void OnGenericEvent(GenericEventArgs e)

Parameters

e GenericEventArgs

OnGotFocus(FocusChangedEventArgs)

An event announcing that the buttons are focused on this element.

protected virtual void OnGotFocus(FocusChangedEventArgs e)

Parameters

e FocusChangedEventArgs

OnLostFocus(FocusChangedEventArgs)

An event announcing that the buttons is no longer focused on this element

protected virtual void OnLostFocus(FocusChangedEventArgs e)

Parameters

e FocusChangedEventArgs

OnPreviewButtonDown(ButtonEventArgs)

An event reporting a button was pressed.

protected virtual void OnPreviewButtonDown(ButtonEventArgs e)

Parameters

e ButtonEventArgs

OnPreviewButtonUp(ButtonEventArgs)

An event reporting a button was released.

protected virtual void OnPreviewButtonUp(ButtonEventArgs e)

Parameters

e ButtonEventArgs

OnRender(DrawingContext) 

public virtual void OnRender(DrawingContext dc)

Parameters

dc DrawingContext

OnTouchDown(TouchEventArgs) 

protected virtual void OnTouchDown(TouchEventArgs e)

Parameters

e TouchEventArgs

OnTouchGestureChanged(TouchGestureEventArgs) 

protected virtual void OnTouchGestureChanged(TouchGestureEventArgs e)

Parameters

e TouchGestureEventArgs

OnTouchGestureEnded(TouchGestureEventArgs) 

protected virtual void OnTouchGestureEnded(TouchGestureEventArgs e)

Parameters

e TouchGestureEventArgs

OnTouchGestureStarted(TouchGestureEventArgs) 

protected virtual void OnTouchGestureStarted(TouchGestureEventArgs e)

Parameters

e TouchGestureEventArgs

OnTouchMove(TouchEventArgs) 

protected virtual void OnTouchMove(TouchEventArgs e)

Parameters

e TouchEventArgs

OnTouchUp(TouchEventArgs) 

protected virtual void OnTouchUp(TouchEventArgs e)

Parameters

e TouchEventArgs

PointToClient(ref int, ref int) 

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

Parameters

x int
y int

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) 

public void RaiseEvent(RoutedEventArgs args)

Parameters

args RoutedEventArgs

RenderRecursive(DrawingContext) 

protected virtual void RenderRecursive(DrawingContext dc)

Parameters

dc DrawingContext

SetMargin(int) 

public void SetMargin(int length)

Parameters

length int

SetMargin(int, int, int, int) 

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

Parameters

left int
top int
right int
bottom int

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 

public event PropertyChangedEventHandler IsEnabledChanged

Event Type

PropertyChangedEventHandler

IsVisibleChanged 

public event PropertyChangedEventHandler IsVisibleChanged

Event Type

PropertyChangedEventHandler

TouchDown 

public event TouchEventHandler TouchDown

Event Type

TouchEventHandler

TouchGestureChanged 

public event TouchGestureEventHandler TouchGestureChanged

Event Type

TouchGestureEventHandler

TouchGestureEnd 

public event TouchGestureEventHandler TouchGestureEnd

Event Type

TouchGestureEventHandler

TouchGestureStart 

public event TouchGestureEventHandler TouchGestureStart

Event Type

TouchGestureEventHandler

TouchMove 

public event TouchEventHandler TouchMove

Event Type

TouchEventHandler

TouchUp 

public event TouchEventHandler TouchUp

Event Type

TouchEventHandler
Edit this page