rename Element.visitChildrenForSemantics to visitOnstageChildren; fix DropdownButton (#11744)

* rename Element.visitChildrenForSemantics to debugVisitOnstageChildren

* address comments

packages/flutter/lib/src/widgets/basic.dart

@@ -1851,9 +1851,9 @@ class _OffstageElement extends SingleChildRenderObjectElement {
   Offstage get widget => super.widget;
 
   @override
-  void visitChildrenForSemantics(ElementVisitor visitor) {
+  void debugVisitOnstageChildren(ElementVisitor visitor) {
     if (!widget.offstage)
-      super.visitChildrenForSemantics(visitor);
+      super.debugVisitOnstageChildren(visitor);
   }
 }
 

packages/flutter/lib/src/widgets/framework.dart

@@ -2595,10 +2595,27 @@ abstract class Element extends DiagnosticableTree implements BuildContext {
   /// only be called if it is provable that the children are available.
   void visitChildren(ElementVisitor visitor) { }
 
-  /// Calls the argument for each child that is relevant for semantics. By
-  /// default, defers to [visitChildren]. Classes like [Offstage] override this
-  /// to hide their children.
-  void visitChildrenForSemantics(ElementVisitor visitor) => visitChildren(visitor);
+  /// Calls the argument for each child considered onstage.
+  ///
+  /// Classes like [Offstage] and [Overlay] override this method to hide their
+  /// children.
+  ///
+  /// Being onstage affects the element's discoverability during testing when
+  /// you use Flutter's [Finder] objects. For example, when you instruct the
+  /// test framework to tap on a widget, by default the finder will look for
+  /// onstage elements and ignore the offstage ones.
+  ///
+  /// The default implementation defers to [visitChildren] and therefore treats
+  /// the element as onstage.
+  ///
+  /// See also:
+  ///
+  /// - [Offstage] widget that hides its children.
+  /// - [Finder] that skips offstage widgets by default.
+  /// - [RenderObject.visitChildrenForSemantics], in contrast to this method,
+  ///   designed specifically for excluding parts of the UI from the semantics
+  ///   tree.
+  void debugVisitOnstageChildren(ElementVisitor visitor) => visitChildren(visitor);
 
   /// Wrapper around [visitChildren] for [BuildContext].
   @override

packages/flutter/lib/src/widgets/overlay.dart

@@ -470,7 +470,7 @@ class _TheatreElement extends RenderObjectElement {
   }
 
   @override
-  void visitChildrenForSemantics(ElementVisitor visitor) {
+  void debugVisitOnstageChildren(ElementVisitor visitor) {
     if (_onstage != null)
       visitor(_onstage);
   }

packages/flutter_test/lib/src/all_elements.dart

@@ -51,7 +51,7 @@ class _DepthFirstChildIterator implements Iterator<Element> {
     assert(element != null);
     final List<Element> children = <Element>[];
     if (skipOffstage) {
-      element.visitChildrenForSemantics(children.add);
+      element.debugVisitOnstageChildren(children.add);
     } else {
       element.visitChildren(children.add);
     }

packages/flutter_test/lib/src/finders.dart

@@ -232,7 +232,7 @@ abstract class Finder {
   /// Whether this finder skips nodes that are offstage.
   ///
   /// If this is true, then the elements are walked using
-  /// [Element.visitChildrenForSemantics]. This skips offstage children of
+  /// [Element.debugVisitOnstageChildren]. This skips offstage children of
   /// [Offstage] widgets, as well as children of inactive [Route]s.
   final bool skipOffstage;