CupertinoSearchTextField constructor

const CupertinoSearchTextField({
  1. Key? key,
  2. TextEditingController? controller,
  3. ValueChanged<String>? onChanged,
  4. ValueChanged<String>? onSubmitted,
  5. TextStyle? style,
  6. String? placeholder,
  7. TextStyle? placeholderStyle,
  8. BoxDecoration? decoration,
  9. Color? backgroundColor,
  10. BorderRadius? borderRadius,
  11. TextInputType? keyboardType = TextInputType.text,
  12. EdgeInsetsGeometry padding = const EdgeInsetsDirectional.fromSTEB(5.5, 8, 5.5, 8),
  13. Color itemColor = CupertinoColors.secondaryLabel,
  14. double itemSize = 20.0,
  15. EdgeInsetsGeometry prefixInsets = const EdgeInsetsDirectional.fromSTEB(6, 0, 0, 3),
  16. Widget prefixIcon = const Icon(CupertinoIcons.search),
  17. EdgeInsetsGeometry suffixInsets = const EdgeInsetsDirectional.fromSTEB(0, 0, 5, 2),
  18. Icon suffixIcon = const Icon(CupertinoIcons.xmark_circle_fill),
  19. OverlayVisibilityMode suffixMode = OverlayVisibilityMode.editing,
  20. VoidCallback? onSuffixTap,
  21. String? restorationId,
  22. FocusNode? focusNode,
  23. SmartQuotesType? smartQuotesType,
  24. SmartDashesType? smartDashesType,
  25. bool enableIMEPersonalizedLearning = true,
  26. bool autofocus = false,
  27. VoidCallback? onTap,
  28. bool autocorrect = true,
  29. bool? enabled,
})

Creates a CupertinoTextField that mimics the look and behavior of UIKit's UISearchTextField.

Similar to CupertinoTextField, to provide a prefilled text entry, pass in a TextEditingController with an initial value to the controller parameter.

The onChanged parameter takes a ValueChanged<String> which is invoked upon a change in the text field's value.

The onSubmitted parameter takes a ValueChanged<String> which is invoked when the keyboard submits.

To provide a hint placeholder text that appears when the text entry is empty, pass a String to the placeholder parameter. This defaults to 'Search'.

The style and placeholderStyle properties allow changing the style of the text and placeholder of the text field. placeholderStyle defaults to the gray CupertinoColors.secondaryLabel iOS color.

To set the text field's background color and border radius, pass a BoxDecoration to the decoration parameter. This defaults to the default translucent tertiarySystemFill iOS color and 9 px corner radius.

The itemColor and itemSize properties allow changing the icon color and icon size of the search icon (prefix) and X-Mark (suffix). They default to CupertinoColors.secondaryLabel and 20.0.

The padding, prefixInsets, and suffixInsets let you set the padding insets for text, the search icon (prefix), and the X-Mark icon (suffix). They default to values that replicate the UISearchTextField look. These default fields were determined using the comparison tool in https://github.com/flutter/platform_tests/.

To customize the prefix icon, pass a Widget to prefixIcon. This defaults to the search icon.

To customize the suffix icon, pass an Icon to suffixIcon. This defaults to the X-Mark.

To dictate when the X-Mark (suffix) should be visible, a.k.a. only on when editing, not editing, on always, or on never, pass a OverlayVisibilityMode to suffixMode. This defaults to only on when editing.

To customize the X-Mark (suffix) action, pass a VoidCallback to onSuffixTap. This defaults to clearing the text.

Implementation

// TODO(DanielEdrisian): Localize the 'Search' placeholder.
///
/// The [style] and [placeholderStyle] properties allow changing the style of
/// the text and placeholder of the text field. [placeholderStyle] defaults
/// to the gray [CupertinoColors.secondaryLabel] iOS color.
///
/// To set the text field's background color and border radius, pass a
/// [BoxDecoration] to the [decoration] parameter. This defaults to the
/// default translucent tertiarySystemFill iOS color and 9 px corner radius.
// TODO(DanielEdrisian): Must make border radius continuous, see
// https://github.com/flutter/flutter/issues/13914.
///
/// The [itemColor] and [itemSize] properties allow changing the icon color
/// and icon size of the search icon (prefix) and X-Mark (suffix).
/// They default to [CupertinoColors.secondaryLabel] and `20.0`.
///
/// The [padding], [prefixInsets], and [suffixInsets] let you set the padding
/// insets for text, the search icon (prefix), and the X-Mark icon (suffix).
/// They default to values that replicate the `UISearchTextField` look. These
/// default fields were determined using the comparison tool in
/// https://github.com/flutter/platform_tests/.
///
/// To customize the prefix icon, pass a [Widget] to [prefixIcon]. This
/// defaults to the search icon.
///
/// To customize the suffix icon, pass an [Icon] to [suffixIcon]. This
/// defaults to the X-Mark.
///
/// To dictate when the X-Mark (suffix) should be visible, a.k.a. only on when
/// editing, not editing, on always, or on never, pass a
/// [OverlayVisibilityMode] to [suffixMode]. This defaults to only on when
/// editing.
///
/// To customize the X-Mark (suffix) action, pass a [VoidCallback] to
/// [onSuffixTap]. This defaults to clearing the text.
const CupertinoSearchTextField({
  super.key,
  this.controller,
  this.onChanged,
  this.onSubmitted,
  this.style,
  this.placeholder,
  this.placeholderStyle,
  this.decoration,
  this.backgroundColor,
  this.borderRadius,
  this.keyboardType = TextInputType.text,
  this.padding = const EdgeInsetsDirectional.fromSTEB(5.5, 8, 5.5, 8),
  this.itemColor = CupertinoColors.secondaryLabel,
  this.itemSize = 20.0,
  this.prefixInsets = const EdgeInsetsDirectional.fromSTEB(6, 0, 0, 3),
  this.prefixIcon = const Icon(CupertinoIcons.search),
  this.suffixInsets = const EdgeInsetsDirectional.fromSTEB(0, 0, 5, 2),
  this.suffixIcon = const Icon(CupertinoIcons.xmark_circle_fill),
  this.suffixMode = OverlayVisibilityMode.editing,
  this.onSuffixTap,
  this.restorationId,
  this.focusNode,
  this.smartQuotesType,
  this.smartDashesType,
  this.enableIMEPersonalizedLearning = true,
  this.autofocus = false,
  this.onTap,
  this.autocorrect = true,
  this.enabled,
})  : assert(
        !((decoration != null) && (backgroundColor != null)),
        'Cannot provide both a background color and a decoration\n'
        'To provide both, use "decoration: BoxDecoration(color: '
        'backgroundColor)"',
      ),
      assert(
        !((decoration != null) && (borderRadius != null)),
        'Cannot provide both a border radius and a decoration\n'
        'To provide both, use "decoration: BoxDecoration(borderRadius: '
        'borderRadius)"',
      );