feat: Control and listen to selection/caret changes in TextField (#5725)

* initial commit

* support `CupertinoTextField`

* Fix #2916: Downsizing `Stack` has no animation

* enable `show_labels` in mkdocs configuration

* improve documentation

* update documentation for clarity and focus requirement

* refactor: simplify animation handling in sized control

* improve file picker docs

* fix docs

Author: ndonkoHenri

packages/flet/lib/src/controls/base_controls.dart

@@ -282,11 +282,7 @@ Widget _positionedControl(
       top: top,
       right: right,
       bottom: bottom,
-      onEnd: control.getBool("on_animation_end", false)!
-          ? () {
-              control.triggerEvent("animation_end", "position");
-            }
-          : null,
+      onEnd: () => control.triggerEvent("animation_end", "position"),
       child: widget,
     );
   } else if (left != null || top != null || right != null || bottom != null) {
@@ -305,25 +301,34 @@ Widget _positionedControl(
 }
 
 Widget _sizedControl(Widget widget, Control control) {
-  final skipProps = control.internals?["skip_properties"] as List?;
-  if (skipProps?.contains("width") == true ||
-      skipProps?.contains("height") == true) {
+  final skipProps = control.internals?['skip_properties'] as List?;
+  if (skipProps != null && ['width', 'height'].any(skipProps.contains)) {
     return widget;
   }
 
-  var width = control.getDouble("width");
-  var height = control.getDouble("height");
+  final width = control.getDouble("width");
+  final height = control.getDouble("height");
+  final animationSize = control.getAnimation("animate_size");
 
-  if ((width != null || height != null)) {
-    widget = ConstrainedBox(
-      constraints: BoxConstraints.tightFor(width: width, height: height),
-      child: widget,
-    );
-  }
-  var animation = control.getAnimation("animate_size");
-  if (animation != null) {
-    return AnimatedSize(
-        duration: animation.duration, curve: animation.curve, child: widget);
+  final hasFixedSize = width != null || height != null;
+
+  if (animationSize != null) {
+    return hasFixedSize
+        ? AnimatedContainer(
+            duration: animationSize.duration,
+            curve: animationSize.curve,
+            width: width,
+            height: height,
+            child: widget,
+          )
+        : AnimatedSize(
+            duration: animationSize.duration,
+            curve: animationSize.curve,
+            child: widget,
+          );
+  } else {
+    return hasFixedSize
+        ? SizedBox(width: width, height: height, child: widget)
+        : widget;
   }
-  return widget;
 }

packages/flet/lib/src/controls/cupertino_textfield.dart

@@ -41,11 +41,13 @@ class _CupertinoTextFieldControlState extends State<CupertinoTextFieldControl> {
   late final FocusNode _shiftEnterfocusNode;
   String? _lastFocusValue;
   String? _lastBlurValue;
+  TextSelection? _selection;
 
   @override
   void initState() {
     super.initState();
     _controller = TextEditingController();
+    _controller.addListener(_handleControllerChange);
     _shiftEnterfocusNode = FocusNode(
       onKeyEvent: (FocusNode node, KeyEvent evt) {
         if (!HardwareKeyboard.instance.isShiftPressed &&
@@ -67,6 +69,7 @@ class _CupertinoTextFieldControlState extends State<CupertinoTextFieldControl> {
 
   @override
   void dispose() {
+    _controller.removeListener(_handleControllerChange);
     _controller.dispose();
     _shiftEnterfocusNode.removeListener(_onShiftEnterFocusChange);
     _shiftEnterfocusNode.dispose();
@@ -101,6 +104,25 @@ class _CupertinoTextFieldControlState extends State<CupertinoTextFieldControl> {
     widget.control.triggerEvent(_focusNode.hasFocus ? "focus" : "blur");
   }
 
+  void _handleControllerChange() {
+    final selection = _controller.selection;
+    if (_selection == selection) return;
+
+    _selection = selection;
+
+    if (!selection.isValid ||
+        !widget.control.getBool("on_selection_change", false)!) {
+      return;
+    }
+
+    widget.control.updateProperties({"selection": selection.toMap()});
+    widget.control.triggerEvent("selection_change", {
+      "selected_text":
+          _controller.text.substring(selection.start, selection.end),
+      "selection": selection.toMap()
+    });
+  }
+
   @override
   Widget build(BuildContext context) {
     debugPrint("CupertinoTextField build: ${widget.control.id}");
@@ -109,7 +131,12 @@ class _CupertinoTextFieldControlState extends State<CupertinoTextFieldControl> {
     var value = widget.control.getString("value", "")!;
     if (_value != value) {
       _value = value;
-      _controller.text = value;
+      _controller.value = TextEditingValue(
+        text: value,
+        // preserve cursor position at the end
+        selection: TextSelection.collapsed(offset: value.length),
+      );
+      _selection = _controller.selection;
     }
 
     var shiftEnter = widget.control.getBool("shift_enter", false)!;
@@ -165,6 +192,13 @@ class _CupertinoTextFieldControlState extends State<CupertinoTextFieldControl> {
       _focusNode.unfocus();
     }
 
+    var selection = widget.control.getTextSelection("selection",
+        minOffset: 0, maxOffset: _controller.text.length);
+    if (selection != null && selection != _controller.selection) {
+      _controller.selection = selection;
+      _selection = selection;
+    }
+
     var borderRadius = widget.control.getBorderRadius("border_radius");
 
     BoxBorder? border;

packages/flet/lib/src/controls/text.dart

@@ -82,13 +82,12 @@ class TextControl extends StatelessWidget {
 
     TextAlign textAlign =
         parseTextAlign(control.getString("text_align"), TextAlign.start)!;
-
     TextOverflow overflow =
         parseTextOverflow(control.getString("overflow"), TextOverflow.clip)!;
 
     onSelectionChanged(TextSelection selection, SelectionChangedCause? cause) {
       control.triggerEvent("selection_change", {
-        "text": text,
+        "selected_text": text,
         "cause": cause?.name ?? "unknown",
         "selection": selection.toMap(),
       });

packages/flet/lib/src/controls/textfield.dart

@@ -36,11 +36,13 @@ class _TextFieldControlState extends State<TextFieldControl> {
   late final FocusNode _shiftEnterfocusNode;
   String? _lastFocusValue;
   String? _lastBlurValue;
+  TextSelection? _selection;
 
   @override
   void initState() {
     super.initState();
     _controller = TextEditingController();
+    _controller.addListener(_handleControllerChange);
     _shiftEnterfocusNode = FocusNode(
       onKeyEvent: (FocusNode node, KeyEvent evt) {
         if (!HardwareKeyboard.instance.isShiftPressed &&
@@ -62,6 +64,7 @@ class _TextFieldControlState extends State<TextFieldControl> {
 
   @override
   void dispose() {
+    _controller.removeListener(_handleControllerChange);
     _controller.dispose();
     _shiftEnterfocusNode.removeListener(_onShiftEnterFocusChange);
     _shiftEnterfocusNode.dispose();
@@ -92,6 +95,25 @@ class _TextFieldControlState extends State<TextFieldControl> {
     widget.control.triggerEvent(_focusNode.hasFocus ? "focus" : "blur");
   }
 
+  void _handleControllerChange() {
+    final selection = _controller.selection;
+    if (_selection == selection) return;
+
+    _selection = selection;
+
+    if (!selection.isValid ||
+        !widget.control.getBool("on_selection_change", false)!) {
+      return;
+    }
+
+    widget.control.updateProperties({"selection": selection.toMap()});
+    widget.control.triggerEvent("selection_change", {
+      "selected_text":
+          _controller.text.substring(selection.start, selection.end),
+      "selection": selection.toMap()
+    });
+  }
+
   @override
   Widget build(BuildContext context) {
     debugPrint("TextField build: ${widget.control.id}");
@@ -103,9 +125,17 @@ class _TextFieldControlState extends State<TextFieldControl> {
       _value = value;
       _controller.value = TextEditingValue(
         text: value,
-        selection: TextSelection.collapsed(
-            offset: value.length), // preserve cursor position at the end
+        // preserve cursor position at the end
+        selection: TextSelection.collapsed(offset: value.length),
       );
+      _selection = _controller.selection;
+    }
+
+    var selection = widget.control.getTextSelection("selection",
+        minOffset: 0, maxOffset: _controller.text.length);
+    if (selection != null && selection != _controller.selection) {
+      _controller.selection = selection;
+      _selection = selection;
     }
 
     var shiftEnter = widget.control.getBool("shift_enter", false)!;