# Text Editing ## What data structures support editable text? * `TextRange` represents a range using \[start, end) character indices: start is the index of the first character and end is the index after the last character. If both are -1, the range is collapsed (empty) and outside of the text (invalid). If both are equal, the range is collapsed but potentially within the text (i.e., an insertion point). If start <= end, the range is said to be normal. * `TextSelection` expands on range to represent a selection of text. A range is specified as a \[`baseOffset`, `extentOffset`) using character indices. The lesser will always become the base offset, with the greater becoming the extent offset (i.e., the range is normalized). If both offsets are the same, the selection is collapsed, representing an insertion point; selections have a concept of directionality (`TextSelection.isDirectional`) which may be left ambiguous until the selection is uncollapsed. Both offsets are resolved to positions using a provided affinity. This ensures that the selection is unambiguous before and after rendering (e.g., due to automatic line breaks). * `TextSelectionPoint` pairs an offset with the text direction at that offset; this is helpful for determining how to render a selection handle at a given position. * `TextEditingValue` captures the current editing state. It exposes the full text in the editor (`TextEditingValue.text`), a range in that text that is still being composed (`TextEditingValue.composing`), and any selection present in the UI (`TextEditingValue.selection`). Note that an affinity isn’t necessary for the composing range since it indexes unrendered text. ## How are editing and selection overlays built? * `TextSelectionDelegate` supports reading and writing the selection (via `TextSelectionDelegate.textEditingValue`), configures any associated selection actions (e.g., `TextSelectionDelegate.canCopy`), and provides helpers to manage selection UI (e.g., `TextSelectionDelegate.bringIntoView`, `TextSelectionDelegate.hideToolbar`). This delegate is utilized primarily by `TextSelectionControls` to implement the toolbar and selection handles. * `ToolbarOptions` is a helper bundling all options that determine toolbar behavior within an `EditableText` -- that is, how the overridden `TextSelectionDelegate` methods behave. * `TextSelectionControls` is an abstract class that builds and manages selection-related UI including the toolbar and selection handles. This class also implements toolbar behaviors (e.g., `TextSelectionControls.handleCopy`) and eligibility checks (e.g., `TextSelectionControls.canCopy`), deferring to the delegate where appropriate (e.g., `TextSelectionDelegate.bringIntoView` to scroll the selection into view). These checks are mainly used by `TextSelectionControls`’ build methods (e.g., `TextSelectionControls.buildHandle`, `TextSelectionControls.buildToolbar`), which construct the actual UI. Concrete implementations are provided for `Cupertino` and `Material` (`_CupertinoTextSelectionControls` and `_MaterialTextSelectionControls`, respectively), producing idiomatic UI for the corresponding platform. The build process is initiated by `TextSelectionOverlay`. * `TextSelectionOverlay` is the visual engine underpinning selection UI. It integrates `TextSelectionControls` and `TextSelectionDelegate` to build and configure the text selection handles and toolbar, and `TextEditingValue` to track the current editing state; the editing state may be updated at any point (via `TextSelectionOverlay.update`). Updates are made build-safe by scheduling a post-frame callback if in the midst of a persistent frame callback (building, layout, etc; this avoids infinite recursion in the build method). * The UI is inserted into the enclosing `Overlay` and hidden and shown as needed (via `TextSelectionOverlay.hide`, `TextSelectionOverlay.showToolbar`, etc). * The toolbar and selection handles are positioned using leader/follower layers (via `CompositedTransformLeader` and `CompositedTransformFollower`). A `LayerLink` instance for each type of UI is anchored to a region within the editable text so that the two layers are identically transformed (e.g., to efficiently scroll together). When this happens, `TextSelectionOverlay.updateForScroll` marks the overlay as needing to be rebuilt so that the UI can adjust to its new position. * The toolbar is built directly (via `TextSelectionControls.buildToolbar`), whereas each selection handle corresponds to a `_TextSelectionHandleOverlay` widget. These widgets invoke a handler when the selection range changes to update the `TextEditingValue` (via `TextSelectionOverlay._handleSelectionHandleChanged`). * `TextSelectionGestureDetector` is a stateful widget that recognizes a sequence of selection-related gestures (e.g., a tap followed by a double tap), unlike a typical detector which recognizes just one. The text field (e.g., `TextField`) incorporates the gesture detector when building the corresponding UI. * `_TextSelectionGestureDetectorState` coordinates the text editing gesture detectors, multiplexing them as described above. A map of recognizer factories is assembled and assigned callbacks (via `GestureRecognizerFactoryWithHandlers`) given the widget’s configuration. These are passed to a `RawGestureDetector` widget which constructs the recognizers as needed. * `_TransparentTapGestureRecognizer` is a `TapGestureRecognizer` capable of recognizing while ceding to other recognizers in the arena. Thus, the same tap may be handled by multiple recognizers. This is particularly useful since selection handles tend to overlap editable text; a single tap in the overlap region is generally processed by the selection handle, whereas a double tap is processed by the editable text. * `TextSelectionGestureDetectorBuilderDelegate` provides a hook for customizing the interaction model (typically implemented by the text field, e.g., `_CupertinoTextFieldState`, `_TextFieldState`). The delegate also exposes the `GlobalKey` associated with the underlying `EditableTextState`. * `TextSelectionGestureDetectorBuilder` configures a `TextSelectionGestureDetector` with sensible defaults for text editing. The delegate is used to obtain a reference to the editable text and to customize portions of the interaction model. * Platform-specific text fields extend `TextSelectionGestureDetectorBuilder` to provide idiomatic interaction models (e.g., `_TextFieldSelectionGestureDetectorBuilder`). ## How can editable behavior be customized? * `TextInputFormatter` provides a hook to transform text just before `EditableText.onChange` is invoked (i.e., when a change is committed -- not as the user types). Blocklisting, allowlisting, and length-limiting formatters are available (`BlacklistingTextInputFormatter`, `WhitelistingTextInputFormatter`, and `LengthLimitingTextInputFormatter`, respectively). * `TextEditingController` provides a bidirectional interface for interacting with an `EditableText` or subclass thereof; as a `ValueNotifier`, the controller will notify whenever state changes, including as the user types. The text (`TextEditingController.text`), selection (`TextEditingController.selection`), and underlying `TextEditingValue` (`TextEditingController.value`) can be read and written, even in response to notifications. The controller may also be used to produce a `TextSpan`, an immutable span of styled text that can be painted to a layer. ## How is editable text implemented? * `EditableText` is the fundamental text input widget, integrating the other editable building blocks (e.g., `TextSelectionControls`, `TextSelectionOverlay`, etc.) with keyboard interaction (via `TextInput`), scrolling (via `Scrollable`), and text rendering to implement a basic input field. `EditableText` also supports basic gestures (tapping, long pressing, force pressing) for cursor and selection management and `IME` interaction. A variety of properties allow editing behavior and text appearance to be customized, though the actual work is performed by `EditableTextState`. When `EditableText` receives focus but is not fully visible, it will be scrolled into view (via `RenderObject.showOnScreen`). * The resulting text is styled and structured (via `TextStyle` and `StrutStyle`), aligned (via `TextAlign`), and localized (via `TextDirection` and `Locale`). `EditableText` also supports a text scale factor. * `EditableText` layout behavior is dependant on the maximum and minimum number of lines (`EditableText.maxLines`, `EditableText.minLines`) and whether expansion is enabled (`EditableText.expands`). * If maximum lines is one (the default), the field will scroll horizontally on one line. * If maximum lines is null, the field will be laid out for the minimum number of lines, and grow vertically. * If maximum lines is greater than one, the field will be laid out for the minimum number of lines, and grow vertically until the maximum number of lines is reached. * If a multiline field reaches its maximum height, it will scroll vertically. * If a field is expanding, it is sized to the incoming constraints. * `EditableText` follows a simple editing flow to allow the application to react to text changes and handle keyboard actions (via `EditableTextState._finalizeEditing`). * `EditableText.onChanged` is invoked as the field’s contents are changed (i.e., as characters are explicitly typed). * `EditableText.onEditingComplete` (by default) submits changes, clearing the controller’s composing bit, and relinquishes focus. If a non-completion action was selected (e.g., “next”), focus is retained to allow the submit handler to manage focus itself. A custom handler can be provided to alter the latter behavior. * `EditableText.onSubmitted` is invoked last, when the user has indicated that editing is complete (e.g., by hitting “done”). * `EditableTextState` applies the configuration described by `EditableText` to implement a text field; it also manages the flow of information with the platform `TextInput` service. Additionally, the state object exposes a simplified, top-level interface for interacting with editable text. The editing value can be updated (via `EditableTextState.updateEditingValue`), the toolbar toggled (via `EditableTextState.toggleToolbar`), the `IME` displayed (via `EditableTextState.requestKeyboard`), editing actions performed (via `EditableTextState.performAction`), text scrolled into view (via `EditableText.bringIntoView`) and prepared for rendering (via `EditableText.buildTextSpan`). In this respect, `EditableTextState` is the glue binding many of the editing components together. * Is a: `TextInputClient`, `TextSelectionDelegate` * Breakdown how it is updated by the client / notifies the client of changes to keep things in sync * `updateEditingValue` is invoked by the client when user types on keyboard (same for `performAction` / `floatingCursor`). * `EditableTextState` participates in the keep alive protocol (via `AutomaticKeepAliveClientMixin`) to ensure that it isn’t prematurely destroyed, losing editing state (e.g., when scrolled out of view). * * When text is specified programmatically (via `EditableTextState.textEditingValue`, `EditableTextState.updateEditingValue`), the underlying `TextInput` service must be notified so that platform state remains in sync (applying any text formatters beforehand). `EditableTextState._didChangeTextEditingValue` * `RenderEditable` ## How are platform-specific text fields implemented? * `TextField` * `TextFieldState` * `CupertinoTextField` ## How is the toolbar rendered? * The toolbar UI is built by `TextSelectionControls.buildToolbar` using the line height, a bounding rectangle for the input (in global, logical coordinates), an anchor position and, if necessary, a tuple of `TextSelectionPoints`. * `EditableText` triggers on gesture, overlay does the work ## How are selection handles rendered? * Selection handles are visual handles rendered just before and just after a selection. Handles need not be symmetric; `TextSelectionHandleType` characterizes which variation of the handle is to be rendered (left, right, or collapsed). * Each handle is built by `TextSelectionControls.buildHandle` which requires a type and a line height. * The handle’s size is computed by `TextSelectionControls.getHandleSize`, typically using the associated render editable’s line height (`RenderEditable.preferredLineHeight`), which is derived from the text painter’s line height (`TextPainter.preferredLineHeight`). The painter calculates this height through direct measurement. * The handle’s anchor point is computed by `TextSelectionControls.getHandleAnchor` using the type of handle being rendered and the associated render editable’s line height, as above. * `EditableText` triggers on select / cursor position, overlay does the work * `EditableText` uses the handle’s size and anchor to ensure that selection handles are fully visible on screen (via `RenderObject.showOnScreen`). ## How does the editable retain state in response to platform lifecycle events? ## What is the best way to manage input via forms? ## `IME` (input method editor)?