navigating-mewui-tree— agent skill

Element Hierarchy

Element (base)
└─ UIElement (input, visibility, focus)
   └─ FrameworkElement (sizing, margin, alignment)
      ├─ Panel (multi-child: StackPanel, Grid, Canvas, DockPanel)
      ├─ Control (themed elements: Button, Label, TextBox)
      │  ├─ ContentControl (single child: Window)
      │  └─ Border (decorator)
      └─ ...

Parent-Child Relationships

// Every element has one parent
Element? parent = element.Parent;

// Multi-child (Panel)
panel.Add(child);       // Sets child.Parent = panel
panel.Remove(child);    // Sets child.Parent = null
panel.Children;         // IReadOnlyList<Element>

// Single-child (ContentControl, Border)
contentControl.Content = child;  // Element? type, sets child.Parent
border.Child = child;            // UIElement? type

Tree Traversal

// Find visual root (usually Window)
Element? root = element.FindVisualRoot();

// Check ancestry
bool isChild = element.IsDescendantOf(ancestor);
bool isParent = element.IsAncestorOf(descendant);  // Also available

// Find ancestor of type
static T? FindAncestor<T>(Element element) where T : Element
{
    for (var cur = element.Parent; cur != null; cur = cur.Parent)
        if (cur is T match) return match;
    return null;
}

Note: VisualTree.Visit() exists but is internal - use FindVisualRoot/IsDescendantOf for external code.

IVisualTreeHost (Internal)

Interface for elements with children (internal API):

internal interface IVisualTreeHost
{
    void VisitChildren(Action<Element> visitor);
}

// Panel implementation
void IVisualTreeHost.VisitChildren(Action<Element> visitor)
{
    foreach (var child in _children)
        visitor(child);
}

// ContentControl implementation
void IVisualTreeHost.VisitChildren(Action<Element> visitor)
{
    if (Content != null) visitor(Content);
}

Visual Root Lifecycle

// Called when element joins/leaves tree
protected virtual void OnVisualRootChanged(Element? oldRoot, Element? newRoot)
{
    // newRoot == null: removed from tree
    // newRoot is Window: added to tree
}

Coordinate Transforms

// Transform to ancestor
var transform = element.TransformToAncestor(ancestor);

// Translate point between elements
Point translated = element.TranslatePoint(localPoint, otherElement);

// Mouse position - use MouseEventArgs.Position property
protected override void OnMouseMove(MouseEventArgs e)
{
    Point pos = e.Position;  // Position relative to this element
}

Hit testing: See hit-testing.md