feat: Control and listen to selection/caret changes in TextField

[ndonkoHenri]

Fix #1005
Fix #1742
Fix #2916
Fix #5467
Fix #3335
Fix #5708

Example

import flet as ft


def main(page: ft.Page):
    page.title = "Text selection"

    def handle_selection_change(e: ft.TextSelectionChangeEvent[ft.TextField]):
        selection.value = (
            f"Selection: '{e.selected_text}'" if e.selected_text else "No selection."
        )
        selection_details.value = f"start={e.selection.start}, end={e.selection.end}"
        caret.value = f"Caret position: {e.selection.end}"

    async def select_characters(e: ft.Event[ft.Button]):
        await field.focus()
        field.selection = ft.TextSelection(
            base_offset=0, extent_offset=len(field.value)
        )

    async def move_caret(e: ft.Event[ft.Button]):
        await field.focus()
        field.selection = ft.TextSelection(base_offset=0, extent_offset=0)

    page.add(
        ft.Column(
            spacing=10,
            controls=[
                field := ft.TextField(
                    value="Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
                    multiline=True,
                    min_lines=3,
                    autofocus=True,
                    on_selection_change=handle_selection_change,
                ),
                selection := ft.Text("Select some text from the field."),
                selection_details := ft.Text(),
                caret := ft.Text("Caret position: -"),
                ft.Button(
                    content="Select all text",
                    on_click=select_characters,
                ),
                ft.Button(
                    content="Move caret to start",
                    on_click=move_caret,
                ),
            ],
        )
    )


ft.run(main)

Summary by Sourcery

Implement text selection and caret control in text fields across Dart and Python SDK, including new event triggers, property parsing, and updated utilities, plus docs and examples.

New Features:

• Add selection property and on_selection_change event to TextField and CupertinoTextField for programmatic control and listening to selection/caret changes

Enhancements:

• Extend Python SDK TextSelection with computed properties (start, end, is_valid, is_collapsed, is_normalized, etc.) and implement parsing/serialization in Dart
• Refactor text utility functions (getTextStyle, getFontWeight) to use lookup maps
• Update base controls size animation logic to handle constraints and animations correctly

Documentation:

• Add documentation and code examples for handling selection changes in TextField and CupertinoTextField
• Enable show_labels in mkdocs configuration

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[Copilot]

Pull Request Overview

This PR adds text selection control and monitoring capabilities to TextField and CupertinoTextField components. Users can now programmatically control text selection/caret position and listen to selection change events through a new on_selection_change callback.

Key Changes

• Introduced TextSelection class with base_offset/extent_offset properties to represent text selections
• Added on_selection_change event handler to TextField/CupertinoTextField for monitoring selection changes
• Added selection property to TextField for programmatic control of text selection and caret position

Reviewed Changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
sdk/python/packages/flet/src/flet/controls/material/textfield.py	Added selection property and on_selection_change event handler to TextField
sdk/python/packages/flet/src/flet/controls/material/form_field_control.py	Added documentation for the focus() method
sdk/python/packages/flet/src/flet/controls/core/text.py	Refactored TextSelection to use base_offset/extent_offset as required fields with computed properties; updated TextSelectionChangeEvent structure
sdk/python/packages/flet/mkdocs.yml	Enabled show_labels in documentation configuration
sdk/python/packages/flet/docs/controls/textfield.md	Added example demonstrating selection change handling
sdk/python/packages/flet/docs/controls/cupertinotextfield.md	Added selection change and background image examples
sdk/python/packages/flet-map/src/flet_map/marker_layer.py	Fixed broken reference link in documentation
sdk/python/examples/controls/text_field/selection_change.py	New example demonstrating selection monitoring and control
sdk/python/examples/controls/cupertino_text_field/selection_change.py	New example for CupertinoTextField selection handling
sdk/python/examples/controls/cupertino_text_field/label_focus.py	Removed obsolete example file
packages/flet/lib/src/utils/text.dart	Added TextSelection parsing utilities and refactored switch statements to map lookups
packages/flet/lib/src/controls/textfield.dart	Implemented selection change tracking and programmatic selection control
packages/flet/lib/src/controls/text.dart	Updated event field name from "text" to "selected_text"
packages/flet/lib/src/controls/cupertino_textfield.dart	Implemented selection change tracking for CupertinoTextField
packages/flet/lib/src/controls/base_controls.dart	Refactored _sizedControl to properly handle AnimatedContainer with dimensions

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[cloudflare-workers-and-pages]

Deploying flet-docs with    Cloudflare Pages

Latest commit:	fbdb83f
Status:	✅  Deploy successful!
Preview URL:	https://e0a3286e.flet-docs.pages.dev
Branch Preview URL:	https://textfield-text-selection.flet-docs.pages.dev

View logs