Skip to content

Commit d11ae18

Browse files
LouiseHsusuryaKommana2662
authored andcommitted
Add ContextMenuButtonKind (flutter#193528)
part of flutter#193527 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant in-code documentation (doc comments with `///`). - [x] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.
1 parent 22035c8 commit d11ae18

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
@@ -2216,21 +2216,21 @@ class EditableText extends StatefulWidget {
22162216
final showShareBeforeSelectAll = defaultTargetPlatform == TargetPlatform.android;
22172217

22182218
resultButtonItem.addAll(<ContextMenuButtonItem>[
2219-
if (onCut != null) ContextMenuButtonItem(onPressed: onCut, type: ContextMenuButtonType.cut),
2219+
if (onCut != null) ContextMenuButtonItem(onPressed: onCut, kind: ContextMenuButtonKind.cut),
22202220
if (onCopy != null)
2221-
ContextMenuButtonItem(onPressed: onCopy, type: ContextMenuButtonType.copy),
2221+
ContextMenuButtonItem(onPressed: onCopy, kind: ContextMenuButtonKind.copy),
22222222
if (onPaste != null)
2223-
ContextMenuButtonItem(onPressed: onPaste, type: ContextMenuButtonType.paste),
2223+
ContextMenuButtonItem(onPressed: onPaste, kind: ContextMenuButtonKind.paste),
22242224
if (onShare != null && showShareBeforeSelectAll)
2225-
ContextMenuButtonItem(onPressed: onShare, type: ContextMenuButtonType.share),
2225+
ContextMenuButtonItem(onPressed: onShare, kind: ContextMenuButtonKind.share),
22262226
if (onSelectAll != null)
2227-
ContextMenuButtonItem(onPressed: onSelectAll, type: ContextMenuButtonType.selectAll),
2227+
ContextMenuButtonItem(onPressed: onSelectAll, kind: ContextMenuButtonKind.selectAll),
22282228
if (onLookUp != null)
2229-
ContextMenuButtonItem(onPressed: onLookUp, type: ContextMenuButtonType.lookUp),
2229+
ContextMenuButtonItem(onPressed: onLookUp, kind: ContextMenuButtonKind.lookUp),
22302230
if (onSearchWeb != null)
2231-
ContextMenuButtonItem(onPressed: onSearchWeb, type: ContextMenuButtonType.searchWeb),
2231+
ContextMenuButtonItem(onPressed: onSearchWeb, kind: ContextMenuButtonKind.searchWeb),
22322232
if (onShare != null && !showShareBeforeSelectAll)
2233-
ContextMenuButtonItem(onPressed: onShare, type: ContextMenuButtonType.share),
2233+
ContextMenuButtonItem(onPressed: onShare, kind: ContextMenuButtonKind.share),
22342234
]);
22352235
}
22362236

@@ -2239,7 +2239,7 @@ class EditableText extends StatefulWidget {
22392239
resultButtonItem.add(
22402240
ContextMenuButtonItem(
22412241
onPressed: onLiveTextInput,
2242-
type: ContextMenuButtonType.liveTextInput,
2242+
kind: ContextMenuButtonKind.liveTextInput,
22432243
),
22442244
);
22452245
}
@@ -3181,28 +3181,28 @@ class EditableTextState extends State<EditableText>
31813181
onPressed: () {
31823182
cutSelection(SelectionChangedCause.toolbar);
31833183
},
3184-
type: ContextMenuButtonType.cut,
3184+
kind: ContextMenuButtonKind.cut,
31853185
),
31863186
if (toolbarOptions.copy && copyEnabled)
31873187
ContextMenuButtonItem(
31883188
onPressed: () {
31893189
copySelection(SelectionChangedCause.toolbar);
31903190
},
3191-
type: ContextMenuButtonType.copy,
3191+
kind: ContextMenuButtonKind.copy,
31923192
),
31933193
if (toolbarOptions.paste && pasteEnabled)
31943194
ContextMenuButtonItem(
31953195
onPressed: () async {
31963196
await _pasteTextWithReporting(SelectionChangedCause.toolbar);
31973197
},
3198-
type: ContextMenuButtonType.paste,
3198+
kind: ContextMenuButtonKind.paste,
31993199
),
32003200
if (toolbarOptions.selectAll && selectAllEnabled)
32013201
ContextMenuButtonItem(
32023202
onPressed: () {
32033203
selectAll(SelectionChangedCause.toolbar);
32043204
},
3205-
type: ContextMenuButtonType.selectAll,
3205+
kind: ContextMenuButtonKind.selectAll,
32063206
),
32073207
];
32083208
}

‎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)