InkWellModifier class

A rectangular area of a Material that responds to touch.

For a variant of this widget that does not clip splashes, see InkResponse.

The following diagram shows how an InkWell looks when tapped, when using default values.

The InkWell widget must have a Material widget as an ancestor. The Material widget is where the ink reactions are actually painted. This matches the Material Design premise wherein the Material is what is actually reacting to touches by spreading ink.

If a Widget uses this class directly, it should include the following line at the top of its build function to call debugCheckHasMaterial:

assert(debugCheckHasMaterial(context));

Troubleshooting

The ink splashes aren't visible!

If there is an opaque graphic, e.g. painted using a Container, Image, or DecoratedBox, between the Material widget and the InkWell widget, then the splash won't be visible because it will be under the opaque graphic. This is because ink splashes draw on the underlying Material itself, as if the ink was spreading inside the material.

The Ink widget can be used as a replacement for Image, Container, or DecoratedBox to ensure that the image or decoration also paints in the Material itself, below the ink.

If this is not possible for some reason, e.g. because you are using an opaque CustomPaint widget, alternatively consider using a second Material above the opaque widget but below the InkWell (as an ancestor to the ink well). The MaterialType.transparency material kind can be used for this purpose.

InkWell isn't clipping properly

If you want to clip an InkWell or any Ink widgets you need to keep in mind that the Material that the Ink will be printed on is responsible for clipping. This means you can't wrap the Ink widget in a clipping widget directly, since this will leave the Material not clipped (and by extension the printed Ink widgets as well).

An easy solution is to deliberately wrap the Ink widgets you want to clip in a Material, and wrap that in a clipping widget instead. See Ink for an example.

The ink splashes don't track the size of an animated container

If the size of an InkWell's Material ancestor changes while the InkWell's splashes are expanding, you may notice that the splashes aren't clipped correctly. This can't be avoided.

An example of this situation is as follows:

{@tool dartpad} Tap the container to cause it to grow. Then, tap it again and hold before the widget reaches its maximum size to observe the clipped ink splash.

** See code in examples/api/lib/material/ink_well/ink_well.0.dart ** {@end-tool}

An InkWell's splashes will not properly update to conform to changes if the size of its underlying Material, where the splashes are rendered, changes during animation. You should avoid using InkWells within Material widgets that are changing size.

See also:

• GestureDetector, for listening for gestures without ink splashes.
• ElevatedButton and TextButton, two kinds of buttons in Material Design.
• InkResponse, a variant of InkWell that doesn't force a rectangular shape on the ink reaction.

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatelessWidget
• SingleChildStatelessModifier
• InkResponseModifier
• InkWellModifier

Available extensions

• ModifierTransformer

Constructors

InkWellModifier({Key? key, Key? modifierKey, Widget? child, GestureTapCallback? onTap, GestureTapCallback? onDoubleTap, GestureLongPressCallback? onLongPress, GestureTapDownCallback? onTapDown, GestureTapUpCallback? onTapUp, GestureTapCallback? onTapCancel, ValueChanged<bool>? onHighlightChanged, ValueChanged<bool>? onHover, MouseCursor? mouseCursor, Color? focusColor, Color? hoverColor, Color? highlightColor, MaterialStateProperty<Color?>? overlayColor, Color? splashColor, InteractiveInkFeatureFactory? splashFactory, double? radius, BorderRadius? borderRadius, ShapeBorder? customBorder, bool? enableFeedback = true, bool excludeFromSemantics = false, FocusNode? focusNode, bool canRequestFocus = true, ValueChanged<bool>? onFocusChange, bool autofocus = false, MaterialStatesController? statesController})

Creates an ink well.

const

Properties

autofocus → bool

True if this widget will be selected as the initial focus when no other node in its scope is currently focused.

final, inherited

borderRadius → BorderRadius?

The clipping radius of the containing rect. This is effective only if customBorder is null.

final, inherited

canRequestFocus → bool

If true, this widget may request the primary focus.

final, inherited

containedInkWell → bool

Whether this ink response should be clipped its bounds.

final, inherited

customBorder → ShapeBorder?

The custom clip border which overrides borderRadius.

final, inherited

enableFeedback → bool

Whether detected gestures should provide acoustic and/or haptic feedback.

final, inherited

excludeFromSemantics → bool

Whether to exclude the gestures introduced by this widget from the semantics tree.

final, inherited

focusColor → Color?

The color of the ink response when the parent widget is focused. If this property is null then the focus color of the theme, ThemeData.focusColor, will be used.

final, inherited

focusNode → FocusNode?

An optional focus node to use as the focus node for this widget.

final, inherited

hashCode → int

The hash code for this object.

no setter, inherited

highlightColor → Color?

The highlight color of the ink response when pressed. If this property is null then the highlight color of the theme, ThemeData.highlightColor, will be used.

final, inherited

highlightShape → BoxShape

The shape (e.g., circle, rectangle) to use for the highlight drawn around this part of the material when pressed, hovered over, or focused.

final, inherited

hoverColor → Color?

The color of the ink response when a pointer is hovering over it. If this property is null then the hover color of the theme, ThemeData.hoverColor, will be used.

final, inherited

key → Key?

Controls how one widget replaces another widget in the tree.

final, inherited

modifierKey → Key?

The actual key of the widget, which Modifier wrapped

final, inherited

mouseCursor → MouseCursor?

The cursor for a mouse pointer when it enters or is hovering over the widget.

final, inherited

onDoubleTap → GestureTapCallback?

Called when the user double taps this part of the material.

final, inherited

onFocusChange → ValueChanged<bool>?

Handler called when the focus changes.

final, inherited

onHighlightChanged → ValueChanged<bool>?

Called when this part of the material either becomes highlighted or stops being highlighted.

final, inherited

onHover → ValueChanged<bool>?

Called when a pointer enters or exits the ink response area.

final, inherited

onLongPress → GestureLongPressCallback?

Called when the user long-presses on this part of the material.

final, inherited

onTap → GestureTapCallback?

Called when the user taps this part of the material.

final, inherited

onTapCancel → GestureTapCallback?

Called when the user cancels a tap that was started on this part of the material.

final, inherited

onTapDown → GestureTapDownCallback?

Called when the user taps down this part of the material.

final, inherited

onTapUp → GestureTapUpCallback?

Called when the user releases a tap that was started on this part of the material. onTap is called immediately after.

final, inherited

overlayColor → MaterialStateProperty<Color?>?

Defines the ink response focus, hover, and splash colors.

final, inherited

radius → double?

The radius of the ink splash.

final, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

splashColor → Color?

The splash color of the ink response. If this property is null then the splash color of the theme, ThemeData.splashColor, will be used.

final, inherited

splashFactory → InteractiveInkFeatureFactory?

Defines the appearance of the splash.

final, inherited

statesController → MaterialStatesController?

Represents the interactive "state" of this widget in terms of a set of WidgetStates, like WidgetState.pressed and WidgetState.focused.

final, inherited

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.

inherited

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

modified() → Modifier

Available on Widget, provided by the ModifierTransformer extension

Transform normal widget to Modifier

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, int wrapWidth = 65}) → 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