Traverses the element tree downward, looking for elements/widgets that meet certain criteria.

Use Like:

List<Element> matches = context.findChildElementsMatching( ( e ) => e.widget is MyCustomWidget );
Element firstMatch = context.findFirstChildElementForWidgetOfType<MyCustomWidget>();
Element lastMatch = context.findLastChildElementForWidgetOfType<MyCustomWidget>();

Additional information

USE WITH CAUTION!!

Calling this method is potentially expensive for build contexts that correspond to RenderObjectWidgets (O(N) in the number of children).

Calling this method recursively is extremely expensive (O(N) in the number of descendants), and should be avoided if possible. Generally it is significantly cheaper to use an InheritedWidget and have the descendants pull data down, than it is to use visitChildElements recursively to push data down to them.

Depth Condition / Conflict

When traversing the element tree downward, there can often times be the same type of element at the same depth.

I plan on adding DepthConflictStrategy support in the future to provide some further instruction on what to do if there is a conflict.

Example (future) Cases:

DepthConflictStrategy.useFirst;
DepthConflictStrategy.useLast;
DepthConflictStrategy.custom;