text_field.dart 40.3 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
Ian Hickson's avatar
Ian Hickson committed
4

5 6
import 'dart:ui' as ui show BoxHeightStyle, BoxWidthStyle;

7
import 'package:flutter/gestures.dart';
8 9 10 11 12 13 14
import 'package:flutter/rendering.dart';
import 'package:flutter/services.dart';
import 'package:flutter/widgets.dart';

import 'colors.dart';
import 'icons.dart';
import 'text_selection.dart';
xster's avatar
xster committed
15
import 'theme.dart';
16

17
export 'package:flutter/services.dart' show TextInputType, TextInputAction, TextCapitalization, SmartQuotesType, SmartDashesType;
18

19
// Value inspected from Xcode 11 & iOS 13.0 Simulator.
20
const BorderSide _kDefaultRoundedBorderSide = BorderSide(
21 22 23 24
  color: CupertinoDynamicColor.withBrightness(
    color: Color(0x33000000),
    darkColor: Color(0x33FFFFFF),
  ),
25 26 27 28 29 30 31 32 33
  style: BorderStyle.solid,
  width: 0.0,
);
const Border _kDefaultRoundedBorder = Border(
  top: _kDefaultRoundedBorderSide,
  bottom: _kDefaultRoundedBorderSide,
  left: _kDefaultRoundedBorderSide,
  right: _kDefaultRoundedBorderSide,
);
34

35
const BoxDecoration _kDefaultRoundedBorderDecoration = BoxDecoration(
36 37 38 39
  color: CupertinoDynamicColor.withBrightness(
    color: CupertinoColors.white,
    darkColor: CupertinoColors.black,
  ),
40
  border: _kDefaultRoundedBorder,
41 42 43 44 45 46
  borderRadius: BorderRadius.all(Radius.circular(5.0)),
);

const Color _kDisabledBackground = CupertinoDynamicColor.withBrightness(
  color: Color(0xFFFAFAFA),
  darkColor: Color(0xFF050505),
47 48
);

49 50 51 52 53 54
// Value inspected from Xcode 11 & iOS 13.0 Simulator.
// Note it may not be consistent with https://developer.apple.com/design/resources/.
const CupertinoDynamicColor _kClearButtonColor = CupertinoDynamicColor.withBrightness(
  color: Color(0xFF636366),
  darkColor: Color(0xFFAEAEB2),
);
55

56 57 58 59 60 61 62 63
// An eyeballed value that moves the cursor slightly left of where it is
// rendered for text on Android so it's positioning more accurately matches the
// native iOS text cursor positioning.
//
// This value is in device pixels, not logical pixels as is typically used
// throughout the codebase.
const int _iOSHorizontalCursorOffsetPixels = -2;

64 65 66 67 68 69 70 71 72 73
/// Visibility of text field overlays based on the state of the current text entry.
///
/// Used to toggle the visibility behavior of the optional decorating widgets
/// surrounding the [EditableText] such as the clear text button.
enum OverlayVisibilityMode {
  /// Overlay will never appear regardless of the text entry state.
  never,

  /// Overlay will only appear when the current text entry is not empty.
  ///
74
  /// This includes prefilled text that the user did not type in manually. But
75 76 77 78 79
  /// does not include text in placeholders.
  editing,

  /// Overlay will only appear when the current text entry is empty.
  ///
80
  /// This also includes not having prefilled text that the user did not type
81 82 83 84 85 86 87
  /// in manually. Texts in placeholders are ignored.
  notEditing,

  /// Always show the overlay regardless of the text entry state.
  always,
}

88 89
class _CupertinoTextFieldSelectionGestureDetectorBuilder extends TextSelectionGestureDetectorBuilder {
  _CupertinoTextFieldSelectionGestureDetectorBuilder({
90
    required _CupertinoTextFieldState state,
91 92 93 94 95 96 97 98 99
  }) : _state = state,
       super(delegate: state);

  final _CupertinoTextFieldState _state;

  @override
  void onSingleTapUp(TapUpDetails details) {
    // Because TextSelectionGestureDetector listens to taps that happen on
    // widgets in front of it, tapping the clear button will also trigger
Shi-Hao Hong's avatar
Shi-Hao Hong committed
100
    // this handler. If the clear button widget recognizes the up event,
101 102
    // then do not handle it.
    if (_state._clearGlobalKey.currentContext != null) {
103
      final RenderBox renderBox = _state._clearGlobalKey.currentContext!.findRenderObject() as RenderBox;
104 105 106 107 108 109 110 111
      final Offset localOffset = renderBox.globalToLocal(details.globalPosition);
      if (renderBox.hitTest(BoxHitTestResult(), position: localOffset)) {
        return;
      }
    }
    super.onSingleTapUp(details);
    _state._requestKeyboard();
    if (_state.widget.onTap != null)
112
      _state.widget.onTap!();
113 114 115 116 117 118 119 120
  }

  @override
  void onDragSelectionEnd(DragEndDetails details) {
    _state._requestKeyboard();
  }
}

121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
/// An iOS-style text field.
///
/// A text field lets the user enter text, either with a hardware keyboard or with
/// an onscreen keyboard.
///
/// This widget corresponds to both a `UITextField` and an editable `UITextView`
/// on iOS.
///
/// The text field calls the [onChanged] callback whenever the user changes the
/// text in the field. If the user indicates that they are done typing in the
/// field (e.g., by pressing a button on the soft keyboard), the text field
/// calls the [onSubmitted] callback.
///
/// To control the text that is displayed in the text field, use the
/// [controller]. For example, to set the initial value of the text field, use
/// a [controller] that already contains some text such as:
///
138
/// {@tool snippet}
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
///
/// ```dart
/// class MyPrefilledText extends StatefulWidget {
///   @override
///   _MyPrefilledTextState createState() => _MyPrefilledTextState();
/// }
///
/// class _MyPrefilledTextState extends State<MyPrefilledText> {
///   TextEditingController _textController;
///
///   @override
///   void initState() {
///     super.initState();
///     _textController = TextEditingController(text: 'initial text');
///   }
///
///   @override
///   Widget build(BuildContext context) {
///     return CupertinoTextField(controller: _textController);
///   }
/// }
/// ```
161
/// {@end-tool}
162 163 164 165 166 167 168 169
///
/// The [controller] can also control the selection and composing region (and to
/// observe changes to the text, selection, and composing region).
///
/// The text field has an overridable [decoration] that, by default, draws a
/// rounded rectangle border around the text field. If you set the [decoration]
/// property to null, the decoration will be removed entirely.
///
Dan Field's avatar
Dan Field committed
170 171
/// Remember to call [TextEditingController.dispose] when it is no longer
/// needed. This will ensure we discard any resources used by the object.
172
///
173 174 175 176 177 178 179
/// See also:
///
///  * <https://developer.apple.com/documentation/uikit/uitextfield>
///  * [TextField], an alternative text field widget that follows the Material
///    Design UI conventions.
///  * [EditableText], which is the raw text editing control at the heart of a
///    [TextField].
180
///  * Learn how to use a [TextEditingController] in one of our [cookbook recipes](https://flutter.dev/docs/cookbook/forms/text-field-changes#2-use-a-texteditingcontroller).
181 182 183
class CupertinoTextField extends StatefulWidget {
  /// Creates an iOS-style text field.
  ///
184
  /// To provide a prefilled text entry, pass in a [TextEditingController] with
185 186 187 188 189 190 191 192 193 194 195
  /// an initial value to the [controller] parameter.
  ///
  /// To provide a hint placeholder text that appears when the text entry is
  /// empty, pass a [String] to the [placeholder] parameter.
  ///
  /// The [maxLines] property can be set to null to remove the restriction on
  /// the number of lines. In this mode, the intrinsic height of the widget will
  /// grow as the number of lines of text grows. By default, it is `1`, meaning
  /// this is a single-line text field and will scroll horizontally when
  /// overflown. [maxLines] must not be zero.
  ///
196 197 198
  /// The text cursor is not shown if [showCursor] is false or if [showCursor]
  /// is null (the default) and [readOnly] is true.
  ///
199 200
  /// If specified, the [maxLength] property must be greater than zero.
  ///
201 202 203 204 205
  /// The [selectionHeightStyle] and [selectionWidthStyle] properties allow
  /// changing the shape of the selection highlighting. These properties default
  /// to [ui.BoxHeightStyle.tight] and [ui.BoxWidthStyle.tight] respectively and
  /// must not be null.
  ///
206 207
  /// The [autocorrect], [autofocus], [clearButtonMode], [dragStartBehavior],
  /// [expands], [maxLengthEnforced], [obscureText], [prefixMode], [readOnly],
208 209
  /// [scrollPadding], [suffixMode], [textAlign], [selectionHeightStyle],
  /// [selectionWidthStyle], and [enableSuggestions] properties must not be null.
210
  ///
211 212
  /// See also:
  ///
213 214
  ///  * [minLines], which is the minimum number of lines to occupy when the
  ///    content spans fewer lines.
215
  ///  * [expands], to allow the widget to size itself to its parent's height.
216 217 218
  ///  * [maxLength], which discusses the precise meaning of "number of
  ///    characters" and how it may differ from the intuitive meaning.
  const CupertinoTextField({
219
    Key? key,
220 221 222 223 224
    this.controller,
    this.focusNode,
    this.decoration = _kDefaultRoundedBorderDecoration,
    this.padding = const EdgeInsets.all(6.0),
    this.placeholder,
225
    this.placeholderStyle = const TextStyle(
226 227
      fontWeight: FontWeight.w400,
      color: CupertinoColors.placeholderText,
228
    ),
229 230 231 232 233
    this.prefix,
    this.prefixMode = OverlayVisibilityMode.always,
    this.suffix,
    this.suffixMode = OverlayVisibilityMode.always,
    this.clearButtonMode = OverlayVisibilityMode.never,
234
    TextInputType? keyboardType,
235 236
    this.textInputAction,
    this.textCapitalization = TextCapitalization.none,
xster's avatar
xster committed
237
    this.style,
238
    this.strutStyle,
239
    this.textAlign = TextAlign.start,
240
    this.textAlignVertical,
241
    this.readOnly = false,
242
    ToolbarOptions? toolbarOptions,
243
    this.showCursor,
244
    this.autofocus = false,
245
    this.obscuringCharacter = '•',
246 247
    this.obscureText = false,
    this.autocorrect = true,
248 249
    SmartDashesType? smartDashesType,
    SmartQuotesType? smartQuotesType,
250
    this.enableSuggestions = true,
251
    this.maxLines = 1,
252 253
    this.minLines,
    this.expands = false,
254 255 256 257 258 259 260 261
    this.maxLength,
    this.maxLengthEnforced = true,
    this.onChanged,
    this.onEditingComplete,
    this.onSubmitted,
    this.inputFormatters,
    this.enabled,
    this.cursorWidth = 2.0,
262
    this.cursorHeight,
263
    this.cursorRadius = const Radius.circular(2.0),
264
    this.cursorColor,
265 266
    this.selectionHeightStyle = ui.BoxHeightStyle.tight,
    this.selectionWidthStyle = ui.BoxWidthStyle.tight,
267 268
    this.keyboardAppearance,
    this.scrollPadding = const EdgeInsets.all(20.0),
269
    this.dragStartBehavior = DragStartBehavior.start,
270
    this.enableInteractiveSelection = true,
271
    this.onTap,
272
    this.scrollController,
273
    this.scrollPhysics,
274
    this.autofillHints,
275
    this.restorationId,
276
  }) : assert(textAlign != null),
277
       assert(readOnly != null),
278
       assert(autofocus != null),
279 280
       // TODO(a14n): uncomment when issue is fixed, https://github.com/dart-lang/sdk/issues/43407
       assert(obscuringCharacter != null/* && obscuringCharacter.length == 1*/),
281 282
       assert(obscureText != null),
       assert(autocorrect != null),
283 284
       smartDashesType = smartDashesType ?? (obscureText ? SmartDashesType.disabled : SmartDashesType.enabled),
       smartQuotesType = smartQuotesType ?? (obscureText ? SmartQuotesType.disabled : SmartQuotesType.enabled),
285
       assert(enableSuggestions != null),
286 287
       assert(maxLengthEnforced != null),
       assert(scrollPadding != null),
288
       assert(dragStartBehavior != null),
289 290
       assert(selectionHeightStyle != null),
       assert(selectionWidthStyle != null),
291
       assert(maxLines == null || maxLines > 0),
292 293 294
       assert(minLines == null || minLines > 0),
       assert(
         (maxLines == null) || (minLines == null) || (maxLines >= minLines),
295
         "minLines can't be greater than maxLines",
296 297 298 299 300 301
       ),
       assert(expands != null),
       assert(
         !expands || (maxLines == null && minLines == null),
         'minLines and maxLines must be null when expands is true.',
       ),
302
       assert(!obscureText || maxLines == 1, 'Obscured fields cannot be multiline.'),
303 304 305 306
       assert(maxLength == null || maxLength > 0),
       assert(clearButtonMode != null),
       assert(prefixMode != null),
       assert(suffixMode != null),
307 308 309 310 311
       // Assert the following instead of setting it directly to avoid surprising the user by silently changing the value they set.
       assert(!identical(textInputAction, TextInputAction.newline) ||
         maxLines == 1 ||
         !identical(keyboardType, TextInputType.text),
         'Use keyboardType TextInputType.multiline when using TextInputAction.newline on a multiline TextField.'),
312
       keyboardType = keyboardType ?? (maxLines == 1 ? TextInputType.text : TextInputType.multiline),
313
       toolbarOptions = toolbarOptions ?? (obscureText ?
314 315 316 317 318 319 320 321 322
         const ToolbarOptions(
           selectAll: true,
           paste: true,
         ) :
         const ToolbarOptions(
           copy: true,
           cut: true,
           selectAll: true,
           paste: true,
323
         )),
324 325 326 327 328
       super(key: key);

  /// Controls the text being edited.
  ///
  /// If null, this widget will create its own [TextEditingController].
329
  final TextEditingController? controller;
330

331
  /// {@macro flutter.widgets.Focus.focusNode}
332
  final FocusNode? focusNode;
333 334 335 336 337

  /// Controls the [BoxDecoration] of the box behind the text input.
  ///
  /// Defaults to having a rounded rectangle grey border and can be null to have
  /// no box decoration.
338
  final BoxDecoration? decoration;
339 340 341 342 343 344 345 346 347 348 349 350 351 352

  /// Padding around the text entry area between the [prefix] and [suffix]
  /// or the clear button when [clearButtonMode] is not never.
  ///
  /// Defaults to a padding of 6 pixels on all sides and can be null.
  final EdgeInsetsGeometry padding;

  /// A lighter colored placeholder hint that appears on the first line of the
  /// text field when the text entry is empty.
  ///
  /// Defaults to having no placeholder text.
  ///
  /// The text style of the placeholder text matches that of the text field's
  /// main text entry except a lighter font weight and a grey font color.
353
  final String? placeholder;
354

355 356 357 358 359 360 361 362 363
  /// The style to use for the placeholder text.
  ///
  /// The [placeholderStyle] is merged with the [style] [TextStyle] when applied
  /// to the [placeholder] text. To avoid merging with [style], specify
  /// [TextStyle.inherit] as false.
  ///
  /// Defaults to the [style] property with w300 font weight and grey color.
  ///
  /// If specifically set to null, placeholder's style will be the same as [style].
364
  final TextStyle? placeholderStyle;
365

366
  /// An optional [Widget] to display before the text.
367
  final Widget? prefix;
368 369 370 371 372 373 374 375 376 377

  /// Controls the visibility of the [prefix] widget based on the state of
  /// text entry when the [prefix] argument is not null.
  ///
  /// Defaults to [OverlayVisibilityMode.always] and cannot be null.
  ///
  /// Has no effect when [prefix] is null.
  final OverlayVisibilityMode prefixMode;

  /// An optional [Widget] to display after the text.
378
  final Widget? suffix;
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404

  /// Controls the visibility of the [suffix] widget based on the state of
  /// text entry when the [suffix] argument is not null.
  ///
  /// Defaults to [OverlayVisibilityMode.always] and cannot be null.
  ///
  /// Has no effect when [suffix] is null.
  final OverlayVisibilityMode suffixMode;

  /// Show an iOS-style clear button to clear the current text entry.
  ///
  /// Can be made to appear depending on various text states of the
  /// [TextEditingController].
  ///
  /// Will only appear if no [suffix] widget is appearing.
  ///
  /// Defaults to never appearing and cannot be null.
  final OverlayVisibilityMode clearButtonMode;

  /// {@macro flutter.widgets.editableText.keyboardType}
  final TextInputType keyboardType;

  /// The type of action button to use for the keyboard.
  ///
  /// Defaults to [TextInputAction.newline] if [keyboardType] is
  /// [TextInputType.multiline] and [TextInputAction.done] otherwise.
405
  final TextInputAction? textInputAction;
406 407 408 409 410 411 412 413

  /// {@macro flutter.widgets.editableText.textCapitalization}
  final TextCapitalization textCapitalization;

  /// The style to use for the text being edited.
  ///
  /// Also serves as a base for the [placeholder] text's style.
  ///
xster's avatar
xster committed
414
  /// Defaults to the standard iOS font style from [CupertinoTheme] if null.
415
  final TextStyle? style;
416

417
  /// {@macro flutter.widgets.editableText.strutStyle}
418
  final StrutStyle? strutStyle;
419

420 421 422
  /// {@macro flutter.widgets.editableText.textAlign}
  final TextAlign textAlign;

423 424 425 426 427 428 429
  /// Configuration of toolbar options.
  ///
  /// If not set, select all and paste will default to be enabled. Copy and cut
  /// will be disabled if [obscureText] is true. If [readOnly] is true,
  /// paste and cut will be disabled regardless.
  final ToolbarOptions toolbarOptions;

Dan Field's avatar
Dan Field committed
430
  /// {@macro flutter.widgets.inputDecorator.textAlignVertical}
431
  final TextAlignVertical? textAlignVertical;
432

433 434 435 436
  /// {@macro flutter.widgets.editableText.readOnly}
  final bool readOnly;

  /// {@macro flutter.widgets.editableText.showCursor}
437
  final bool? showCursor;
438

439 440 441
  /// {@macro flutter.widgets.editableText.autofocus}
  final bool autofocus;

442 443 444
  /// {@macro flutter.widgets.editableText.obscuringCharacter}
  final String obscuringCharacter;

445 446 447 448 449 450
  /// {@macro flutter.widgets.editableText.obscureText}
  final bool obscureText;

  /// {@macro flutter.widgets.editableText.autocorrect}
  final bool autocorrect;

451 452 453 454 455 456
  /// {@macro flutter.services.textInput.smartDashesType}
  final SmartDashesType smartDashesType;

  /// {@macro flutter.services.textInput.smartQuotesType}
  final SmartQuotesType smartQuotesType;

457 458 459
  /// {@macro flutter.services.textInput.enableSuggestions}
  final bool enableSuggestions;

460
  /// {@macro flutter.widgets.editableText.maxLines}
461
  final int? maxLines;
462

463
  /// {@macro flutter.widgets.editableText.minLines}
464
  final int? minLines;
465 466 467 468

  /// {@macro flutter.widgets.editableText.expands}
  final bool expands;

469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510
  /// The maximum number of characters (Unicode scalar values) to allow in the
  /// text field.
  ///
  /// If set, a character counter will be displayed below the
  /// field, showing how many characters have been entered and how many are
  /// allowed. After [maxLength] characters have been input, additional input
  /// is ignored, unless [maxLengthEnforced] is set to false. The TextField
  /// enforces the length with a [LengthLimitingTextInputFormatter], which is
  /// evaluated after the supplied [inputFormatters], if any.
  ///
  /// This value must be either null or greater than zero. If set to null
  /// (the default), there is no limit to the number of characters allowed.
  ///
  /// Whitespace characters (e.g. newline, space, tab) are included in the
  /// character count.
  ///
  /// ## Limitations
  ///
  /// The CupertinoTextField does not currently count Unicode grapheme clusters
  /// (i.e. characters visible to the user), it counts Unicode scalar values,
  /// which leaves out a number of useful possible characters (like many emoji
  /// and composed characters), so this will be inaccurate in the presence of
  /// those characters. If you expect to encounter these kinds of characters, be
  /// generous in the maxLength used.
  ///
  /// For instance, the character "ö" can be represented as '\u{006F}\u{0308}',
  /// which is the letter "o" followed by a composed diaeresis "¨", or it can
  /// be represented as '\u{00F6}', which is the Unicode scalar value "LATIN
  /// SMALL LETTER O WITH DIAERESIS". In the first case, the text field will
  /// count two characters, and the second case will be counted as one
  /// character, even though the user can see no difference in the input.
  ///
  /// Similarly, some emoji are represented by multiple scalar values. The
  /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "👍🏽", should be
  /// counted as a single character, but because it is a combination of two
  /// Unicode scalar values, '\u{1F44D}\u{1F3FD}', it is counted as two
  /// characters.
  ///
  /// See also:
  ///
  ///  * [LengthLimitingTextInputFormatter] for more information on how it
  ///    counts characters, and how it may differ from the intuitive meaning.
511
  final int? maxLength;
512 513 514 515 516 517 518 519 520 521

  /// If true, prevents the field from allowing more than [maxLength]
  /// characters.
  ///
  /// If [maxLength] is set, [maxLengthEnforced] indicates whether or not to
  /// enforce the limit, or merely provide a character counter and warning when
  /// [maxLength] is exceeded.
  final bool maxLengthEnforced;

  /// {@macro flutter.widgets.editableText.onChanged}
522
  final ValueChanged<String>? onChanged;
523 524

  /// {@macro flutter.widgets.editableText.onEditingComplete}
525
  final VoidCallback? onEditingComplete;
526 527

  /// {@macro flutter.widgets.editableText.onSubmitted}
528 529 530 531 532 533
  ///
  /// See also:
  ///
  ///  * [EditableText.onSubmitted] for an example of how to handle moving to
  ///    the next/previous field when using [TextInputAction.next] and
  ///    [TextInputAction.previous] for [textInputAction].
534
  final ValueChanged<String>? onSubmitted;
535 536

  /// {@macro flutter.widgets.editableText.inputFormatters}
537
  final List<TextInputFormatter>? inputFormatters;
538 539 540 541 542 543

  /// Disables the text field when false.
  ///
  /// Text fields in disabled states have a light grey background and don't
  /// respond to touch events including the [prefix], [suffix] and the clear
  /// button.
544
  final bool? enabled;
545 546 547 548

  /// {@macro flutter.widgets.editableText.cursorWidth}
  final double cursorWidth;

549
  /// {@macro flutter.widgets.editableText.cursorHeight}
550
  final double? cursorHeight;
551

552 553 554 555 556
  /// {@macro flutter.widgets.editableText.cursorRadius}
  final Radius cursorRadius;

  /// The color to use when painting the cursor.
  ///
557 558 559
  /// Defaults to the [CupertinoThemeData.primaryColor] of the ambient theme,
  /// which itself defaults to [CupertinoColors.activeBlue] in the light theme
  /// and [CupertinoColors.activeOrange] in the dark theme.
560
  final Color? cursorColor;
561

562 563 564 565 566 567 568 569 570 571
  /// Controls how tall the selection highlight boxes are computed to be.
  ///
  /// See [ui.BoxHeightStyle] for details on available styles.
  final ui.BoxHeightStyle selectionHeightStyle;

  /// Controls how wide the selection highlight boxes are computed to be.
  ///
  /// See [ui.BoxWidthStyle] for details on available styles.
  final ui.BoxWidthStyle selectionWidthStyle;

572 573 574 575 576
  /// The appearance of the keyboard.
  ///
  /// This setting is only honored on iOS devices.
  ///
  /// If null, defaults to [Brightness.light].
577
  final Brightness? keyboardAppearance;
578 579 580 581

  /// {@macro flutter.widgets.editableText.scrollPadding}
  final EdgeInsets scrollPadding;

582 583 584
  /// {@macro flutter.widgets.editableText.enableInteractiveSelection}
  final bool enableInteractiveSelection;

585 586 587
  /// {@macro flutter.widgets.scrollable.dragStartBehavior}
  final DragStartBehavior dragStartBehavior;

588
  /// {@macro flutter.widgets.editableText.scrollController}
589
  final ScrollController? scrollController;
590

Dan Field's avatar
Dan Field committed
591
  /// {@macro flutter.widgets.editableText.scrollPhysics}
592
  final ScrollPhysics? scrollPhysics;
593

594
  /// {@macro flutter.widgets.editableText.selectionEnabled}
595
  bool get selectionEnabled => enableInteractiveSelection;
596

597
  /// {@macro flutter.material.textfield.onTap}
598
  final GestureTapCallback? onTap;
599

600
  /// {@macro flutter.widgets.editableText.autofillHints}
601
  /// {@macro flutter.services.autofill.autofillHints}
602
  final Iterable<String>? autofillHints;
603

604
  /// {@macro flutter.material.textfield.restorationId}
605
  final String? restorationId;
606

607 608 609 610 611 612 613 614 615 616 617
  @override
  _CupertinoTextFieldState createState() => _CupertinoTextFieldState();

  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(DiagnosticsProperty<TextEditingController>('controller', controller, defaultValue: null));
    properties.add(DiagnosticsProperty<FocusNode>('focusNode', focusNode, defaultValue: null));
    properties.add(DiagnosticsProperty<BoxDecoration>('decoration', decoration));
    properties.add(DiagnosticsProperty<EdgeInsetsGeometry>('padding', padding));
    properties.add(StringProperty('placeholder', placeholder));
618
    properties.add(DiagnosticsProperty<TextStyle>('placeholderStyle', placeholderStyle));
619 620 621 622 623 624
    properties.add(DiagnosticsProperty<OverlayVisibilityMode>('prefix', prefix == null ? null : prefixMode));
    properties.add(DiagnosticsProperty<OverlayVisibilityMode>('suffix', suffix == null ? null : suffixMode));
    properties.add(DiagnosticsProperty<OverlayVisibilityMode>('clearButtonMode', clearButtonMode));
    properties.add(DiagnosticsProperty<TextInputType>('keyboardType', keyboardType, defaultValue: TextInputType.text));
    properties.add(DiagnosticsProperty<TextStyle>('style', style, defaultValue: null));
    properties.add(DiagnosticsProperty<bool>('autofocus', autofocus, defaultValue: false));
625
    properties.add(DiagnosticsProperty<String>('obscuringCharacter', obscuringCharacter, defaultValue: '•'));
626
    properties.add(DiagnosticsProperty<bool>('obscureText', obscureText, defaultValue: false));
627
    properties.add(DiagnosticsProperty<bool>('autocorrect', autocorrect, defaultValue: true));
628 629
    properties.add(EnumProperty<SmartDashesType>('smartDashesType', smartDashesType, defaultValue: obscureText ? SmartDashesType.disabled : SmartDashesType.enabled));
    properties.add(EnumProperty<SmartQuotesType>('smartQuotesType', smartQuotesType, defaultValue: obscureText ? SmartQuotesType.disabled : SmartQuotesType.enabled));
630
    properties.add(DiagnosticsProperty<bool>('enableSuggestions', enableSuggestions, defaultValue: true));
631
    properties.add(IntProperty('maxLines', maxLines, defaultValue: 1));
632 633
    properties.add(IntProperty('minLines', minLines, defaultValue: null));
    properties.add(DiagnosticsProperty<bool>('expands', expands, defaultValue: false));
634 635
    properties.add(IntProperty('maxLength', maxLength, defaultValue: null));
    properties.add(FlagProperty('maxLengthEnforced', value: maxLengthEnforced, ifTrue: 'max length enforced'));
636 637 638
    properties.add(DoubleProperty('cursorWidth', cursorWidth, defaultValue: 2.0));
    properties.add(DoubleProperty('cursorHeight', cursorHeight, defaultValue: null));
    properties.add(DiagnosticsProperty<Radius>('cursorRadius', cursorRadius, defaultValue: null));
639
    properties.add(createCupertinoColorProperty('cursorColor', cursorColor, defaultValue: null));
640
    properties.add(FlagProperty('selectionEnabled', value: selectionEnabled, defaultValue: true, ifFalse: 'selection disabled'));
641
    properties.add(DiagnosticsProperty<ScrollController>('scrollController', scrollController, defaultValue: null));
642
    properties.add(DiagnosticsProperty<ScrollPhysics>('scrollPhysics', scrollPhysics, defaultValue: null));
643 644
    properties.add(EnumProperty<TextAlign>('textAlign', textAlign, defaultValue: TextAlign.start));
    properties.add(DiagnosticsProperty<TextAlignVertical>('textAlignVertical', textAlignVertical, defaultValue: null));
645 646 647
  }
}

648
class _CupertinoTextFieldState extends State<CupertinoTextField> with RestorationMixin, AutomaticKeepAliveClientMixin<CupertinoTextField> implements TextSelectionGestureDetectorBuilderDelegate {
649
  final GlobalKey _clearGlobalKey = GlobalKey();
650

651 652
  RestorableTextEditingController? _controller;
  TextEditingController get _effectiveController => widget.controller ?? _controller!.value;
653

654
  FocusNode? _focusNode;
655 656
  FocusNode get _effectiveFocusNode => widget.focusNode ?? (_focusNode ??= FocusNode());

657 658
  bool _showSelectionHandles = false;

659
  late _CupertinoTextFieldSelectionGestureDetectorBuilder _selectionGestureDetectorBuilder;
660 661 662 663 664 665 666 667 668 669 670 671

  // API for TextSelectionGestureDetectorBuilderDelegate.
  @override
  bool get forcePressEnabled => true;

  @override
  final GlobalKey<EditableTextState> editableTextKey = GlobalKey<EditableTextState>();

  @override
  bool get selectionEnabled => widget.selectionEnabled;
  // End of API for TextSelectionGestureDetectorBuilderDelegate.

672 673 674
  @override
  void initState() {
    super.initState();
675
    _selectionGestureDetectorBuilder = _CupertinoTextFieldSelectionGestureDetectorBuilder(state: this);
676
    if (widget.controller == null) {
677
      _createLocalController();
678 679 680 681 682 683 684
    }
  }

  @override
  void didUpdateWidget(CupertinoTextField oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.controller == null && oldWidget.controller != null) {
685
      _createLocalController(oldWidget.controller!.value);
686
    } else if (widget.controller != null && oldWidget.controller == null) {
687 688
      unregisterFromRestoration(_controller!);
      _controller!.dispose();
689 690 691 692 693 694 695 696 697
      _controller = null;
    }
    final bool isEnabled = widget.enabled ?? true;
    final bool wasEnabled = oldWidget.enabled ?? true;
    if (wasEnabled && !isEnabled) {
      _effectiveFocusNode.unfocus();
    }
  }

698
  @override
699
  void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
700 701 702 703 704 705 706
    if (_controller != null) {
      _registerController();
    }
  }

  void _registerController() {
    assert(_controller != null);
707 708
    registerForRestoration(_controller!, 'controller');
    _controller!.value.addListener(updateKeepAlive);
709 710
  }

711
  void _createLocalController([TextEditingValue? value]) {
712 713 714 715 716 717 718 719 720 721
    assert(_controller == null);
    _controller = value == null
        ? RestorableTextEditingController()
        : RestorableTextEditingController.fromValue(value);
    if (!restorePending) {
      _registerController();
    }
  }

  @override
722
  String? get restorationId => widget.restorationId;
723

724 725 726
  @override
  void dispose() {
    _focusNode?.dispose();
727
    _controller?.dispose();
728 729 730
    super.dispose();
  }

731
  EditableTextState? get _editableText => editableTextKey.currentState;
732

733
  void _requestKeyboard() {
734
    _editableText?.requestKeyboard();
735 736
  }

737
  bool _shouldShowSelectionHandles(SelectionChangedCause? cause) {
738 739
    // When the text field is activated by something that doesn't trigger the
    // selection overlay, we shouldn't show the handles either.
740
    if (!_selectionGestureDetectorBuilder.shouldShowSelectionToolbar)
741 742 743 744 745 746 747 748 749 750 751 752 753
      return false;

    // On iOS, we don't show handles when the selection is collapsed.
    if (_effectiveController.selection.isCollapsed)
      return false;

    if (cause == SelectionChangedCause.keyboard)
      return false;

    if (_effectiveController.text.isNotEmpty)
      return true;

    return false;
754 755
  }

756
  void _handleSelectionChanged(TextSelection selection, SelectionChangedCause? cause) {
757
    if (cause == SelectionChangedCause.longPress) {
758 759
      _editableText?.bringIntoView(selection.base);
    }
760 761 762 763 764
    final bool willShowSelectionHandles = _shouldShowSelectionHandles(cause);
    if (willShowSelectionHandles != _showSelectionHandles) {
      setState(() {
        _showSelectionHandles = willShowSelectionHandles;
      });
765 766 767
    }
  }

768
  @override
769
  bool get wantKeepAlive => _controller?.value.text.isNotEmpty == true;
770 771

  bool _shouldShowAttachment({
772 773
    required OverlayVisibilityMode attachment,
    required bool hasText,
774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807
  }) {
    switch (attachment) {
      case OverlayVisibilityMode.never:
        return false;
      case OverlayVisibilityMode.always:
        return true;
      case OverlayVisibilityMode.editing:
        return hasText;
      case OverlayVisibilityMode.notEditing:
        return !hasText;
    }
  }

  bool _showPrefixWidget(TextEditingValue text) {
    return widget.prefix != null && _shouldShowAttachment(
      attachment: widget.prefixMode,
      hasText: text.text.isNotEmpty,
    );
  }

  bool _showSuffixWidget(TextEditingValue text) {
    return widget.suffix != null && _shouldShowAttachment(
      attachment: widget.suffixMode,
      hasText: text.text.isNotEmpty,
    );
  }

  bool _showClearButton(TextEditingValue text) {
    return _shouldShowAttachment(
      attachment: widget.clearButtonMode,
      hasText: text.text.isNotEmpty,
    );
  }

808 809 810 811 812 813 814 815 816 817 818 819 820
  // True if any surrounding decoration widgets will be shown.
  bool get _hasDecoration {
    return widget.placeholder != null ||
      widget.clearButtonMode != OverlayVisibilityMode.never ||
      widget.prefix != null ||
      widget.suffix != null;
  }

  // Provide default behavior if widget.textAlignVertical is not set.
  // CupertinoTextField has top alignment by default, unless it has decoration
  // like a prefix or suffix, in which case it's aligned to the center.
  TextAlignVertical get _textAlignVertical {
    if (widget.textAlignVertical != null) {
821
      return widget.textAlignVertical!;
822 823 824 825
    }
    return _hasDecoration ? TextAlignVertical.center : TextAlignVertical.top;
  }

826
  Widget _addTextDependentAttachments(Widget editableText, TextStyle textStyle, TextStyle placeholderStyle) {
xster's avatar
xster committed
827 828
    assert(editableText != null);
    assert(textStyle != null);
829
    assert(placeholderStyle != null);
830 831
    // If there are no surrounding widgets, just return the core editable text
    // part.
832
    if (!_hasDecoration) {
833 834 835 836 837 838 839
      return editableText;
    }

    // Otherwise, listen to the current state of the text entry.
    return ValueListenableBuilder<TextEditingValue>(
      valueListenable: _effectiveController,
      child: editableText,
840
      builder: (BuildContext context, TextEditingValue? text, Widget? child) {
841 842 843
        return Row(children: <Widget>[
          // Insert a prefix at the front if the prefix visibility mode matches
          // the current text state.
844
          if (_showPrefixWidget(text!)) widget.prefix!,
845 846 847 848 849 850 851 852 853 854 855
          // In the middle part, stack the placeholder on top of the main EditableText
          // if needed.
          Expanded(
            child: Stack(
              children: <Widget>[
                if (widget.placeholder != null && text.text.isEmpty)
                  SizedBox(
                    width: double.infinity,
                    child: Padding(
                      padding: widget.padding,
                      child: Text(
856
                        widget.placeholder!,
857 858 859 860 861 862 863
                        maxLines: widget.maxLines,
                        overflow: TextOverflow.ellipsis,
                        style: placeholderStyle,
                        textAlign: widget.textAlign,
                      ),
                    ),
                  ),
864
                child!,
865
              ],
866
            ),
867 868 869
          ),
          // First add the explicit suffix if the suffix visibility mode matches.
          if (_showSuffixWidget(text))
870
            widget.suffix!
871 872
          // Otherwise, try to show a clear button if its visibility mode matches.
          else if (_showClearButton(text))
873
            GestureDetector(
874
              key: _clearGlobalKey,
875 876 877 878 879 880
              onTap: widget.enabled ?? true ? () {
                // Special handle onChanged for ClearButton
                // Also call onChanged when the clear button is tapped.
                final bool textChanged = _effectiveController.text.isNotEmpty;
                _effectiveController.clear();
                if (widget.onChanged != null && textChanged)
881
                  widget.onChanged!(_effectiveController.text);
882
              } : null,
883 884
              child: Padding(
                padding: const EdgeInsets.symmetric(horizontal: 6.0),
885 886 887
                child: Icon(
                  CupertinoIcons.clear_thick_circled,
                  size: 18.0,
888
                  color: CupertinoDynamicColor.resolve(_kClearButtonColor, context),
889 890 891
                ),
              ),
            ),
892
        ]);
893 894 895 896 897 898 899 900 901 902 903
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    super.build(context); // See AutomaticKeepAliveClientMixin.
    assert(debugCheckHasDirectionality(context));
    final TextEditingController controller = _effectiveController;
    final List<TextInputFormatter> formatters = widget.inputFormatters ?? <TextInputFormatter>[];
    final bool enabled = widget.enabled ?? true;
904
    final Offset cursorOffset = Offset(_iOSHorizontalCursorOffsetPixels / MediaQuery.of(context)!.devicePixelRatio, 0);
905 906 907
    if (widget.maxLength != null && widget.maxLengthEnforced) {
      formatters.add(LengthLimitingTextInputFormatter(widget.maxLength));
    }
908
    final CupertinoThemeData themeData = CupertinoTheme.of(context);
909

910
    final TextStyle? resolvedStyle = widget.style?.copyWith(
911 912 913 914 915 916
      color: CupertinoDynamicColor.resolve(widget.style?.color, context),
      backgroundColor: CupertinoDynamicColor.resolve(widget.style?.backgroundColor, context),
    );

    final TextStyle textStyle = themeData.textTheme.textStyle.merge(resolvedStyle);

917
    final TextStyle? resolvedPlaceholderStyle = widget.placeholderStyle?.copyWith(
918 919 920 921 922 923
      color: CupertinoDynamicColor.resolve(widget.placeholderStyle?.color, context),
      backgroundColor: CupertinoDynamicColor.resolve(widget.placeholderStyle?.backgroundColor, context),
    );

    final TextStyle placeholderStyle = textStyle.merge(resolvedPlaceholderStyle);

924
    final Brightness keyboardAppearance = widget.keyboardAppearance ?? CupertinoTheme.brightnessOf(context)!;
925
    final Color cursorColor = CupertinoDynamicColor.resolve(widget.cursorColor, context) ?? themeData.primaryColor;
926
    final Color? disabledColor = CupertinoDynamicColor.resolve(_kDisabledBackground, context);
927

928
    final Color? decorationColor = CupertinoDynamicColor.resolve(widget.decoration?.color, context);
929

930
    final BoxBorder? border = widget.decoration?.border;
931
    Border resolvedBorder = border as Border;
932 933 934 935 936 937 938 939 940 941 942 943 944 945 946
    if (border is Border) {
      BorderSide resolveBorderSide(BorderSide side) {
        return side == BorderSide.none
          ? side
          : side.copyWith(color: CupertinoDynamicColor.resolve(side.color, context));
      }
      resolvedBorder = border == null || border.runtimeType != Border
        ? border
        : Border(
          top: resolveBorderSide(border.top),
          left: resolveBorderSide(border.left),
          bottom: resolveBorderSide(border.bottom),
          right: resolveBorderSide(border.right),
        );
    }
947

948
    final BoxDecoration? effectiveDecoration = widget.decoration?.copyWith(
949 950 951
      border: resolvedBorder,
      color: enabled ? decorationColor : (decorationColor ?? disabledColor),
    );
952

953 954
    final Color selectionColor = CupertinoTheme.of(context).primaryColor.withOpacity(0.2);

955 956 957
    final Widget paddedEditable = Padding(
      padding: widget.padding,
      child: RepaintBoundary(
958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000
        child: UnmanagedRestorationScope(
          bucket: bucket,
          child: EditableText(
            key: editableTextKey,
            controller: controller,
            readOnly: widget.readOnly,
            toolbarOptions: widget.toolbarOptions,
            showCursor: widget.showCursor,
            showSelectionHandles: _showSelectionHandles,
            focusNode: _effectiveFocusNode,
            keyboardType: widget.keyboardType,
            textInputAction: widget.textInputAction,
            textCapitalization: widget.textCapitalization,
            style: textStyle,
            strutStyle: widget.strutStyle,
            textAlign: widget.textAlign,
            autofocus: widget.autofocus,
            obscuringCharacter: widget.obscuringCharacter,
            obscureText: widget.obscureText,
            autocorrect: widget.autocorrect,
            smartDashesType: widget.smartDashesType,
            smartQuotesType: widget.smartQuotesType,
            enableSuggestions: widget.enableSuggestions,
            maxLines: widget.maxLines,
            minLines: widget.minLines,
            expands: widget.expands,
            selectionColor: selectionColor,
            selectionControls: widget.selectionEnabled
              ? cupertinoTextSelectionControls : null,
            onChanged: widget.onChanged,
            onSelectionChanged: _handleSelectionChanged,
            onEditingComplete: widget.onEditingComplete,
            onSubmitted: widget.onSubmitted,
            inputFormatters: formatters,
            rendererIgnoresPointer: true,
            cursorWidth: widget.cursorWidth,
            cursorHeight: widget.cursorHeight,
            cursorRadius: widget.cursorRadius,
            cursorColor: cursorColor,
            cursorOpacityAnimates: true,
            cursorOffset: cursorOffset,
            paintCursorAboveText: true,
            autocorrectionTextRectColor: selectionColor,
1001
            backgroundCursorColor: CupertinoDynamicColor.resolve(CupertinoColors.inactiveGray, context)!,
1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012
            selectionHeightStyle: widget.selectionHeightStyle,
            selectionWidthStyle: widget.selectionWidthStyle,
            scrollPadding: widget.scrollPadding,
            keyboardAppearance: keyboardAppearance,
            dragStartBehavior: widget.dragStartBehavior,
            scrollController: widget.scrollController,
            scrollPhysics: widget.scrollPhysics,
            enableInteractiveSelection: widget.enableInteractiveSelection,
            autofillHints: widget.autofillHints,
            restorationId: 'editable',
          ),
1013 1014 1015 1016 1017
        ),
      ),
    );

    return Semantics(
1018 1019
      enabled: enabled,
      onTap: !enabled ? null : () {
1020 1021 1022 1023 1024 1025 1026 1027
        if (!controller.selection.isValid) {
          controller.selection = TextSelection.collapsed(offset: controller.text.length);
        }
        _requestKeyboard();
      },
      child: IgnorePointer(
        ignoring: !enabled,
        child: Container(
1028
          decoration: effectiveDecoration,
1029
          child: _selectionGestureDetectorBuilder.buildGestureDetector(
1030 1031 1032 1033 1034 1035 1036 1037
            behavior: HitTestBehavior.translucent,
            child: Align(
              alignment: Alignment(-1.0, _textAlignVertical.y),
              widthFactor: 1.0,
              heightFactor: 1.0,
              child: _addTextDependentAttachments(paddedEditable, textStyle, placeholderStyle),
            ),
          ),
1038 1039 1040 1041 1042
        ),
      ),
    );
  }
}