Class UIElementExtensions

Namespace

Icy.UI

Assembly

IcyUI.dll

Convenience operations over an existing UIElement tree - walking it, searching it, and looking elements up by name.

public static class UIElementExtensions

Inheritance

object

UIElementExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

Detach(UIElement)

Removes the UIElement instance from its parent. If the element is root, removes it from the Canvas instance.

public static void Detach(this UIElement element)

Parameters

element UIElement

The element to detach.

EnumerateSubtree(UIElement)

Enumerates element and every element beneath it, depth-first.

public static IEnumerable<UIElement> EnumerateSubtree(this UIElement element)

Parameters

element UIElement

The element to start from.

Returns

IEnumerable<UIElement>

element first, then its whole subtree.

Remarks

Walks the visual tree, so it also sees elements a control builds for itself - a Control's chrome Border, for instance - not only the children an author added.

FindChildren(UIElement, Func<UIElement, bool>)

Finds every element beneath control matching predicate.

public static IEnumerable<UIElement> FindChildren(this UIElement control, Func<UIElement, bool> predicate)

Parameters

control UIElement

The element to search under.

predicate Func<UIElement, bool>

The condition an element must satisfy to be returned.

Returns

IEnumerable<UIElement>

The matching descendants, in depth-first order. control itself is not tested.

FindControl<T>(UIElement, string)

Finds the element named name in element's tree.

public static T? FindControl<T>(this UIElement element, string name) where T : UIElement

Parameters

element UIElement

Any element in the tree to search - the search starts from its root.

name string

The name to look up, as declared by x:Name or assigned to Name.

Returns

T

The named element, or null when the tree has none, or has one of another type.

Type Parameters

T

The type the named element is expected to have.

Remarks

A tree loaded from markup carries a MarkupNameScope on its root, and this is a dictionary lookup in it. A hand-built tree has no scope, so the whole subtree is walked and matched on Name instead - the same call works either way, just at different cost.

The search starts at the root of element's tree, not at element itself, so any element can look up any other in the same document. An element that is not yet attached to anything is its own root.

FindRequiredControl<T>(UIElement, string)

Finds the element named name in element's tree, and throws when it isn't there.

public static T FindRequiredControl<T>(this UIElement element, string name) where T : UIElement

Parameters

element UIElement

Any element in the tree to search - the search starts from its root.

name string

The name to look up.

Returns

T

The named element.

Type Parameters

T

The type the named element is expected to have.

Remarks

Use this over FindControl<T>(UIElement, string) wherever the element is required for the code to work at all - a missing name then fails at the lookup, naming what was missing, instead of surfacing as a null somewhere later.

Exceptions

InvalidOperationException

No element in the tree is named name, or the one that is isn't a T.

GetRoot(UIElement)

Walks up to the topmost element above element.

public static UIElement GetRoot(this UIElement element)

Parameters

element UIElement

The element to start from.

Returns

UIElement

The root of element's tree, or element when it is the root.

Remarks

Stops at the topmost UIElement, which is the element added to a Canvas - the canvas itself is not a UIElement and is not part of the walk.

Localize(UIElement, string, string, string?)

Sets propertyName to the localized string for key, and keeps it updated when the configuration's Culture changes: {Localize} for UI built in code.

public static void Localize(this UIElement element, string propertyName, string key, string? context = null)

Parameters

element UIElement

The element.

propertyName string

The property, such as nameof(TextBlock.Text).

key string

The key, such as Menu.Play.

context string

An optional context for the key.

Remarks

An element that isn't on a canvas yet gets its string when it's attached: the configuration comes from the canvas. Setting the property to something else later, before or after it's attached, stops the updates.

Exceptions

ArgumentException

propertyName isn't a property of the element.

WithStyle<T>(T, Style)

Applies a style to the UI element.

public static T WithStyle<T>(this T element, Style style) where T : UIElement

Parameters

element T

The element to style.

style Style

Style instance to apply.

Returns

T

The same element, for chaining.

Type Parameters

T

The type of the element the style is applied to.