1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5/// @docImport 'package:flutter/material.dart';
6library;
7
8import 'enum_util.dart';
9import 'message.dart';
10
11EnumIndex<TextInputAction> _textInputActionIndex =
12 EnumIndex<TextInputAction>(TextInputAction.values);
13
14/// A Flutter Driver command that send a text input action.
15class SendTextInputAction extends Command {
16 /// Creates a command that enters text into the currently focused widget.
17 const SendTextInputAction(this.textInputAction, {super.timeout});
18
19 /// Deserializes this command from the value generated by [serialize].
20 SendTextInputAction.deserialize(super.json)
21 : textInputAction =
22 _textInputActionIndex.lookupBySimpleName(json['action']!),
23 super.deserialize();
24
25 /// The [TextInputAction]
26 final TextInputAction textInputAction;
27
28 @override
29 String get kind => 'send_text_input_action';
30
31 @override
32 Map<String, String> serialize() => super.serialize()
33 ..addAll(<String, String>{
34 'action': _textInputActionIndex.toSimpleName(textInputAction),
35 });
36}
37
38/// An action the user has requested the text input control to perform.
39///
40// This class is identical to [TextInputAction](https://api.flutter.dev/flutter/services/TextInputAction.html).
41// This class is cloned from `TextInputAction` and must be kept in sync. The cloning is needed
42// because importing is not allowed directly.
43enum TextInputAction {
44 /// Logical meaning: There is no relevant input action for the current input
45 /// source, e.g., [TextField].
46 ///
47 /// Android: Corresponds to Android's "IME_ACTION_NONE". The keyboard setup
48 /// is decided by the OS. The keyboard will likely show a return key.
49 ///
50 /// iOS: iOS does not have a keyboard return type of "none." It is
51 /// inappropriate to choose this [TextInputAction] when running on iOS.
52 none,
53
54 /// Logical meaning: Let the OS decide which action is most appropriate.
55 ///
56 /// Android: Corresponds to Android's "IME_ACTION_UNSPECIFIED". The OS chooses
57 /// which keyboard action to display. The decision will likely be a done
58 /// button or a return key.
59 ///
60 /// iOS: Corresponds to iOS's "UIReturnKeyDefault". The title displayed in
61 /// the action button is "return".
62 unspecified,
63
64 /// Logical meaning: The user is done providing input to a group of inputs
65 /// (like a form). Some kind of finalization behavior should now take place.
66 ///
67 /// Android: Corresponds to Android's "IME_ACTION_DONE". The OS displays a
68 /// button that represents completion, e.g., a checkmark button.
69 ///
70 /// iOS: Corresponds to iOS's "UIReturnKeyDone". The title displayed in the
71 /// action button is "Done".
72 done,
73
74 /// Logical meaning: The user has entered some text that represents a
75 /// destination, e.g., a restaurant name. The "go" button is intended to take
76 /// the user to a part of the app that corresponds to this destination.
77 ///
78 /// Android: Corresponds to Android's "IME_ACTION_GO". The OS displays a
79 /// button that represents taking "the user to the target of the text they
80 /// typed", e.g., a right-facing arrow button.
81 ///
82 /// iOS: Corresponds to iOS's "UIReturnKeyGo". The title displayed in the
83 /// action button is "Go".
84 go,
85
86 /// Logical meaning: Execute a search query.
87 ///
88 /// Android: Corresponds to Android's "IME_ACTION_SEARCH". The OS displays a
89 /// button that represents a search, e.g., a magnifying glass button.
90 ///
91 /// iOS: Corresponds to iOS's "UIReturnKeySearch". The title displayed in the
92 /// action button is "Search".
93 search,
94
95 /// Logical meaning: Sends something that the user has composed, e.g., an
96 /// email or a text message.
97 ///
98 /// Android: Corresponds to Android's "IME_ACTION_SEND". The OS displays a
99 /// button that represents sending something, e.g., a paper plane button.
100 ///
101 /// iOS: Corresponds to iOS's "UIReturnKeySend". The title displayed in the
102 /// action button is "Send".
103 send,
104
105 /// Logical meaning: The user is done with the current input source and wants
106 /// to move to the next one.
107 ///
108 /// Moves the focus to the next focusable item in the same [FocusScope].
109 ///
110 /// Android: Corresponds to Android's "IME_ACTION_NEXT". The OS displays a
111 /// button that represents moving forward, e.g., a right-facing arrow button.
112 ///
113 /// iOS: Corresponds to iOS's "UIReturnKeyNext". The title displayed in the
114 /// action button is "Next".
115 next,
116
117 /// Logical meaning: The user wishes to return to the previous input source
118 /// in the group, e.g., a form with multiple [TextField]s.
119 ///
120 /// Moves the focus to the previous focusable item in the same [FocusScope].
121 ///
122 /// Android: Corresponds to Android's "IME_ACTION_PREVIOUS". The OS displays a
123 /// button that represents moving backward, e.g., a left-facing arrow button.
124 ///
125 /// iOS: iOS does not have a keyboard return type of "previous." It is
126 /// inappropriate to choose this [TextInputAction] when running on iOS.
127 previous,
128
129 /// Logical meaning: In iOS apps, it is common for a "Back" button and
130 /// "Continue" button to appear at the top of the screen. However, when the
131 /// keyboard is open, these buttons are often hidden off-screen. Therefore,
132 /// the purpose of the "Continue" return key on iOS is to make the "Continue"
133 /// button available when the user is entering text.
134 ///
135 /// Historical context aside, [TextInputAction.continueAction] can be used any
136 /// time that the term "Continue" seems most appropriate for the given action.
137 ///
138 /// Android: Android does not have an IME input type of "continue." It is
139 /// inappropriate to choose this [TextInputAction] when running on Android.
140 ///
141 /// iOS: Corresponds to iOS's "UIReturnKeyContinue". The title displayed in the
142 /// action button is "Continue". This action is only available on iOS 9.0+.
143 ///
144 /// The reason that this value has "Action" post-fixed to it is because
145 /// "continue" is a reserved word in Dart, as well as many other languages.
146 continueAction,
147
148 /// Logical meaning: The user wants to join something, e.g., a wireless
149 /// network.
150 ///
151 /// Android: Android does not have an IME input type of "join." It is
152 /// inappropriate to choose this [TextInputAction] when running on Android.
153 ///
154 /// iOS: Corresponds to iOS's "UIReturnKeyJoin". The title displayed in the
155 /// action button is "Join".
156 join,
157
158 /// Logical meaning: The user wants routing options, e.g., driving directions.
159 ///
160 /// Android: Android does not have an IME input type of "route." It is
161 /// inappropriate to choose this [TextInputAction] when running on Android.
162 ///
163 /// iOS: Corresponds to iOS's "UIReturnKeyRoute". The title displayed in the
164 /// action button is "Route".
165 route,
166
167 /// Logical meaning: Initiate a call to emergency services.
168 ///
169 /// Android: Android does not have an IME input type of "emergencyCall." It is
170 /// inappropriate to choose this [TextInputAction] when running on Android.
171 ///
172 /// iOS: Corresponds to iOS's "UIReturnKeyEmergencyCall". The title displayed
173 /// in the action button is "Emergency Call".
174 emergencyCall,
175
176 /// Logical meaning: Insert a newline character in the focused text input,
177 /// e.g., [TextField].
178 ///
179 /// Android: Corresponds to Android's "IME_ACTION_NONE". The OS displays a
180 /// button that represents a new line, e.g., a carriage return button.
181 ///
182 /// iOS: Corresponds to iOS's "UIReturnKeyDefault". The title displayed in the
183 /// action button is "return".
184 ///
185 /// The term [TextInputAction.newline] exists in Flutter but not in Android
186 /// or iOS. The reason for introducing this term is so that developers can
187 /// achieve the common result of inserting new lines without needing to
188 /// understand the various IME actions on Android and return keys on iOS.
189 /// Thus, [TextInputAction.newline] is a convenience term that alleviates the
190 /// need to understand the underlying platforms to achieve this common behavior.
191 newline,
192}
193

Provided by KDAB

Privacy Policy
Learn more about Flutter for embedded and desktop on industrialflutter.com