SelectableRegionModifier class
A widget that introduces an area for user selections.
Flutter widgets are not selectable by default. To enable selection for a Flutter application, consider wrapping a portion of widget subtree with SelectableRegion. 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.
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:
{@tool snippet}
MaterialApp(
home: SelectableRegion(
selectionControls: materialTextSelectionControls,
focusNode: 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)),
],
),
),
),
)
{@end-tool}
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.
{@tool dartpad} This sample demonstrates how to create an adapter widget that makes any child widget selectable.
** See code in examples/api/lib/material/selection_area/custom_selectable.dart ** {@end-tool}
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.
{@tool dartpad} This sample demonstrates how to create a SelectionContainer that only allows selecting everything or nothing with no partial selection.
** See code in examples/api/lib/material/selection_area/custom_container.dart ** {@end-tool}
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.
{@tool dartpad} This sample demonstrates how to disable selection for a Text in a Column.
** See code in examples/api/lib/material/selection_area/disable_partial_selection.dart ** {@end-tool}
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.
See also:
- SelectionArea, which creates a SelectableRegion with platform-adaptive selection controls.
- SelectionHandler, which contains APIs to handle selection events from the SelectableRegion.
- Selectable, which provides API to participate in the selection system.
- SelectionRegistrar, which Selectable needs to subscribe to receive selection events.
- SelectionContainer, which collects selectable widgets in the subtree and provides api to dispatch selection event to the collected widget.
- Inheritance
-
- Object
- DiagnosticableTree
- Widget
- StatelessWidget
- SingleChildStatelessModifier
- SelectableRegionModifier
- Available extensions
Constructors
- SelectableRegionModifier({Key? key, Key? modifierKey, Widget? child, required FocusNode focusNode, required TextSelectionControls selectionControls})
-
Create a new SelectableRegion widget.
const
Properties
- 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
- modifierKey → Key?
-
The actual key of the widget, which Modifier wrapped
finalinherited
- 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
-
build(
BuildContext context) → Widget -
Describes the part of the user interface represented by this widget.
inherited
-
buildWithChild(
BuildContext context, Widget? child) → Widget -
A build method that receives an extra
child
parameter.override -
createElement(
) → SingleChildStatelessElement -
Create a SingleChildStatelessElement
inherited
-
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