Skip to content

Commit af757cb

Browse files
[CP-stable]Add ContextMenuButtonKind (#195015)
This pull request is created by [automatic cherry pick workflow](https://github.com/flutter/flutter/blob/main/docs/releases/Flutter-Cherrypick-Process.md#automatically-creates-a-cherry-pick-request) Please fill in the form below, and a flutter domain expert will evaluate this cherry pick request. ### Issue Link: Part of flutter/flutter#193527 ### Impact Description: Low user-facing impact on its own, as this PR is purely additive (`ContextMenuButtonKind` and `ContextMenuButtonItem.kind`) without deprecating `ContextMenuButtonType` or changing existing behavior. However, cherry-picking this into `3.47` unblocks the decoupled `cupertino_ui` and `material_ui` packages (which must support the latest stable Flutter release) from migrating to `ContextMenuButtonKind` and unblocks shipping the iOS Translate context menu work (#180021) without waiting an extra stable release cycle. ### Changelog Description: Explain this cherry pick: - [flutter/193527](flutter/flutter#193527) When building custom text selection menus, packages can't add new actions such as Translate without breaking exhaustive switches on `ContextMenuButtonType`; adds the extensible `ContextMenuButtonKind`. ### Workaround: Is there a workaround for this issue? No. ### Risk: What is the risk level of this cherry-pick? ### Test Coverage: Are you confident that your fix is well-tested by automated tests? ### Validation Steps: Run the automated unit tests in `flutter test test/widgets/context_menu_button_item_test.dart`, `test/widgets/editable_text_test.dart`, `test/widgets/selectable_region_test.dart`, and `test/widgets/system_context_menu_test.dart` to verify `ContextMenuButtonKind` and `ContextMenuButtonItem.kind` behavior and backwards compatibility with `ContextMenuButtonType`.
1 parent a2bafa5 commit af757cb

5 files changed

Lines changed: 274 additions & 38 deletions

File tree

‎packages/flutter/lib/src/widgets/context_menu_button_item.dart‎

Lines changed: 176 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ import 'framework.dart';
1212

1313
/// The buttons that can appear in a context menu by default.
1414
///
15+
/// Prefer using [ContextMenuButtonKind] instead, as [ContextMenuButtonType]
16+
/// cannot gain new values without breaking exhaustive switches.
17+
///
1518
/// See also:
1619
///
1720
/// * [ContextMenuButtonItem], which uses this enum to describe a button in a
@@ -52,7 +55,135 @@ enum ContextMenuButtonType {
5255
custom,
5356
}
5457

55-
/// The type and callback for a context menu button.
58+
/// The kinds of buttons that can appear in a context menu by default.
59+
///
60+
/// New kinds may be added in the future, so switches on this class should
61+
/// include a wildcard (`_`) case.
62+
///
63+
/// See also:
64+
///
65+
/// * [ContextMenuButtonItem], which uses this class to describe a button in a
66+
/// context menu.
67+
@immutable
68+
final class ContextMenuButtonKind {
69+
const ContextMenuButtonKind._(this.name, this._legacyType);
70+
71+
/// A name for this kind, useful for debugging.
72+
final String name;
73+
74+
/// The closest [ContextMenuButtonType] for this kind, used to keep
75+
/// [ContextMenuButtonItem.type] working. Kinds with no matching
76+
/// [ContextMenuButtonType] map to [ContextMenuButtonType.custom].
77+
final ContextMenuButtonType _legacyType;
78+
79+
/// A button that cuts the current text selection.
80+
static const ContextMenuButtonKind cut = ContextMenuButtonKind._(
81+
'cut',
82+
ContextMenuButtonType.cut,
83+
);
84+
85+
/// A button that copies the current text selection.
86+
static const ContextMenuButtonKind copy = ContextMenuButtonKind._(
87+
'copy',
88+
ContextMenuButtonType.copy,
89+
);
90+
91+
/// A button that pastes the clipboard contents into the focused text field.
92+
static const ContextMenuButtonKind paste = ContextMenuButtonKind._(
93+
'paste',
94+
ContextMenuButtonType.paste,
95+
);
96+
97+
/// A button that selects all the contents of the focused text field.
98+
static const ContextMenuButtonKind selectAll = ContextMenuButtonKind._(
99+
'selectAll',
100+
ContextMenuButtonType.selectAll,
101+
);
102+
103+
/// A button that deletes the current text selection.
104+
static const ContextMenuButtonKind delete = ContextMenuButtonKind._(
105+
'delete',
106+
ContextMenuButtonType.delete,
107+
);
108+
109+
/// A button that looks up the current text selection.
110+
static const ContextMenuButtonKind lookUp = ContextMenuButtonKind._(
111+
'lookUp',
112+
ContextMenuButtonType.lookUp,
113+
);
114+
115+
/// A button that launches a web search for the current text selection.
116+
static const ContextMenuButtonKind searchWeb = ContextMenuButtonKind._(
117+
'searchWeb',
118+
ContextMenuButtonType.searchWeb,
119+
);
120+
121+
/// A button that displays the share screen for the current text selection.
122+
static const ContextMenuButtonKind share = ContextMenuButtonKind._(
123+
'share',
124+
ContextMenuButtonType.share,
125+
);
126+
127+
/// A button for starting Live Text input.
128+
///
129+
/// See also:
130+
/// * [LiveText], where the availability of Live Text input can be obtained.
131+
/// * [LiveTextInputStatusNotifier], where the status of Live Text can be listened to.
132+
static const ContextMenuButtonKind liveTextInput = ContextMenuButtonKind._(
133+
'liveTextInput',
134+
ContextMenuButtonType.liveTextInput,
135+
);
136+
137+
/// A button that launches a translation popup for the current text selection.
138+
static const ContextMenuButtonKind translate = ContextMenuButtonKind._(
139+
'translate',
140+
ContextMenuButtonType.custom,
141+
);
142+
143+
/// Anything other than the default button kinds.
144+
static const ContextMenuButtonKind custom = ContextMenuButtonKind._(
145+
'custom',
146+
ContextMenuButtonType.custom,
147+
);
148+
149+
/// All of the kinds currently known to this version of Flutter.
150+
///
151+
/// New kinds may be added to this list in the future.
152+
static const List<ContextMenuButtonKind> values = <ContextMenuButtonKind>[
153+
cut,
154+
copy,
155+
paste,
156+
selectAll,
157+
delete,
158+
lookUp,
159+
searchWeb,
160+
share,
161+
liveTextInput,
162+
translate,
163+
custom,
164+
];
165+
166+
/// Returns the kind that corresponds to a [ContextMenuButtonType].
167+
static ContextMenuButtonKind _fromLegacyType(ContextMenuButtonType type) {
168+
return switch (type) {
169+
ContextMenuButtonType.cut => cut,
170+
ContextMenuButtonType.copy => copy,
171+
ContextMenuButtonType.paste => paste,
172+
ContextMenuButtonType.selectAll => selectAll,
173+
ContextMenuButtonType.delete => delete,
174+
ContextMenuButtonType.lookUp => lookUp,
175+
ContextMenuButtonType.searchWeb => searchWeb,
176+
ContextMenuButtonType.share => share,
177+
ContextMenuButtonType.liveTextInput => liveTextInput,
178+
ContextMenuButtonType.custom => custom,
179+
};
180+
}
181+
182+
@override
183+
String toString() => 'ContextMenuButtonKind.$name';
184+
}
185+
186+
/// The kind and callback for a context menu button.
56187
///
57188
/// See also:
58189
///
@@ -64,22 +195,55 @@ enum ContextMenuButtonType {
64195
@immutable
65196
class ContextMenuButtonItem {
66197
/// Creates a const instance of [ContextMenuButtonItem].
198+
///
199+
/// At most one of [kind] or [type] may be given. If neither is given, the
200+
/// button is a [ContextMenuButtonKind.custom] button.
67201
const ContextMenuButtonItem({
68202
required this.onPressed,
69-
this.type = ContextMenuButtonType.custom,
203+
ContextMenuButtonType? type,
204+
ContextMenuButtonKind? kind,
70205
this.label,
71-
});
206+
}) : assert(type == null || kind == null, 'Only one of type and kind may be given.'),
207+
_type = type,
208+
_kind = kind;
72209

73210
/// The callback to be called when the button is pressed.
74211
final VoidCallback? onPressed;
75212

213+
/// The [ContextMenuButtonType] passed to the constructor, if any.
214+
final ContextMenuButtonType? _type;
215+
216+
/// The [ContextMenuButtonKind] passed to the constructor, if any.
217+
final ContextMenuButtonKind? _kind;
218+
219+
/// The kind of button this represents.
220+
///
221+
/// If created with [type], this returns the corresponding
222+
/// [ContextMenuButtonKind]. Defaults to [ContextMenuButtonKind.custom] if
223+
/// neither [kind] nor [type] was specified.
224+
ContextMenuButtonKind get kind {
225+
if (_kind != null) {
226+
return _kind;
227+
}
228+
if (_type != null) {
229+
return ContextMenuButtonKind._fromLegacyType(_type);
230+
}
231+
return ContextMenuButtonKind.custom;
232+
}
233+
76234
/// The type of button this represents.
77-
final ContextMenuButtonType type;
235+
///
236+
/// Prefer using [kind] instead.
237+
///
238+
/// Kinds that have no equivalent [ContextMenuButtonType], such as
239+
/// [ContextMenuButtonKind.translate], are reported as
240+
/// [ContextMenuButtonType.custom].
241+
ContextMenuButtonType get type => _type ?? kind._legacyType;
78242

79243
/// The label to display on the button.
80244
///
81-
/// If a [type] other than [ContextMenuButtonType.custom] is given
82-
/// and a label is not provided, then the default label for that type for the
245+
/// If a [kind] other than [ContextMenuButtonKind.custom] is given
246+
/// and a label is not provided, then the default label for that kind for the
83247
/// platform will be looked up.
84248
final String? label;
85249

@@ -88,11 +252,13 @@ class ContextMenuButtonItem {
88252
ContextMenuButtonItem copyWith({
89253
VoidCallback? onPressed,
90254
ContextMenuButtonType? type,
255+
ContextMenuButtonKind? kind,
91256
String? label,
92257
}) {
258+
assert(type == null || kind == null, 'Only one of type and kind may be given.');
93259
return ContextMenuButtonItem(
94260
onPressed: onPressed ?? this.onPressed,
95-
type: type ?? this.type,
261+
kind: kind ?? (type != null ? ContextMenuButtonKind._fromLegacyType(type) : this.kind),
96262
label: label ?? this.label,
97263
);
98264
}
@@ -105,12 +271,12 @@ class ContextMenuButtonItem {
105271
return other is ContextMenuButtonItem &&
106272
other.label == label &&
107273
other.onPressed == onPressed &&
108-
other.type == type;
274+
other.kind == kind;
109275
}
110276

111277
@override
112-
int get hashCode => Object.hash(label, onPressed, type);
278+
int get hashCode => Object.hash(label, onPressed, kind);
113279

114280
@override
115-
String toString() => 'ContextMenuButtonItem $type, $label';
281+
String toString() => 'ContextMenuButtonItem $kind, $label';
116282
}

‎packages/flutter/lib/src/widgets/editable_text.dart‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2167,21 +2167,21 @@ class EditableText extends StatefulWidget {
21672167
final showShareBeforeSelectAll = defaultTargetPlatform == TargetPlatform.android;
21682168

21692169
resultButtonItem.addAll(<ContextMenuButtonItem>[
2170-
if (onCut != null) ContextMenuButtonItem(onPressed: onCut, type: ContextMenuButtonType.cut),
2170+
if (onCut != null) ContextMenuButtonItem(onPressed: onCut, kind: ContextMenuButtonKind.cut),
21712171
if (onCopy != null)
2172-
ContextMenuButtonItem(onPressed: onCopy, type: ContextMenuButtonType.copy),
2172+
ContextMenuButtonItem(onPressed: onCopy, kind: ContextMenuButtonKind.copy),
21732173
if (onPaste != null)
2174-
ContextMenuButtonItem(onPressed: onPaste, type: ContextMenuButtonType.paste),
2174+
ContextMenuButtonItem(onPressed: onPaste, kind: ContextMenuButtonKind.paste),
21752175
if (onShare != null && showShareBeforeSelectAll)
2176-
ContextMenuButtonItem(onPressed: onShare, type: ContextMenuButtonType.share),
2176+
ContextMenuButtonItem(onPressed: onShare, kind: ContextMenuButtonKind.share),
21772177
if (onSelectAll != null)
2178-
ContextMenuButtonItem(onPressed: onSelectAll, type: ContextMenuButtonType.selectAll),
2178+
ContextMenuButtonItem(onPressed: onSelectAll, kind: ContextMenuButtonKind.selectAll),
21792179
if (onLookUp != null)
2180-
ContextMenuButtonItem(onPressed: onLookUp, type: ContextMenuButtonType.lookUp),
2180+
ContextMenuButtonItem(onPressed: onLookUp, kind: ContextMenuButtonKind.lookUp),
21812181
if (onSearchWeb != null)
2182-
ContextMenuButtonItem(onPressed: onSearchWeb, type: ContextMenuButtonType.searchWeb),
2182+
ContextMenuButtonItem(onPressed: onSearchWeb, kind: ContextMenuButtonKind.searchWeb),
21832183
if (onShare != null && !showShareBeforeSelectAll)
2184-
ContextMenuButtonItem(onPressed: onShare, type: ContextMenuButtonType.share),
2184+
ContextMenuButtonItem(onPressed: onShare, kind: ContextMenuButtonKind.share),
21852185
]);
21862186
}
21872187

@@ -2190,7 +2190,7 @@ class EditableText extends StatefulWidget {
21902190
resultButtonItem.add(
21912191
ContextMenuButtonItem(
21922192
onPressed: onLiveTextInput,
2193-
type: ContextMenuButtonType.liveTextInput,
2193+
kind: ContextMenuButtonKind.liveTextInput,
21942194
),
21952195
);
21962196
}
@@ -3131,28 +3131,28 @@ class EditableTextState extends State<EditableText>
31313131
onPressed: () {
31323132
cutSelection(SelectionChangedCause.toolbar);
31333133
},
3134-
type: ContextMenuButtonType.cut,
3134+
kind: ContextMenuButtonKind.cut,
31353135
),
31363136
if (toolbarOptions.copy && copyEnabled)
31373137
ContextMenuButtonItem(
31383138
onPressed: () {
31393139
copySelection(SelectionChangedCause.toolbar);
31403140
},
3141-
type: ContextMenuButtonType.copy,
3141+
kind: ContextMenuButtonKind.copy,
31423142
),
31433143
if (toolbarOptions.paste && pasteEnabled)
31443144
ContextMenuButtonItem(
31453145
onPressed: () async {
31463146
await _pasteTextWithReporting(SelectionChangedCause.toolbar);
31473147
},
3148-
type: ContextMenuButtonType.paste,
3148+
kind: ContextMenuButtonKind.paste,
31493149
),
31503150
if (toolbarOptions.selectAll && selectAllEnabled)
31513151
ContextMenuButtonItem(
31523152
onPressed: () {
31533153
selectAll(SelectionChangedCause.toolbar);
31543154
},
3155-
type: ContextMenuButtonType.selectAll,
3155+
kind: ContextMenuButtonKind.selectAll,
31563156
),
31573157
];
31583158
}

‎packages/flutter/lib/src/widgets/selectable_region.dart‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -331,13 +331,13 @@ class SelectableRegion extends StatefulWidget {
331331
// known. A button's position in the menu can slightly affect its
332332
// appearance.
333333
return <ContextMenuButtonItem>[
334-
if (canCopy) ContextMenuButtonItem(onPressed: onCopy, type: ContextMenuButtonType.copy),
334+
if (canCopy) ContextMenuButtonItem(onPressed: onCopy, kind: ContextMenuButtonKind.copy),
335335
if (canShare && showShareBeforeSelectAll)
336-
ContextMenuButtonItem(onPressed: onShare, type: ContextMenuButtonType.share),
336+
ContextMenuButtonItem(onPressed: onShare, kind: ContextMenuButtonKind.share),
337337
if (canSelectAll)
338-
ContextMenuButtonItem(onPressed: onSelectAll, type: ContextMenuButtonType.selectAll),
338+
ContextMenuButtonItem(onPressed: onSelectAll, kind: ContextMenuButtonKind.selectAll),
339339
if (canShare && !showShareBeforeSelectAll)
340-
ContextMenuButtonItem(onPressed: onShare, type: ContextMenuButtonType.share),
340+
ContextMenuButtonItem(onPressed: onShare, kind: ContextMenuButtonKind.share),
341341
];
342342
}
343343

‎packages/flutter/lib/src/widgets/system_context_menu.dart‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -161,28 +161,32 @@ class SystemContextMenu extends StatefulWidget {
161161

162162
// Use the generic Flutter-rendered context menu model as the single source of truth.
163163
for (final ContextMenuButtonItem button in editableTextState.contextMenuButtonItems) {
164-
switch (button.type) {
165-
case ContextMenuButtonType.copy:
164+
switch (button.kind) {
165+
case ContextMenuButtonKind.copy:
166166
items.add(const IOSSystemContextMenuItemCopy());
167-
case ContextMenuButtonType.cut:
167+
case ContextMenuButtonKind.cut:
168168
items.add(const IOSSystemContextMenuItemCut());
169-
case ContextMenuButtonType.paste:
169+
case ContextMenuButtonKind.paste:
170170
items.add(const IOSSystemContextMenuItemPaste());
171-
case ContextMenuButtonType.selectAll:
171+
case ContextMenuButtonKind.selectAll:
172172
items.add(const IOSSystemContextMenuItemSelectAll());
173-
case ContextMenuButtonType.lookUp:
173+
case ContextMenuButtonKind.lookUp:
174174
items.add(const IOSSystemContextMenuItemLookUp());
175-
case ContextMenuButtonType.searchWeb:
175+
case ContextMenuButtonKind.searchWeb:
176176
items.add(const IOSSystemContextMenuItemSearchWeb());
177-
case ContextMenuButtonType.share:
177+
case ContextMenuButtonKind.share:
178178
items.add(const IOSSystemContextMenuItemShare());
179-
case ContextMenuButtonType.liveTextInput:
179+
case ContextMenuButtonKind.liveTextInput:
180180
items.add(const IOSSystemContextMenuItemLiveText());
181-
case ContextMenuButtonType.delete:
181+
case ContextMenuButtonKind.delete:
182182
// No native iOS system menu button for Delete — intentionally ignored.
183-
case ContextMenuButtonType.custom:
183+
case ContextMenuButtonKind.translate:
184+
// Not mapped to a system menu item yet.
185+
case ContextMenuButtonKind.custom:
184186
// Custom items are provided explicitly via SystemContextMenu.items,
185187
// not via defaults. Intentionally ignore in default mapping.
188+
case _:
189+
// Kinds added in the future are ignored until they're mapped here.
186190
}
187191
}
188192

0 commit comments

Comments
 (0)