// Copyright 2014 The Flutter Authors. All rights reserved. // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. import 'enum_util.dart'; import 'message.dart'; EnumIndex<TextInputAction> _textInputActionIndex = EnumIndex<TextInputAction>(TextInputAction.values); /// A Flutter Driver command that send a text input action. class SendTextInputAction extends Command { /// Creates a command that enters text into the currently focused widget. const SendTextInputAction(this.textInputAction, {super.timeout}); /// Deserializes this command from the value generated by [serialize]. SendTextInputAction.deserialize(super.json) : textInputAction = _textInputActionIndex.lookupBySimpleName(json['action']!), super.deserialize(); /// The [TextInputAction] final TextInputAction textInputAction; @override String get kind => 'send_text_input_action'; @override Map<String, String> serialize() => super.serialize() ..addAll(<String, String>{ 'action': _textInputActionIndex.toSimpleName(textInputAction), }); } /// An action the user has requested the text input control to perform. /// // This class is identical to [TextInputAction](https://api.flutter.dev/flutter/services/TextInputAction.html). // This class is cloned from `TextInputAction` and must be kept in sync. The cloning is needed // because importing is not allowed directly. enum TextInputAction { /// Logical meaning: There is no relevant input action for the current input /// source, e.g., [TextField]. /// /// Android: Corresponds to Android's "IME_ACTION_NONE". The keyboard setup /// is decided by the OS. The keyboard will likely show a return key. /// /// iOS: iOS does not have a keyboard return type of "none." It is /// inappropriate to choose this [TextInputAction] when running on iOS. none, /// Logical meaning: Let the OS decide which action is most appropriate. /// /// Android: Corresponds to Android's "IME_ACTION_UNSPECIFIED". The OS chooses /// which keyboard action to display. The decision will likely be a done /// button or a return key. /// /// iOS: Corresponds to iOS's "UIReturnKeyDefault". The title displayed in /// the action button is "return". unspecified, /// Logical meaning: The user is done providing input to a group of inputs /// (like a form). Some kind of finalization behavior should now take place. /// /// Android: Corresponds to Android's "IME_ACTION_DONE". The OS displays a /// button that represents completion, e.g., a checkmark button. /// /// iOS: Corresponds to iOS's "UIReturnKeyDone". The title displayed in the /// action button is "Done". done, /// Logical meaning: The user has entered some text that represents a /// destination, e.g., a restaurant name. The "go" button is intended to take /// the user to a part of the app that corresponds to this destination. /// /// Android: Corresponds to Android's "IME_ACTION_GO". The OS displays a /// button that represents taking "the user to the target of the text they /// typed", e.g., a right-facing arrow button. /// /// iOS: Corresponds to iOS's "UIReturnKeyGo". The title displayed in the /// action button is "Go". go, /// Logical meaning: Execute a search query. /// /// Android: Corresponds to Android's "IME_ACTION_SEARCH". The OS displays a /// button that represents a search, e.g., a magnifying glass button. /// /// iOS: Corresponds to iOS's "UIReturnKeySearch". The title displayed in the /// action button is "Search". search, /// Logical meaning: Sends something that the user has composed, e.g., an /// email or a text message. /// /// Android: Corresponds to Android's "IME_ACTION_SEND". The OS displays a /// button that represents sending something, e.g., a paper plane button. /// /// iOS: Corresponds to iOS's "UIReturnKeySend". The title displayed in the /// action button is "Send". send, /// Logical meaning: The user is done with the current input source and wants /// to move to the next one. /// /// Moves the focus to the next focusable item in the same [FocusScope]. /// /// Android: Corresponds to Android's "IME_ACTION_NEXT". The OS displays a /// button that represents moving forward, e.g., a right-facing arrow button. /// /// iOS: Corresponds to iOS's "UIReturnKeyNext". The title displayed in the /// action button is "Next". next, /// Logical meaning: The user wishes to return to the previous input source /// in the group, e.g., a form with multiple [TextField]s. /// /// Moves the focus to the previous focusable item in the same [FocusScope]. /// /// Android: Corresponds to Android's "IME_ACTION_PREVIOUS". The OS displays a /// button that represents moving backward, e.g., a left-facing arrow button. /// /// iOS: iOS does not have a keyboard return type of "previous." It is /// inappropriate to choose this [TextInputAction] when running on iOS. previous, /// Logical meaning: In iOS apps, it is common for a "Back" button and /// "Continue" button to appear at the top of the screen. However, when the /// keyboard is open, these buttons are often hidden off-screen. Therefore, /// the purpose of the "Continue" return key on iOS is to make the "Continue" /// button available when the user is entering text. /// /// Historical context aside, [TextInputAction.continueAction] can be used any /// time that the term "Continue" seems most appropriate for the given action. /// /// Android: Android does not have an IME input type of "continue." It is /// inappropriate to choose this [TextInputAction] when running on Android. /// /// iOS: Corresponds to iOS's "UIReturnKeyContinue". The title displayed in the /// action button is "Continue". This action is only available on iOS 9.0+. /// /// The reason that this value has "Action" post-fixed to it is because /// "continue" is a reserved word in Dart, as well as many other languages. continueAction, /// Logical meaning: The user wants to join something, e.g., a wireless /// network. /// /// Android: Android does not have an IME input type of "join." It is /// inappropriate to choose this [TextInputAction] when running on Android. /// /// iOS: Corresponds to iOS's "UIReturnKeyJoin". The title displayed in the /// action button is "Join". join, /// Logical meaning: The user wants routing options, e.g., driving directions. /// /// Android: Android does not have an IME input type of "route." It is /// inappropriate to choose this [TextInputAction] when running on Android. /// /// iOS: Corresponds to iOS's "UIReturnKeyRoute". The title displayed in the /// action button is "Route". route, /// Logical meaning: Initiate a call to emergency services. /// /// Android: Android does not have an IME input type of "emergencyCall." It is /// inappropriate to choose this [TextInputAction] when running on Android. /// /// iOS: Corresponds to iOS's "UIReturnKeyEmergencyCall". The title displayed /// in the action button is "Emergency Call". emergencyCall, /// Logical meaning: Insert a newline character in the focused text input, /// e.g., [TextField]. /// /// Android: Corresponds to Android's "IME_ACTION_NONE". The OS displays a /// button that represents a new line, e.g., a carriage return button. /// /// iOS: Corresponds to iOS's "UIReturnKeyDefault". The title displayed in the /// action button is "return". /// /// The term [TextInputAction.newline] exists in Flutter but not in Android /// or iOS. The reason for introducing this term is so that developers can /// achieve the common result of inserting new lines without needing to /// understand the various IME actions on Android and return keys on iOS. /// Thus, [TextInputAction.newline] is a convenience term that alleviates the /// need to understand the underlying platforms to achieve this common behavior. newline, }