CupertinoInput constructor
- required ValueNotifier<
BoxDecorationTweenInfo?> decorationTween, - required TextStyle placeholderStyle,
- required TextStyle titleStyle,
- required bool usePlaceholderAsTitle,
- required Duration duration,
- required Curve curve,
- Key? key,
- TextEditingController? controller,
- FocusNode? focusNode,
- UndoHistoryController? undoController,
- EdgeInsetsGeometry padding = const EdgeInsets.all(7.0),
- String? placeholder,
- Widget? prefix,
- OverlayVisibilityMode prefixMode = OverlayVisibilityMode.always,
- Widget? suffix,
- OverlayVisibilityMode suffixMode = OverlayVisibilityMode.always,
- OverlayVisibilityMode clearButtonMode = OverlayVisibilityMode.never,
- TextInputType? keyboardType,
- TextInputAction? textInputAction,
- TextCapitalization textCapitalization = TextCapitalization.none,
- TextStyle? style,
- StrutStyle? strutStyle,
- TextAlign textAlign = TextAlign.start,
- TextAlignVertical? textAlignVertical,
- TextDirection? textDirection,
- bool readOnly = false,
- bool? showCursor,
- bool autofocus = false,
- String obscuringCharacter = '•',
- bool obscureText = false,
- bool autocorrect = true,
- SmartDashesType? smartDashesType,
- SmartQuotesType? smartQuotesType,
- bool enableSuggestions = true,
- int? maxLines = 1,
- int? minLines,
- bool expands = false,
- int? maxLength,
- MaxLengthEnforcement? maxLengthEnforcement,
- ValueChanged<
String> ? onChanged, - VoidCallback? onEditingComplete,
- ValueChanged<
String> ? onSubmitted, - TapRegionCallback? onTapOutside,
- List<
TextInputFormatter> ? inputFormatters, - bool? enabled,
- double cursorWidth = 2.0,
- double? cursorHeight,
- Radius cursorRadius = const Radius.circular(2.0),
- bool cursorOpacityAnimates = true,
- Color? cursorColor,
- BoxHeightStyle selectionHeightStyle = ui.BoxHeightStyle.tight,
- BoxWidthStyle selectionWidthStyle = ui.BoxWidthStyle.tight,
- Brightness? keyboardAppearance,
- EdgeInsets scrollPadding = const EdgeInsets.all(20.0),
- DragStartBehavior dragStartBehavior = DragStartBehavior.start,
- bool? enableInteractiveSelection,
- TextSelectionControls? selectionControls,
- GestureTapCallback? onTap,
- ScrollController? scrollController,
- ScrollPhysics? scrollPhysics,
- Iterable<
String> ? autofillHints = const <String>[], - ContentInsertionConfiguration? contentInsertionConfiguration,
- Clip clipBehavior = Clip.hardEdge,
- String? restorationId,
- bool scribbleEnabled = true,
- bool enableIMEPersonalizedLearning = true,
- EditableTextContextMenuBuilder? contextMenuBuilder = _defaultContextMenuBuilder,
- SpellCheckConfiguration? spellCheckConfiguration,
- TextMagnifierConfiguration? magnifierConfiguration,
- Widget? bottom,
- Widget? top,
- HitTestBehavior hitTestBehavior = HitTestBehavior.translucent,
Creates an iOS-style text field.
To provide a prefilled text entry, pass in a TextEditingController with
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
it overflows. maxLines
must not be zero.
The text cursor is not shown if showCursor
is false or if showCursor
is null (the default) and readOnly
is true.
If specified, the maxLength
property must be greater than zero.
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.
The autocorrect
, autofocus
, clearButtonMode
, dragStartBehavior
,
expands
, obscureText
, prefixMode
, readOnly
, scrollPadding
,
suffixMode
, textAlign
, selectionHeightStyle
, selectionWidthStyle
,
enableSuggestions
, and enableIMEPersonalizedLearning
properties must
not be null.
Troubleshooting Common Accessibility Issues
Customizing User Input Accessibility Announcements
To customize user input accessibility announcements triggered by text changes, use SemanticsService.announce to make the desired accessibility announcement.
On iOS, the on-screen keyboard may announce the most recent input
incorrectly when a TextInputFormatter inserts a thousands separator to
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):
onChanged: (String newText) {
if (newText.isNotEmpty) {
SemanticsService.announce('\$$newText', Directionality.of(context));
}
}
See also:
minLines
, which is the minimum number of lines to occupy when the content spans fewer lines.expands
, to allow the widget to size itself to its parent's height.maxLength
, which discusses the precise meaning of "number of characters" and how it may differ from the intuitive meaning.
Implementation
const CupertinoInput({
required this.decorationTween,
required this.placeholderStyle,
required this.titleStyle,
required this.usePlaceholderAsTitle,
required this.duration,
required this.curve,
super.key,
this.controller,
this.focusNode,
this.undoController,
this.padding = const EdgeInsets.all(7.0),
this.placeholder,
this.prefix,
this.prefixMode = OverlayVisibilityMode.always,
this.suffix,
this.suffixMode = OverlayVisibilityMode.always,
this.clearButtonMode = OverlayVisibilityMode.never,
TextInputType? keyboardType,
this.textInputAction,
this.textCapitalization = TextCapitalization.none,
this.style,
this.strutStyle,
this.textAlign = TextAlign.start,
this.textAlignVertical,
this.textDirection,
this.readOnly = false,
this.showCursor,
this.autofocus = false,
this.obscuringCharacter = '•',
this.obscureText = false,
this.autocorrect = true,
SmartDashesType? smartDashesType,
SmartQuotesType? smartQuotesType,
this.enableSuggestions = true,
this.maxLines = 1,
this.minLines,
this.expands = false,
this.maxLength,
this.maxLengthEnforcement,
this.onChanged,
this.onEditingComplete,
this.onSubmitted,
this.onTapOutside,
this.inputFormatters,
this.enabled,
this.cursorWidth = 2.0,
this.cursorHeight,
this.cursorRadius = const Radius.circular(2.0),
this.cursorOpacityAnimates = true,
this.cursorColor,
this.selectionHeightStyle = ui.BoxHeightStyle.tight,
this.selectionWidthStyle = ui.BoxWidthStyle.tight,
this.keyboardAppearance,
this.scrollPadding = const EdgeInsets.all(20.0),
this.dragStartBehavior = DragStartBehavior.start,
bool? enableInteractiveSelection,
this.selectionControls,
this.onTap,
this.scrollController,
this.scrollPhysics,
this.autofillHints = const <String>[],
this.contentInsertionConfiguration,
this.clipBehavior = Clip.hardEdge,
this.restorationId,
this.scribbleEnabled = true,
this.enableIMEPersonalizedLearning = true,
this.contextMenuBuilder = _defaultContextMenuBuilder,
this.spellCheckConfiguration,
this.magnifierConfiguration,
this.bottom,
this.top,
this.hitTestBehavior = HitTestBehavior.translucent,
}) : assert(obscuringCharacter.length == 1),
smartDashesType = smartDashesType ??
(obscureText ? SmartDashesType.disabled : SmartDashesType.enabled),
smartQuotesType = smartQuotesType ??
(obscureText ? SmartQuotesType.disabled : SmartQuotesType.enabled),
assert(maxLines == null || maxLines > 0),
assert(minLines == null || minLines > 0),
assert(
(maxLines == null) || (minLines == null) || (maxLines >= minLines),
"minLines can't be greater than maxLines",
),
assert(
!expands || (maxLines == null && minLines == null),
'minLines and maxLines must be null when expands is true.',
),
assert(
!obscureText || maxLines == 1,
'Obscured fields cannot be multiline.',
),
assert(maxLength == null || maxLength > 0),
// 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.',
),
keyboardType = keyboardType ??
(maxLines == 1 ? TextInputType.text : TextInputType.multiline),
enableInteractiveSelection =
enableInteractiveSelection ?? (!readOnly || !obscureText);