Provides methods to travel a WPF visual tree and to find items of interest.
Goes beyond framework's VisualTreeHelper GetParent and GetChild methods by allowing traversal of ContentElement objects.
- Use 'FindParent' methods to travel the visual tree up and 'FindChildren' methods to walk it down
- Use either static helpers or extension methods:
- ex: WpfVisualFinders.FindParent(node) or node.FindParent()
- Most searches target a specific type and optionally a name or a regex filter:
- Type can be given at compile time, or at runtime using the 'ByType' methods
- ex: FindParent{MyType}(node) vs FindParentByType(node, myTypeInstance)
- You can target the 'object' type to get rid or type filtering during search
- Item search-by-name is complementary and is activated when setting the optional 'name' argument
- Name can be the exact name or a regular expression
- Type can be given at compile time, or at runtime using the 'ByType' methods
Finds a child of the specified type by walking down the visual tree from the passed node. Every leaves are explored until matching child is found.
T FindChild<T>(DependencyObject node, string name = null, bool allowContentElements = true)
DependencyObject FindChildByType(DependencyObject node, Type type, string name = null, bool allowContentElements = true)
Finds a child of a specific type by walking down the visual tree from the passed node and through first encountered children only. Search is stopped when a matching item is found or when the most accessible leaf is reached.
T FindDirectChild<T>(DependencyObject node, string name = null, bool allowContentElements = true)
DependencyObject FindDirectChildByType(DependencyObject node, Type type, string name = null, bool allowContentElements = true)
Builds up an enumerable of all passed node's descendants that match target type and optional name or regex. Looks at every paths from top node.
IEnumerable<T> FindAllChildren<T>(DependencyObject node, string name = null, bool allowContentElements = true)
IEnumerable<DependencyObject> FindAllChildrenByType(DependencyObject node, Type type, string name = null, bool allowContentElements = true)
Note This method explores and exposes the matching children level-by-level rather than branch-by-branch. Thus, all matching children are exposed, then all matching grandchildren, then all matching grand-grandchildren, etc.
Finds first parent that matches specified type and optional name or regex by walking up the visual tree from the passed node. Returns null after tree top is reached with no result.
T FindParent<T>(DependencyObject node, string name = null, bool allowContentElements = true)
DependencyObject FindParentByType(DependencyObject node, Type type, string name = null, bool allowContentElements = true)
Finds parent taken at a given depth level from the passed node. Returns null if level to cross if too large or if cannot walk the tree up at some point.
DependencyObject FindParentByLevel(DependencyObject node, int level = 1, bool allowContentElements = true)
Note When level defaults to 1, the method gets the immediate parent.
An extension of the VisualTreeHelper.GetParent() method that supports travel through ContentElement objects.
DependencyObject GetParentExtended(DependencyObject node)
ContentElements - and more specifically their derived ContentFrameworkElement counterparts - are special items that dictates rendering on screen for the part they describe but are not attachable to the visual tree and rely on the logical one. However, these items have many APIs in common with the objects we find on visual tree (specifically FrameworkElement) -including naming -, are directly visible in the XAML definitions, and might contain useful information about the visual they represent.
All these reasons make them important nodes to find or travel through while exploring the visual tree, although they are not part of it. As a consequence:
All provided methods allows ContentElement traversal by default. This feature can disabled by setting allowContentElements = false on any method call.
Some ContentElement examples:
This work is licensed under the MIT License.