RawScrollbarModifier class

An extendable base class for building scrollbars that fade in and out.

To add a scrollbar to a ScrollView, like a ListView or a CustomScrollView, wrap the scroll view widget in a RawScrollbar widget.

A scrollbar thumb indicates which portion of a ScrollView is actually visible.

By default, the thumb will fade in and out as the child scroll view scrolls. When thumbVisibility is true, the scrollbar thumb will remain visible without the fade animation. This requires that the ScrollController associated with the Scrollable widget is provided to controller, or that the PrimaryScrollController is being used by that Scrollable widget.

If the scrollbar is wrapped around multiple ScrollViews, it only responds to the nearest ScrollView and shows the corresponding scrollbar thumb by default. The notificationPredicate allows the ability to customize which ScrollNotifications the Scrollbar should listen to.

If the child ScrollView is infinitely long, the RawScrollbar will not be painted. In this case, the scrollbar cannot accurately represent the relative location of the visible area, or calculate the accurate delta to apply when dragging on the thumb or tapping on the track.

Interaction

Scrollbars are interactive and can use the PrimaryScrollController if a controller is not set. Interactive Scrollbar thumbs can be dragged along the main axis of the ScrollView to change the ScrollPosition. Tapping along the track exclusive of the thumb will trigger a ScrollIncrementType.page based on the relative position to the thumb.

When using the PrimaryScrollController, it must not be attached to more than one ScrollPosition. ScrollViews that have not been provided a ScrollController and have a ScrollView.scrollDirection of Axis.vertical will automatically attach their ScrollPosition to the PrimaryScrollController. Provide a unique ScrollController to each Scrollable in this case to prevent having multiple ScrollPositions attached to the PrimaryScrollController.

{@tool dartpad} This sample shows an app with two scrollables in the same route. Since by default, there is one PrimaryScrollController per route, and they both have a scroll direction of Axis.vertical, they would both try to attach to that controller on mobile platforms. The Scrollbar cannot support multiple positions attached to the same controller, so one ListView, and its Scrollbar have been provided a unique ScrollController. Desktop platforms do not automatically attach to the PrimaryScrollController, requiring ScrollView.primary to be true instead in order to use the PrimaryScrollController.

Alternatively, a new PrimaryScrollController could be created above one of the ListViews.

** See code in examples/api/lib/widgets/scrollbar/raw_scrollbar.0.dart ** {@end-tool}

Automatic Scrollbars on Desktop Platforms

Scrollbars are added to most Scrollable widgets by default on TargetPlatformVariant.desktop platforms. This is done through ScrollBehavior.buildScrollbar as part of an app's ScrollConfiguration. Scrollables that do not use the PrimaryScrollController or have a ScrollController provided to them will receive a unique ScrollController for use with the Scrollbar. In this case, only one Scrollable can be using the PrimaryScrollController, unless interactive is false. To prevent Axis.vertical Scrollables from using the PrimaryScrollController, set ScrollView.primary to false. Scrollable widgets that do not have automatically applied Scrollbars include

• EditableText
• ListWheelScrollView
• PageView
• NestedScrollView
• DropdownButton

Default Scrollbars can be disabled for the whole app by setting a ScrollBehavior with scrollbars set to false.

{@tool snippet}

MaterialApp(
  scrollBehavior: const MaterialScrollBehavior()
    .copyWith(scrollbars: false),
  home: Scaffold(
    appBar: AppBar(title: const Text('Home')),
  ),
)

{@end-tool}

{@tool dartpad} This sample shows how to disable the default Scrollbar for a Scrollable widget to avoid duplicate Scrollbars when running on desktop platforms.

** See code in examples/api/lib/widgets/scrollbar/raw_scrollbar.desktop.0.dart ** {@end-tool}

{@tool dartpad} This sample shows a RawScrollbar that executes a fade animation as scrolling occurs. The RawScrollbar will fade into view as the user scrolls, and fade out when scrolling stops. The GridView uses the PrimaryScrollController since it has an Axis.vertical scroll direction and has not been provided a ScrollController.

** See code in examples/api/lib/widgets/scrollbar/raw_scrollbar.1.dart ** {@end-tool}

{@tool dartpad} When thumbVisibility is true, the scrollbar thumb will remain visible without the fade animation. This requires that a ScrollController is provided to controller for both the RawScrollbar and the GridView. Alternatively, the PrimaryScrollController can be used automatically so long as it is attached to the singular ScrollPosition associated with the GridView.

** See code in examples/api/lib/widgets/scrollbar/raw_scrollbar.2.dart ** {@end-tool}

See also:

• ListView, which displays a linear, scrollable list of children.
• GridView, which displays a 2 dimensional, scrollable array of children.

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatelessWidget
• SingleChildStatelessModifier
• RawScrollbarModifier

Implementers

• CupertinoScrollbarModifier

Available extensions

• ModifierTransformer

Constructors

RawScrollbarModifier({Key? key, Widget? child, Key? modifierKey, ScrollController? controller, bool? thumbVisibility, OutlinedBorder? shape, Radius? radius, double? thickness, Color? thumbColor, double minThumbLength = _kMinThumbExtent, double? minOverscrollLength, bool? trackVisibility, Radius? trackRadius, Color? trackColor, Color? trackBorderColor, Duration fadeDuration = _kScrollbarFadeDuration, Duration timeToFade = _kScrollbarTimeToFade, Duration pressDuration = Duration.zero, ScrollNotificationPredicate notificationPredicate = defaultScrollNotificationPredicate, bool? interactive, ScrollbarOrientation? scrollbarOrientation, double mainAxisMargin = 0.0, double crossAxisMargin = 0.0, @Deprecated('Use thumbVisibility instead. ' 'This feature was deprecated after v2.9.0-1.0.pre.') bool? isAlwaysShown})

Creates a basic raw scrollbar that wraps the given child.

const

Properties

controller → ScrollController?

The ScrollController used to implement Scrollbar dragging.

final

crossAxisMargin → double

Distance from the scrollbar thumb side to the nearest cross axis edge in logical pixels.

final

fadeDuration → Duration

The Duration of the fade animation.

final

hashCode → int

The hash code for this object.

no setter, inherited

interactive → bool?

Whether the Scrollbar should be interactive and respond to dragging on the thumb, or tapping in the track area.

final

isAlwaysShown → bool?

Indicates that the scrollbar thumb should be visible, even when a scroll is not underway.

final

key → Key?

Controls how one widget replaces another widget in the tree.

final, inherited

mainAxisMargin → double

Distance from the scrollbar's start and end to the edge of the viewport in logical pixels. It affects the amount of available paint area.

final

minOverscrollLength → double?

The preferred smallest size the scrollbar thumb can shrink to when viewport is overscrolled.

final

minThumbLength → double

The preferred smallest size the scrollbar thumb can shrink to when the total scrollable extent is large, the current visible viewport is small, and the viewport is not overscrolled.

final

modifierKey → Key?

The actual key of the widget, which Modifier wrapped

final, inherited

notificationPredicate → ScrollNotificationPredicate

A check that specifies whether a ScrollNotification should be handled by this widget.

final

pressDuration → Duration

The Duration of time that a LongPress will trigger the drag gesture of the scrollbar thumb.

final

radius → Radius?

The Radius of the scrollbar thumb's rounded rectangle corners.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

scrollbarOrientation → ScrollbarOrientation?

Dictates the orientation of the scrollbar.

final

shape → OutlinedBorder?

The OutlinedBorder of the scrollbar's thumb.

final

thickness → double?

The thickness of the scrollbar in the cross axis of the scrollable.

final

thumbColor → Color?

The color of the scrollbar thumb.

final

thumbVisibility → bool?

Indicates that the scrollbar thumb should be visible, even when a scroll is not underway.

final

timeToFade → Duration

The Duration of time until the fade animation begins.

final

trackBorderColor → Color?

The color of the scrollbar track's border.

final

trackColor → Color?

The color of the scrollbar track.

final

trackRadius → Radius?

The Radius of the scrollbar track's rounded rectangle corners.

final

trackVisibility → bool?

Indicates that the scrollbar track should be visible.

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