SelectableRegion class

A widget that introduces an area for user selections.

Flutter widgets are not selectable by default. Wrapping a widget subtree with a SelectableRegion widget enables selection within that subtree (for example, Text widgets automatically look for selectable regions to enable selection). The wrapped subtree can be selected by users using mouse or touch gestures, e.g. users can select widgets by holding the mouse left-click and dragging across widgets, or they can use long press gestures to select words on touch devices.

A SelectableRegion widget requires configuration; in particular specific selectionControls must be provided.

The SelectionArea widget from the material library configures a SelectableRegion in a platform-specific manner (e.g. using a Material toolbar on Android, a Cupertino toolbar on iOS), and it may therefore be simpler to use that widget rather than using SelectableRegion directly.

An overview of the selection system.

Every Selectable under the SelectableRegion can be selected. They form a selection tree structure to handle the selection.

The SelectableRegion is a wrapper over SelectionContainer. It listens to user gestures and sends corresponding SelectionEvents to the SelectionContainer it creates.

A SelectionContainer is a single Selectable that handles SelectionEvents on behalf of child Selectables in the subtree. It creates a SelectionRegistrarScope with its SelectionContainer.delegate to collect child Selectables and sends the SelectionEvents it receives from the parent SelectionRegistrar to the appropriate child Selectables. It creates an abstraction for the parent SelectionRegistrar as if it is interacting with a single Selectable.

The SelectionContainer created by SelectableRegion is the root node of a selection tree. Each non-leaf node in the tree is a SelectionContainer, and the leaf node is a leaf widget whose render object implements Selectable. They are connected through SelectionRegistrarScopes created by SelectionContainers.

Both SelectionContainers and the leaf Selectables need to register themselves to the SelectionRegistrar from the SelectionContainer.maybeOf if they want to participate in the selection.

An example selection tree will look like:

link
MaterialApp(
  home: SelectableRegion(
    selectionControls: materialTextSelectionControls,
    focusNode: _focusNode, // initialized to FocusNode()
    child: Scaffold(
      appBar: AppBar(title: const Text('Flutter Code Sample')),
      body: ListView(
        children: const <Widget>[
          Text('Item 0', style: TextStyle(fontSize: 50.0)),
          Text('Item 1', style: TextStyle(fontSize: 50.0)),
        ],
      ),
    ),
  ),
)

          SelectionContainer
          (SelectableRegion)
             /         \
            /           \
           /             \
      Selectable          \
 ("Flutter Code Sample")   \
                            \
                     SelectionContainer
                         (ListView)
                         /       \
                        /         \
                       /           \
                Selectable        Selectable
                ("Item 0")         ("Item 1")

Making a widget selectable

Some leaf widgets, such as Text, have all of the selection logic wired up automatically and can be selected as long as they are under a SelectableRegion.

To make a custom selectable widget, its render object needs to mix in Selectable and implement the required APIs to handle SelectionEvents as well as paint appropriate selection highlights.

The render object also needs to register itself to a SelectionRegistrar. For the most cases, one can use SelectionRegistrant to auto-register itself with the register returned from SelectionContainer.maybeOf as seen in the example below.

This sample demonstrates how to create an adapter widget that makes any child widget selectable.
link

To create a local project with this code sample, run:
flutter create --sample=widgets.SelectableRegion.2 mysample

Complex layout

By default, the screen order is used as the selection order. If a group of Selectables needs to select differently, consider wrapping them with a SelectionContainer to customize its selection behavior.

This sample demonstrates how to create a SelectionContainer that only allows selecting everything or nothing with no partial selection.
link

To create a local project with this code sample, run:
flutter create --sample=widgets.SelectableRegion.3 mysample

In the case where a group of widgets should be excluded from selection under a SelectableRegion, consider wrapping that group of widgets using SelectionContainer.disabled.

This sample demonstrates how to disable selection for a Text in a Column.
link

To create a local project with this code sample, run:
flutter create --sample=widgets.SelectableRegion.4 mysample

To create a separate selection system from its parent selection area, wrap part of the subtree with another SelectableRegion. The selection of the child selection area can not extend past its subtree, and the selection of the parent selection area can not extend inside the child selection area.

Tests

In a test, a region can be selected either by faking drag events (e.g. using WidgetTester.dragFrom) or by sending intents to a widget inside the region that has been given a GlobalKey, e.g.:

Actions.invoke(key.currentContext!, const SelectAllTextIntent(SelectionChangedCause.keyboard));

See also:

Inheritance

Constructors

SelectableRegion({Key? key, SelectableRegionContextMenuBuilder? contextMenuBuilder, required FocusNode focusNode, required TextSelectionControls selectionControls, required Widget child, TextMagnifierConfiguration magnifierConfiguration = TextMagnifierConfiguration.disabled, ValueChanged<SelectedContent?>? onSelectionChanged})
Create a new SelectableRegion widget.
const

Properties

child Widget
The child widget this selection area applies to.
final
contextMenuBuilder SelectableRegionContextMenuBuilder?
Builds the text selection toolbar when requested by the user.
final
focusNode FocusNode
An optional focus node to use as the focus node for this widget.
final
hashCode int
The hash code for this object.
no setterinherited
key Key?
Controls how one widget replaces another widget in the tree.
finalinherited
magnifierConfiguration TextMagnifierConfiguration
A configuration object for a magnifier.
final
onSelectionChanged ValueChanged<SelectedContent?>?
Called when the selected content changes.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
selectionControls TextSelectionControls
The delegate to build the selection handles and toolbar for mobile devices.
final

Methods

createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() State<StatefulWidget>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited

Static Methods

getSelectableButtonItems({required SelectionGeometry selectionGeometry, required VoidCallback onCopy, required VoidCallback onSelectAll}) List<ContextMenuButtonItem>
Returns the ContextMenuButtonItems representing the buttons in this platform's default selection menu.