Add SelectionListener/SelectedContentRange (#154202)

https://github.com/user-attachments/assets/59225cf7-5506-414e-87da-aa4d3227e7f6

Adds:
* `SelectionListener`, allows a user to listen to selection changes
under the subtree it wraps given their is an ancestor `SelectionArea` or
`SelectableRegion`. These selection changes can be listened to through
the `SelectionListenerNotifier` that is provided to a
`SelectionListener`.
* `SelectionListenerNotifier`, used with `SelectionListener`, allows a
user listen to selection changes for the subtree of the
`SelectionListener` it was provided to. Provides access to individual
selection values through the `SelectionDetails` object `selection`.
* `SelectableRegionSelectionStatusScope`, allows the user to listen to
when a parent `SelectableRegion` is changing or finalizing the
selection.
* `SelectedContentRange`, provides information about the selection range
under a `SelectionHandler` or `Selectable` through the `getSelection()`
method. This includes a start and end offset relative to the
`Selectable`s content.
* `SelectionHandler.contentLength`, to describe the length of the
content contained by a selectable.

Original PR & Discussion: flutter/flutter#148998

Fixes: #110594

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

---------

Co-authored-by: Renzo Olivares <roliv@google.com>

Author: Renzo-Olivares

examples/api/lib/material/selectable_region/selectable_region.0.dart

@@ -94,7 +94,7 @@ class _RenderSelectableAdapter extends RenderProxyBox with Selectable, Selection
   final ValueNotifier<SelectionGeometry> _geometry;
 
   Color get selectionColor => _selectionColor;
-  late Color _selectionColor;
+  Color _selectionColor;
   set selectionColor(Color value) {
     if (_selectionColor == value) {
       return;
@@ -272,6 +272,20 @@ class _RenderSelectableAdapter extends RenderProxyBox with Selectable, Selection
     return value.hasSelection ? const SelectedContent(plainText: 'Custom Text') : null;
   }
 
+  @override
+  SelectedContentRange? getSelection() {
+    if (!value.hasSelection) {
+      return null;
+    }
+    return const SelectedContentRange(
+      startOffset: 0,
+      endOffset: 1,
+    );
+  }
+
+  @override
+  int get contentLength => 1;
+
   LayerLink? _startHandle;
   LayerLink? _endHandle;
 

examples/api/lib/material/selection_area/selection_area.1.dart

@@ -0,0 +1,136 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+
+/// Flutter code sample for [SelectionArea].
+
+void main() => runApp(const SelectionAreaSelectionListenerExampleApp());
+
+class SelectionAreaSelectionListenerExampleApp extends StatelessWidget {
+  const SelectionAreaSelectionListenerExampleApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: 'Flutter Demo',
+      theme: ThemeData(
+        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
+        useMaterial3: true,
+      ),
+      home: const MyHomePage(title: 'Flutter Demo Home Page'),
+    );
+  }
+}
+
+class MyHomePage extends StatefulWidget {
+  const MyHomePage({super.key, required this.title});
+
+  final String title;
+
+  @override
+  State<MyHomePage> createState() => _MyHomePageState();
+}
+
+class _MyHomePageState extends State<MyHomePage> {
+  final SelectionListenerNotifier _selectionNotifier = SelectionListenerNotifier();
+  SelectableRegionSelectionStatus? _selectableRegionStatus;
+
+  void _handleOnSelectionStateChanged(SelectableRegionSelectionStatus status) {
+    setState(() {
+      _selectableRegionStatus = status;
+    });
+  }
+
+  @override
+  void dispose() {
+    _selectionNotifier.dispose();
+    _selectableRegionStatus = null;
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
+        title: Text(widget.title),
+      ),
+      body: Center(
+        child: Column(
+          children: <Widget>[
+            Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: <Widget>[
+                for (final (int? offset, String label) in <(int? offset, String label)>[
+                  (_selectionNotifier.registered ? _selectionNotifier.selection.range?.startOffset : null, 'StartOffset'),
+                  (_selectionNotifier.registered ? _selectionNotifier.selection.range?.endOffset : null, 'EndOffset'),
+                ])
+                  Text('Selection $label: $offset'),
+                Text('Selection Status: ${_selectionNotifier.registered ? _selectionNotifier.selection.status : 'SelectionListenerNotifier not registered.'}'),
+                Text('Selectable Region Status: $_selectableRegionStatus'),
+              ],
+            ),
+            const SizedBox(height: 15.0,),
+            SelectionArea(
+              child: MySelectableText(
+                selectionNotifier: _selectionNotifier,
+                onChanged: _handleOnSelectionStateChanged,
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class MySelectableText extends StatefulWidget {
+  const MySelectableText({
+    super.key,
+    required this.selectionNotifier,
+    required this.onChanged,
+  });
+
+  final SelectionListenerNotifier selectionNotifier;
+  final ValueChanged<SelectableRegionSelectionStatus> onChanged;
+
+  @override
+  State<MySelectableText> createState() => _MySelectableTextState();
+}
+
+class _MySelectableTextState extends State<MySelectableText> {
+  ValueListenable<SelectableRegionSelectionStatus>? _selectableRegionScope;
+
+  void _handleOnSelectableRegionChanged() {
+    if (_selectableRegionScope == null) {
+      return;
+    }
+    widget.onChanged.call(_selectableRegionScope!.value);
+  }
+
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    _selectableRegionScope?.removeListener(_handleOnSelectableRegionChanged);
+    _selectableRegionScope = SelectableRegionSelectionStatusScope.maybeOf(context);
+    _selectableRegionScope?.addListener(_handleOnSelectableRegionChanged);
+  }
+
+  @override
+  void dispose() {
+    _selectableRegionScope?.removeListener(_handleOnSelectableRegionChanged);
+    _selectableRegionScope = null;
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return SelectionListener(
+      selectionNotifier: widget.selectionNotifier,
+      child: const Text('This is some text under a SelectionArea that can be selected.'),
+    );
+  }
+}