Suggest predicate-based formatter in [FilteringTextInputFormatter] docs for...

Suggest predicate-based formatter in [FilteringTextInputFormatter] docs for whole string matching (#107848)

packages/flutter/lib/src/rendering/viewport.dart

@@ -751,8 +751,8 @@ abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMix
     // Steps to convert `rect` (from a RenderBox coordinate system) to its
     // scroll offset within this viewport (not in the exact order):
     //
-    // 1. Pick the outmost RenderBox (between which, and the viewport, there is
-    // nothing but RenderSlivers) as an intermediate reference frame
+    // 1. Pick the outermost RenderBox (between which, and the viewport, there
+    // is nothing but RenderSlivers) as an intermediate reference frame
     // (the `pivot`), convert `rect` to that coordinate space.
     //
     // 2. Convert `rect` from the `pivot` coordinate space to its sliver

packages/flutter/lib/src/services/text_formatter.dart

@@ -212,19 +212,31 @@ class _TextEditingValueAccumulator {
   }
 }
 
-/// A [TextInputFormatter] that prevents the insertion of characters
-/// matching (or not matching) a particular pattern.
+/// A [TextInputFormatter] that prevents the insertion of characters matching
+/// (or not matching) a particular pattern, by replacing the characters with the
+/// given [replacementString].
 ///
 /// Instances of filtered characters found in the new [TextEditingValue]s
-/// will be replaced with the [replacementString] which defaults to the empty
-/// string.
+/// will be replaced by the [replacementString] which defaults to the empty
+/// string, and the current [TextEditingValue.selection] and
+/// [TextEditingValue.composing] region will be adjusted to account for the
+/// replacement.
 ///
-/// Since this formatter only removes characters from the text, it attempts to
-/// preserve the existing [TextEditingValue.selection] to values it would now
-/// fall at with the removed characters.
+/// This formatter is typically used to match potentially recurring [Pattern]s
+/// in the new [TextEditingValue]. It never completely rejects the new
+/// [TextEditingValue] and falls back to the current [TextEditingValue] when the
+/// given [filterPattern] fails to match. Consider using a different
+/// [TextInputFormatter] such as:
+/// ```dart
+/// TextInputFormatter.withFunction((oldValue, newValue) => regExp.hasMatch(newValue.text) ? newValue : oldValue)
+/// ```
+/// for accepting/rejecting new input based on a predicate on the full string.
+/// As an example, [FilteringTextInputFormatter] typically shouldn't be used
+/// with [RegExp]s that contain positional matchers (`^` or `$`) since these
+/// patterns are usually meant for matching the whole string.
 class FilteringTextInputFormatter extends TextInputFormatter {
-  /// Creates a formatter that prevents the insertion of characters
-  /// based on a filter pattern.
+  /// Creates a formatter that replaces banned patterns with the given
+  /// [replacementString].
   ///
   /// If [allow] is true, then the filter pattern is an allow list,
   /// and characters must match the pattern to be accepted. See also

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

@@ -299,7 +299,7 @@ class SlottedRenderObjectElement<S> extends RenderObjectElement {
       throw FlutterError.fromParts(<DiagnosticsNode>[
         ErrorSummary('Multiple widgets used the same key in ${widget.runtimeType}.'),
         ErrorDescription(
-          'The key ${duplicateKey.key} was used by multiple widgets. The parents of those widgets were:\n'
+          'The key ${duplicateKey.key} was used by multiple widgets. The offending widgets were:\n'
         ),
         for (final Element element in duplicateKey.value) ErrorDescription('  - $element\n'),
         ErrorDescription(

packages/flutter/test/widgets/slotted_render_object_widget_test.dart

@@ -197,7 +197,7 @@ void main() {
 
     expect((tester.takeException() as FlutterError).toString(), equalsIgnoringHashCodes(
      'Multiple widgets used the same key in _Diagonal.\n'
-     "The key [<'widget 1'>] was used by multiple widgets. The parents of those widgets were:\n"
+     "The key [<'widget 1'>] was used by multiple widgets. The offending widgets were:\n"
      "  - SizedBox-[<'widget 1'>](width: 50.0, height: 50.0, renderObject: RenderConstrainedBox#00000 NEEDS-LAYOUT NEEDS-PAINT)\n"
      "  - SizedBox-[<'widget 1'>](width: 10.0, height: 10.0, renderObject: RenderConstrainedBox#00000 NEEDS-LAYOUT NEEDS-PAINT)\n"
      "  - SizedBox-[<'widget 1'>](width: 100.0, height: 100.0, renderObject: RenderConstrainedBox#a4685 NEEDS-LAYOUT NEEDS-PAINT)\n"