development/flutter
development/flutter
1
0
Fork 0
mirror of https://github.com/flutter/flutter synced 2024-09-13 21:32:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Further clarification of the TextSelectionControls migration (#132539)

Browse source 
Further follow-up for https://github.com/flutter/flutter/issues/122421.
This commit is contained in:
Ian Hickson 2023-08-15 09:37:16 -07:00 committed by GitHub
parent efdfd96c4a
commit cc0d63ea66
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 31 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
packages/flutter/lib/src/widgets/editable_text.dart
View file

@ -1255,11 +1255,14 @@ class EditableText extends StatefulWidget {
final Color? selectionColor;
/// {@template flutter.widgets.editableText.selectionControls}
/// Optional delegate for building the text selection handles and toolbar.
/// Optional delegate for building the text selection handles.
///
/// The [EditableText] widget used on its own will not trigger the display
/// of the selection toolbar by itself. The toolbar is shown by calling
/// [EditableTextState.showToolbar] in response to an appropriate user event.
/// Historically, this field also controlled the toolbar. This is now handled
/// by [contextMenuBuilder] instead. However, for backwards compatibility, when
/// [selectionControls] is set to an object that does not mix in
/// [TextSelectionHandleControls], [contextMenuBuilder] is ignored and the
/// [TextSelectionControls.buildToolbar] method is used instead.
/// {@endtemplate}
///
/// See also:
///
@ -1269,7 +1272,6 @@ class EditableText extends StatefulWidget {
/// * [TextField], a Material Design themed wrapper of [EditableText], which
/// shows the selection toolbar upon appropriate user events based on the
/// user's platform set in [ThemeData.platform].
/// {@endtemplate}
final TextSelectionControls? selectionControls;
/// {@template flutter.widgets.editableText.keyboardType}
@ -1778,6 +1780,11 @@ class EditableText extends StatefulWidget {
/// `buttonItems` represents the buttons that would be built by default for
/// this widget.
///
/// For backwards compatibility, when [selectionControls] is set to an object
/// that does not mix in [TextSelectionHandleControls], [contextMenuBuilder]
/// is ignored and the [TextSelectionControls.buildToolbar] method is used
/// instead.
///
/// {@tool dartpad}
/// This example shows how to customize the menu, in this case by keeping the
/// default buttons for the platform but modifying their appearance.

33
packages/flutter/lib/src/widgets/text_selection.dart
View file

@ -61,23 +61,28 @@ class ToolbarItemsParentData extends ContainerBoxParentData<RenderBox> {
/// An interface for building the selection UI, to be provided by the
/// implementer of the toolbar widget.
///
/// Override text operations such as [handleCut] if needed.
/// Parts of this class, including [buildToolbar], have been deprecated in favor
/// of [EditableText.contextMenuBuilder], which is now the preferred way to
/// customize the context menus.
///
/// ## Use with [EditableText.contextMenuBuilder]
/// [buildToolbar] has been deprecated in favor of
/// [EditableText.contextMenuBuilder], and that is the preferred way to
/// customize the context menus now. However, both ways will continue to work
/// during the deprecation period.
///
/// To use both [EditableText.contextMenuBuilder] and [buildHandle], a two-step
/// migration is necessary. First, migrate to [TextSelectionHandleControls],
/// using its [TextSelectionHandleControls.buildHandle] method and moving
/// toolbar code to [EditableText.contextMenuBuilder]. Later, the deprecation
/// period will expire, [buildToolbar] will be removed, and
/// [TextSelectionHandleControls] will be deprecated. Migrate back to
/// [TextSelectionControls.buildHandle], so that the final state is to use
/// [EditableText.contextMenuBuilder] for the toolbar and
/// [TextSelectionControls] for the handles.
/// For backwards compatibility during the deprecation period, when
/// [EditableText.selectionControls] is set to an object that does not mix in
/// [TextSelectionHandleControls], [EditableText.contextMenuBuilder] is ignored
/// in favor of the deprecated [buildToolbar].
///
/// To migrate code from [buildToolbar] to the preferred
/// [EditableText.contextMenuBuilder], while still using [buildHandle], mix in
/// [TextSelectionHandleControls] into the [TextSelectionControls] subclass when
/// moving any toolbar code to a callback passed to
/// [EditableText.contextMenuBuilder].
///
/// In due course, [buildToolbar] will be removed, and the mixin will no longer
/// be necessary as a way to flag to the framework that the code has been
/// migrated and does not expect [buildToolbar] to be called.
///
/// For more information, see <https://docs.flutter.dev/release/breaking-changes/context-menus>.
///
/// See also:
///