add documentation and bump to version 0.3.0

letsar · letsar · commit 517ecf3b9387 · 2018-07-23T22:33:19.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,12 @@
+## 0.3.0
+## Added
+* The `closeOnTap` argument on slide actions to close when a action has been tapped.
+* The `closeOnScroll` argument on `Slidable` to close when the nearest `Scrollable` starts to scroll.
+* The static `Slidable.of` function.
+
+## Changed
+* The `dragExtent` field in `SlidableDelegateContext` has been changed to `dragSign`. 
+
 ## 0.2.0
 ### Added
 * `Slidable.builder` constructor.
diff --git a/README.md b/README.md
@@ -14,6 +14,8 @@ A Flutter implementation of slidable list item with left and right slide actions
 * 2 built-in slide action widget.
 * You can easily create you custom layouts and animations.
 * You can use a builder to create your slide actions if you want special effects during animation.
+* Close when a slide action has been tapped (overridable).
+* Close when the nearest `Scrollable` starts to scroll (overridable).
 
 ## Getting started
 
@@ -22,7 +24,7 @@ In the `pubspec.yaml` of your flutter project, add the following dependency:
 ```yaml
 dependencies:
   ...
-  flutter_slidable: "^0.2.0"
+  flutter_slidable: "^0.3.0"
 ```
 
 In your library add the following import:
@@ -52,7 +54,6 @@ A `direction` parameter let you choose if you want actions to appear when you sl
 
 ```dart
 new Slidable(
-  key: Key('$3'),
   delegate: new SlidableDrawerDelegate(),
   actionExtentRatio: 0.25,
   child: new Container(
@@ -133,6 +134,16 @@ The slide actions stretch while the item is sliding:
 
 ![Overview](https://raw.githubusercontent.com/letsar/flutter_slidable/master/doc/images/slidable_stretch.gif)
 
+#### How to prevent my slide action to close after it has been tapped?
+
+By default, `SlideAction` and `IconSlideAction` close on tap.
+To prevent this, you can set `false` to the `closeOnTap` constructor argument. 
+
+#### How to prevent my Slidable to close after my list scrolled?
+
+By default, a `Slidable` closes when the nearest `Scrollable` widget starts to scroll.
+To prevent this, you can set `false` to the `closeOnScroll` constructor argument. 
+
 ## Changelog
 
 Please see the [Changelog](https://github.com/letsar/flutter_slidable/blob/master/CHANGELOG.md) page to know what's recently changed.
diff --git a/lib/src/widgets/slidable.dart b/lib/src/widgets/slidable.dart
@@ -5,7 +5,8 @@ const double _kActionsExtentRatio = 0.25;
 const double _kFastThreshold = 2500.0;
 
 /// Signature for the builder callback used to create slide actions.
-typedef Widget SlideActionBuilder(BuildContext context, int index, Animation<double> animation);
+typedef Widget SlideActionBuilder(
+    BuildContext context, int index, Animation<double> animation);
 
 /// A delegate that supplies slide actions.
 ///
@@ -62,7 +63,8 @@ class SlideActionBuilderDelegate extends SlideActionDelegate {
   final int actionCount;
 
   @override
-  Widget build(BuildContext context, int index, Animation<double> animation) => builder(context, index, animation);
+  Widget build(BuildContext context, int index, Animation<double> animation) =>
+      builder(context, index, animation);
 }
 
 /// A delegate that supplies slide actions using an explicit list.
@@ -91,7 +93,8 @@ class SlideActionListDelegate extends SlideActionDelegate {
   int get actionCount => actions?.length ?? 0;
 
   @override
-  Widget build(BuildContext context, int index, Animation<double> animation) => actions[index];
+  Widget build(BuildContext context, int index, Animation<double> animation) =>
+      actions[index];
 }
 
 /// A handle to various properties useful while calling [SlidableDelegate.buildActions].
@@ -111,7 +114,8 @@ class SlidableDelegateContext {
   final Slidable slidable;
 
   /// The current actions that have to be shown.
-  SlideActionDelegate get actionDelegate => showActions ? slidable.actionDelegate : slidable.secondaryActionDelegate;
+  SlideActionDelegate get actionDelegate =>
+      showActions ? slidable.actionDelegate : slidable.secondaryActionDelegate;
 
   bool get directionIsXAxis => slidable.direction == Axis.horizontal;
 
@@ -129,7 +133,8 @@ class SlidableDelegateContext {
 
   /// Builds the slide actions using the active [SlideActionDelegate]'s builder.
   List<Widget> buildActions(BuildContext context) {
-    return List.generate(actionCount, (int index) => actionDelegate.build(context, index, controller.view));
+    return List.generate(actionCount,
+        (int index) => actionDelegate.build(context, index, controller.view));
   }
 
   Offset createOffset(double value) {
@@ -176,7 +181,8 @@ abstract class SlidableDelegate {
   const SlidableDelegate({
     double fastThreshold,
   })  : fastThreshold = fastThreshold ?? _kFastThreshold,
-        assert(fastThreshold == null || fastThreshold >= .0, 'fastThreshold must be positive');
+        assert(fastThreshold == null || fastThreshold >= .0,
+            'fastThreshold must be positive');
 
   /// The threshold used to know if a movement was fast and request to open/close the actions.
   final double fastThreshold;
@@ -243,10 +249,14 @@ class SlidableStrechDelegate extends SlidableStackDelegate {
                 children: <Widget>[
                   ctx.createPositioned(
                     position: 0.0,
-                    extent: ctx.getMaxExtent(constraints) * ctx.getAnimationValue(animation).abs(),
+                    extent: ctx.getMaxExtent(constraints) *
+                        ctx.getAnimationValue(animation).abs(),
                     child: new Flex(
                       direction: ctx.slidable.direction,
-                      children: ctx.buildActions(context).map((a) => Expanded(child: a)).toList(),
+                      children: ctx
+                          .buildActions(context)
+                          .map((a) => Expanded(child: a))
+                          .toList(),
                     ),
                   ),
                 ],
@@ -276,7 +286,10 @@ class SlidableBehindDelegate extends SlidableStackDelegate {
               extent: ctx.getMaxExtent(constraints) * ctx.totalActionsExtent,
               child: new Flex(
                 direction: ctx.slidable.direction,
-                children: ctx.buildActions(context).map((a) => Expanded(child: a)).toList(),
+                children: ctx
+                    .buildActions(context)
+                    .map((a) => Expanded(child: a))
+                    .toList(),
               ),
             ),
           ],
@@ -298,7 +311,8 @@ class SlidableScrollDelegate extends SlidableStackDelegate {
   Widget buildStackActions(BuildContext context, SlidableDelegateContext ctx) {
     return new Positioned.fill(
       child: new LayoutBuilder(builder: (context, constraints) {
-        final double totalExtent = ctx.getMaxExtent(constraints) * ctx.totalActionsExtent;
+        final double totalExtent =
+            ctx.getMaxExtent(constraints) * ctx.totalActionsExtent;
 
         final animation = new Tween(
           begin: ctx.createOffset(-totalExtent),
@@ -315,7 +329,10 @@ class SlidableScrollDelegate extends SlidableStackDelegate {
                     extent: totalExtent,
                     child: new Flex(
                       direction: ctx.slidable.direction,
-                      children: ctx.buildActions(context).map((a) => Expanded(child: a)).toList(),
+                      children: ctx
+                          .buildActions(context)
+                          .map((a) => Expanded(child: a))
+                          .toList(),
                     ),
                   ),
                 ],
@@ -339,7 +356,8 @@ class SlidableDrawerDelegate extends SlidableStackDelegate {
     return new Positioned.fill(
       child: new LayoutBuilder(builder: (context, constraints) {
         final count = ctx.actionCount;
-        final double actionExtent = ctx.getMaxExtent(constraints) * ctx.slidable.actionExtentRatio;
+        final double actionExtent =
+            ctx.getMaxExtent(constraints) * ctx.slidable.actionExtentRatio;
 
         final animations = Iterable.generate(count).map((index) {
           return new Tween(
@@ -354,11 +372,13 @@ class SlidableDrawerDelegate extends SlidableStackDelegate {
               return new Stack(
                 children: List.generate(ctx.actionCount, (index) {
                   // For the main actions we have to reverse the order if we want the last item at the bottom of the stack.
-                  int displayIndex = ctx.showActions ? ctx.actionCount - index - 1 : index;
+                  int displayIndex =
+                      ctx.showActions ? ctx.actionCount - index - 1 : index;
                   return ctx.createPositioned(
                     position: ctx.getAnimationValue(animations[index]),
                     extent: actionExtent,
-                    child: ctx.actionDelegate.build(context, displayIndex, ctx.controller.view),
+                    child: ctx.actionDelegate
+                        .build(context, displayIndex, ctx.controller.view),
                   );
                 }),
               );
@@ -398,7 +418,8 @@ class Slidable extends StatefulWidget {
           child: child,
           delegate: delegate,
           actionDelegate: new SlideActionListDelegate(actions: actions),
-          secondaryActionDelegate: new SlideActionListDelegate(actions: secondaryActions),
+          secondaryActionDelegate:
+              new SlideActionListDelegate(actions: secondaryActions),
           showAllActionsThreshold: showAllActionsThreshold,
           actionExtentRatio: actionExtentRatio,
           movementDuration: movementDuration,
@@ -426,9 +447,16 @@ class Slidable extends StatefulWidget {
     this.closeOnScroll = true,
   })  : assert(delegate != null),
         assert(direction != null),
-        assert(showAllActionsThreshold != null && showAllActionsThreshold >= .0 && showAllActionsThreshold <= 1.0,
+        assert(
+            showAllActionsThreshold != null &&
+                showAllActionsThreshold >= .0 &&
+                showAllActionsThreshold <= 1.0,
             'showAllActionsThreshold must be between 0.0 and 1.0'),
-        assert(actionExtentRatio != null && actionExtentRatio >= .0 && actionExtentRatio <= 1.0, 'actionExtentRatio must be between 0.0 and 1.0'),
+        assert(
+            actionExtentRatio != null &&
+                actionExtentRatio >= .0 &&
+                actionExtentRatio <= 1.0,
+            'actionExtentRatio must be between 0.0 and 1.0'),
         assert(closeOnScroll != null),
         super(key: key);
 
@@ -476,11 +504,14 @@ class Slidable extends StatefulWidget {
   SlidableState createState() => SlidableState();
 }
 
-class SlidableState extends State<Slidable> with TickerProviderStateMixin, AutomaticKeepAliveClientMixin<Slidable> {
+class SlidableState extends State<Slidable>
+    with TickerProviderStateMixin, AutomaticKeepAliveClientMixin<Slidable> {
   @override
   void initState() {
     super.initState();
-    _controller = new AnimationController(duration: widget.movementDuration, vsync: this)..addStatusListener(_handleShowAllActionsStatusChanged);
+    _controller =
+        new AnimationController(duration: widget.movementDuration, vsync: this)
+          ..addStatusListener(_handleShowAllActionsStatusChanged);
   }
 
   AnimationController _controller;
@@ -494,17 +525,22 @@ class SlidableState extends State<Slidable> with TickerProviderStateMixin, Autom
   }
 
   @override
-  bool get wantKeepAlive => _controller != null && (_controller.isAnimating || _controller.isCompleted);
+  bool get wantKeepAlive =>
+      _controller != null &&
+      (_controller.isAnimating || _controller.isCompleted);
 
   /// The current actions that have to be shown.
-  SlideActionDelegate get actionDelegate => _showActions ? widget.actionDelegate : widget.secondaryActionDelegate;
+  SlideActionDelegate get actionDelegate =>
+      _showActions ? widget.actionDelegate : widget.secondaryActionDelegate;
 
   bool get _directionIsXAxis {
     return widget.direction == Axis.horizontal;
   }
 
   double get _overallDragAxisExtent {
-    return (_directionIsXAxis ? context.size.width : context.size.height) * widget.actionExtentRatio * (actionDelegate?.actionCount ?? 0);
+    return (_directionIsXAxis ? context.size.width : context.size.height) *
+        widget.actionExtentRatio *
+        (actionDelegate?.actionCount ?? 0);
   }
 
   @override
@@ -527,7 +563,8 @@ class SlidableState extends State<Slidable> with TickerProviderStateMixin, Autom
   void _addScrollingNotifierListener() {
     if (widget.closeOnScroll) {
       _scrollPosition = Scrollable.of(context)?.position;
-      if (_scrollPosition != null) _scrollPosition.isScrollingNotifier.addListener(_isScrollingListener);
+      if (_scrollPosition != null)
+        _scrollPosition.isScrollingNotifier.addListener(_isScrollingListener);
     }
   }
 
@@ -580,7 +617,8 @@ class SlidableState extends State<Slidable> with TickerProviderStateMixin, Autom
     final double velocity = details.primaryVelocity;
     final bool shouldOpen = velocity.sign == _dragExtent.sign;
     final bool fast = velocity.abs() > widget.delegate.fastThreshold;
-    if (_controller.value >= widget.showAllActionsThreshold || (shouldOpen && fast)) {
+    if (_controller.value >= widget.showAllActionsThreshold ||
+        (shouldOpen && fast)) {
       open();
     } else {
       close();
@@ -599,15 +637,21 @@ class SlidableState extends State<Slidable> with TickerProviderStateMixin, Autom
   Widget build(BuildContext context) {
     super.build(context); // See AutomaticKeepAliveClientMixin.
 
-    if ((widget.actionDelegate == null || widget.actionDelegate.actionCount == 0) &&
-        (widget.secondaryActionDelegate == null || widget.secondaryActionDelegate.actionCount == 0)) {
+    if ((widget.actionDelegate == null ||
+            widget.actionDelegate.actionCount == 0) &&
+        (widget.secondaryActionDelegate == null ||
+            widget.secondaryActionDelegate.actionCount == 0)) {
       return widget.child;
     }
 
     Widget content = widget.child;
 
-    if (_showActions && widget.actionDelegate != null && widget.actionDelegate.actionCount > 0 ||
-        !_showActions && widget.secondaryActionDelegate != null && widget.secondaryActionDelegate.actionCount > 0) {
+    if (_showActions &&
+            widget.actionDelegate != null &&
+            widget.actionDelegate.actionCount > 0 ||
+        !_showActions &&
+            widget.secondaryActionDelegate != null &&
+            widget.secondaryActionDelegate.actionCount > 0) {
       content = widget.delegate.buildActions(
         context,
         new SlidableDelegateContext(
diff --git a/lib/src/widgets/slide_action.dart b/lib/src/widgets/slide_action.dart
@@ -6,7 +6,8 @@ const bool _kCloseOnTap = true;
 
 /// Abstract class for slide actions that can close after [onTap] occurred.
 abstract class ClosableSlideAction extends StatelessWidget {
-  /// Creates a slide that closes when a tap has occurred if [closeOnTap] is [true].
+  /// Creates a slide that closes when a tap has occurred if [closeOnTap]
+  /// is [true].
   ///
   /// The [closeOnTap] argument must not be null.
   const ClosableSlideAction({
@@ -24,7 +25,8 @@ abstract class ClosableSlideAction extends StatelessWidget {
   /// Defaults to true.
   final bool closeOnTap;
 
-  /// Calls [onTap] if not null and closes the closest [Slidable] that encloses the given context.
+  /// Calls [onTap] if not null and closes the closest [Slidable]
+  /// that encloses the given context.
   void _handleCloseAfterTap(BuildContext context) {
     if (onTap != null) {
       onTap();
@@ -68,7 +70,8 @@ class SlideAction extends ClosableSlideAction {
             color == null || decoration == null,
             'Cannot provide both a color and a decoration\n'
             'The color argument is just a shorthand for "decoration: new BoxDecoration(color: color)".'),
-        decoration = decoration ?? (color != null ? new BoxDecoration(color: color) : null),
+        decoration = decoration ??
+            (color != null ? new BoxDecoration(color: color) : null),
         super(
           key: key,
           onTap: onTap,
@@ -121,11 +124,18 @@ class IconSlideAction extends ClosableSlideAction {
 
   @override
   Widget buildAction(BuildContext context) {
-    final Color foregroundColor = ThemeData.estimateBrightnessForColor(color) == Brightness.light ? Colors.black : Colors.white;
+    final Color foregroundColor =
+        ThemeData.estimateBrightnessForColor(color) == Brightness.light
+            ? Colors.black
+            : Colors.white;
     final Text textWidget = new Text(
       caption ?? '',
       overflow: TextOverflow.ellipsis,
-      style: Theme.of(context).primaryTextTheme.caption.copyWith(color: foregroundColor),
+      style: Theme
+          .of(context)
+          .primaryTextTheme
+          .caption
+          .copyWith(color: foregroundColor),
     );
     return Container(
       color: color,
diff --git a/pubspec.yaml b/pubspec.yaml
@@ -1,6 +1,6 @@
 name: flutter_slidable
 description: A Flutter implementation of slidable list item with directional slide actions.
-version: 0.2.0
+version: 0.3.0
 author: Romain Rastel <lets4r@gmail.com>
 homepage: https://github.com/letsar/flutter_slidable
 
