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 [
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.
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.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.buildToolbar), which construct the actual UI. Concrete implementations are provided for
_MaterialTextSelectionControls, respectively), producing idiomatic UI for the corresponding platform. The build process is initiated by
TextSelectionOverlay is the visual engine underpinning selection UI. It integrates
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
The toolbar and selection handles are positioned using leader/follower layers (via
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
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.,
_TextFieldState). The delegate also exposes the
GlobalKey associated with the underlying
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.,
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 (
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
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.
EditableText is the fundamental text input widget, integrating the other editable building blocks (e.g.,
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
EditableText receives focus but is not fully visible, it will be scrolled into view (via
The resulting text is styled and structured (via
StrutStyle), aligned (via
TextAlign), and localized (via
EditableText also supports a text scale factor.
EditableText layout behavior is dependant on the maximum and minimum number of lines (
EditableText.minLines) and whether expansion is enabled (
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
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
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.
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
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.updateEditingValue), the underlying
TextInput service must be notified so that platform state remains in sync (applying any text formatters beforehand).
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
EditableText triggers on gesture, overlay does the work
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