firka/flutter
firka/flutter
5
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improvements to EditableText documentation (#132532)

Browse Source
This commit is contained in:
Ian Hickson 2023-08-16 18:02:17 -07:00 committed by GitHub
parent b66878a61e
commit 8864395034
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 67 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
packages/flutter/lib/src/rendering/editable.dart
View File

@ -878,7 +878,9 @@ class RenderEditable extends RenderBox with RelayoutWhenSystemFontsChangeMixin,
/// The color to use when painting the cursor aligned to the text while
/// rendering the floating cursor.
///
/// The default is light grey.
/// Typically this would be set to [CupertinoColors.inactiveGray].
///
/// If this is null, the background cursor is not painted.
Color? get backgroundCursorColor => _caretPainter.backgroundCursorColor;
set backgroundCursorColor(Color? value) {
_caretPainter.backgroundCursorColor = value;
@ -2645,8 +2647,8 @@ class _RenderEditableCustomPaint extends RenderBox {
/// when only auxiliary content changes (e.g. a blinking cursor) are present. It
/// will be scheduled to repaint when:
///
/// * It's assigned to a new [RenderEditable] and the [shouldRepaint] method
/// returns true.
/// * It's assigned to a new [RenderEditable] (replacing a prior
/// [RenderEditablePainter]) and the [shouldRepaint] method returns true.
/// * Any of the [RenderEditable]s it is attached to repaints.
/// * The [notifyListeners] method is called, which typically happens when the
/// painter's attributes change.
@ -2657,9 +2659,8 @@ class _RenderEditableCustomPaint extends RenderBox {
/// and sets it as the foreground painter of the [RenderEditable].
/// * [RenderEditable.painter], which takes a [RenderEditablePainter]
/// and sets it as the background painter of the [RenderEditable].
/// * [CustomPainter] a similar class which paints within a [RenderCustomPaint].
/// * [CustomPainter], a similar class which paints within a [RenderCustomPaint].
abstract class RenderEditablePainter extends ChangeNotifier {
/// Determines whether repaint is needed when a new [RenderEditablePainter]
/// is provided to a [RenderEditable].
///
@ -2795,6 +2796,11 @@ class _CaretPainter extends RenderEditablePainter {
notifyListeners();
}
// This is directly manipulated by the RenderEditable during
// setFloatingCursor.
//
// When changing this value, the caller is responsible for ensuring that
// listeners are notified.
bool showRegularCaret = false;
final Paint caretPaint = Paint();

61
packages/flutter/lib/src/widgets/editable_text.dart
View File

@ -206,7 +206,7 @@ class TextEditingController extends ValueNotifier<TextEditingValue> {
value == null || !value.composing.isValid || value.isComposingRangeValid,
'New TextEditingValue $value has an invalid non-empty composing range '
'${value.composing}. It is recommended to use a valid composing range, '
'even for readonly text fields',
'even for readonly text fields.',
),
super(value ?? TextEditingValue.empty);
@ -235,7 +235,7 @@ class TextEditingController extends ValueNotifier<TextEditingValue> {
!newValue.composing.isValid || newValue.isComposingRangeValid,
'New TextEditingValue $newValue has an invalid non-empty composing range '
'${newValue.composing}. It is recommended to use a valid composing range, '
'even for readonly text fields',
'even for readonly text fields.',
);
super.value = newValue;
}
@ -547,8 +547,11 @@ class _DiscreteKeyFrameSimulation extends Simulation {
///
/// This widget interacts with the [TextInput] service to let the user edit the
/// text it contains. It also provides scrolling, selection, and cursor
/// movement. This widget does not provide any focus management (e.g.,
/// tap-to-focus).
/// movement.
///
/// The [EditableText] widget is a low-level widget that is intended as a
/// building block for custom widget sets. For a complete user experience,
/// consider using a [TextField] or [CupertinoTextField].
///
/// ## Handling User Input
///
@ -662,13 +665,14 @@ class _DiscreteKeyFrameSimulation extends Simulation {
///
/// ## Gesture Events Handling
///
/// This widget provides rudimentary, platform-agnostic gesture handling for
/// user actions such as tapping, long-pressing and scrolling when
/// [rendererIgnoresPointer] is false (false by default). To tightly conform
/// to the platform behavior with respect to input gestures in text fields, use
/// [TextField] or [CupertinoTextField]. For custom selection behavior, call
/// methods such as [RenderEditable.selectPosition],
/// [RenderEditable.selectWord], etc. programmatically.
/// When [rendererIgnoresPointer] is false (the default), this widget provides
/// rudimentary, platform-agnostic gesture handling for user actions such as
/// tapping, long-pressing, and scrolling.
///
/// To provide more complete gesture handling, including double-click to select
/// a word, drag selection, and platform-specific handling of gestures such as
/// long presses, consider setting [rendererIgnoresPointer] to true and using
/// [TextSelectionGestureDetectorBuilder].
///
/// {@template flutter.widgets.editableText.showCaretOnScreen}
/// ## Keep the caret visible when focused
@ -696,7 +700,7 @@ class _DiscreteKeyFrameSimulation extends Simulation {
/// a currency value text field. The following example demonstrates how to
/// suppress the default accessibility announcements by always announcing
/// the content of the text field as a US currency value (the `\$` inserts
/// a dollar sign, the `$newText interpolates the `newText` variable):
/// a dollar sign, the `$newText` interpolates the `newText` variable):
///
/// ```dart
/// onChanged: (String newText) {
@ -726,14 +730,6 @@ class EditableText extends StatefulWidget {
///
/// The text cursor is not shown if [showCursor] is false or if [showCursor]
/// is null (the default) and [readOnly] is true.
///
/// The [controller], [focusNode], [obscureText], [autocorrect], [autofocus],
/// [showSelectionHandles], [enableInteractiveSelection], [forceLine],
/// [style], [cursorColor], [cursorOpacityAnimates], [backgroundCursorColor],
/// [enableSuggestions], [paintCursorAboveText], [selectionHeightStyle],
/// [selectionWidthStyle], [textAlign], [dragStartBehavior], [scrollPadding],
/// [dragStartBehavior], [toolbarOptions], [rendererIgnoresPointer],
/// [readOnly], and [enableIMEPersonalizedLearning] arguments must not be null.
EditableText({
super.key,
required this.controller,
@ -1101,8 +1097,7 @@ class EditableText extends StatefulWidget {
/// The color to use when painting the background cursor aligned with the text
/// while rendering the floating cursor.
///
/// Cannot be null. By default it is the disabled grey color from
/// CupertinoColors.
/// Typically this would be set to [CupertinoColors.inactiveGray].
final Color backgroundCursorColor;
/// {@template flutter.widgets.editableText.maxLines}
@ -1473,10 +1468,28 @@ class EditableText extends StatefulWidget {
/// the editing position.
final MouseCursor? mouseCursor;
/// If true, the [RenderEditable] created by this widget will not handle
/// pointer events, see [RenderEditable] and [RenderEditable.ignorePointer].
/// Whether the caller will provide gesture handling (true), or if the
/// [EditableText] is expected to handle basic gestures (false).
///
/// When this is false, the [EditableText] (or more specifically, the
/// [RenderEditable]) enables some rudimentary gestures (tap to position the
/// cursor, long-press to select all, and some scrolling behavior).
///
/// These behaviors are sufficient for debugging purposes but are inadequate
/// for user-facing applications. To enable platform-specific behaviors, use a
/// [TextSelectionGestureDetectorBuilder] to wrap the [EditableText], and set
/// [rendererIgnoresPointer] to true.
///
/// When [rendererIgnoresPointer] is true true, the [RenderEditable] created
/// by this widget will not handle pointer events.
///
/// This property is false by default.
///
/// See also:
///
/// * [RenderEditable.ignorePointer], which implements this feature.
/// * [TextSelectionGestureDetectorBuilder], which implements platform-specific
/// gestures and behaviors.
final bool rendererIgnoresPointer;
/// {@template flutter.widgets.editableText.cursorWidth}

28
packages/flutter/lib/src/widgets/text_selection.dart
View File

@ -1871,12 +1871,13 @@ class _SelectionHandleOverlayState extends State<_SelectionHandleOverlay> with S
/// Delegate interface for the [TextSelectionGestureDetectorBuilder].
///
/// The interface is usually implemented by text field implementations wrapping
/// [EditableText], that use a [TextSelectionGestureDetectorBuilder] to build a
/// [TextSelectionGestureDetector] for their [EditableText]. The delegate provides
/// the builder with information about the current state of the text field.
/// Based on these information, the builder adds the correct gesture handlers
/// to the gesture detector.
/// The interface is usually implemented by the [State] of text field
/// implementations wrapping [EditableText], so that they can use a
/// [TextSelectionGestureDetectorBuilder] to build a
/// [TextSelectionGestureDetector] for their [EditableText]. The delegate
/// provides the builder with information about the current state of the text
/// field. Based on that information, the builder adds the correct gesture
/// handlers to the gesture detector.
///
/// See also:
///
@ -1907,6 +1908,12 @@ abstract class TextSelectionGestureDetectorBuilderDelegate {
/// The resulting [TextSelectionGestureDetector] to wrap an [EditableText] is
/// obtained by calling [buildGestureDetector].
///
/// A [TextSelectionGestureDetectorBuilder] must be provided a
/// [TextSelectionGestureDetectorBuilderDelegate], from which information about
/// the [EditableText] may be obtained. Typically, the [State] of the widget
/// that builds the [EditableText] implements this interface, and then passes
/// itself as the [delegate].
///
/// See also:
///
/// * [TextField], which uses a subclass to implement the Material-specific
@ -1915,8 +1922,6 @@ abstract class TextSelectionGestureDetectorBuilderDelegate {
/// Cupertino-specific gesture logic of an [EditableText].
class TextSelectionGestureDetectorBuilder {
/// Creates a [TextSelectionGestureDetectorBuilder].
///
/// The [delegate] must not be null.
TextSelectionGestureDetectorBuilder({
required this.delegate,
});
@ -1926,6 +1931,9 @@ class TextSelectionGestureDetectorBuilder {
/// The delegate provides the builder with information about what actions can
/// currently be performed on the text field. Based on this, the builder adds
/// the correct gesture handlers to the gesture detector.
///
/// Typically implemented by a [State] of a widget that builds an
/// [EditableText].
@protected
final TextSelectionGestureDetectorBuilderDelegate delegate;
@ -2971,7 +2979,9 @@ class TextSelectionGestureDetectorBuilder {
/// Returns a [TextSelectionGestureDetector] configured with the handlers
/// provided by this builder.
///
/// The [child] or its subtree should contain [EditableText].
/// The [child] or its subtree should contain an [EditableText] whose key is
/// the [GlobalKey] provided by the [delegate]'s
/// [TextSelectionGestureDetectorBuilderDelegate.editableTextKey].
Widget buildGestureDetector({
Key? key,
HitTestBehavior? behavior,