diff --git a/README.md b/README.md index 76ab01f..5081f99 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ Customize the threshold (when the card should slide away) ## Installation Add this to your package's `pubspec.yaml` file: + ```yaml card_swiper: ... ``` @@ -47,6 +48,7 @@ card_swiper: ... ```yaml flutter pub add flutter_card_swiper ``` + in your project's root directory. ## Usage @@ -91,40 +93,41 @@ class Example extends StatelessWidget { ``` ## Constructor + #### Basic -| Parameter | Default | Description | Required | -| ------------- |:-------------|:-----|:-----:| -| cardBuilder | - | Widget builder for rendering cards | true -| cardsCount | - | Cards count | true -| initialIndex | 0 | index of the first card when the swiper is initialized | false -| controller | - | Trigger swipe | false -| padding | EdgeInsets.symmetric(horizontal: 20, vertical: 25) | Control swiper padding | false -| duration | 200 milliseconds | The duration that every animation should last | false -| maxAngle | 30 | Maximum angle the card reaches while swiping | false -| threshold | 50 | Threshold from which the card is swiped away | false -| scale | 0.9 | Scale of the card that is behind the front card | false -| isDisabled | false | Set to ```true``` if swiping should be disabled, has no impact when triggered from the outside | false -| isHorizontalSwipingEnabled | true | Set to ```false``` if you want your card to move only across the vertical axis when swiping | false -| isVerticalSwipingEnabled | true | Set to ```false``` if you want your card to move only across the horizontal axis when swiping | false -| isLoop | true | set to ```true``` if the stack should loop | false -| onTapDisabled | - | Function that get triggered when the swiper is disabled | false -| onSwipe | - | Called with the oldIndex, newIndex and detected swipe direction when the user swiped. If [onSwipe] returns ```false```, the swipe action will be canceled. Otherwise, if it returns ```true```, the swipe action will be performed as expected. | false -| onEnd | - | Called when there is no Widget left to be swiped away | false -| direction | right | Direction in which the card is swiped away when triggered from the outside | false -| numberOfCardsDisplayed | 2 | If your widgets in the 'cards' list cause performance issues, you can choose to display more cards at a time to reduce how long the user waits for a card to appear | false +| Parameter | Default | Description | Required | +| -------------------------- | :------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | +| cardBuilder | - | Widget builder for rendering cards | true | +| cardsCount | - | Number of cards | true | +| initialIndex | 0 | Index of the first card when the swiper is initialized | false | +| controller | - | Trigger swipe | false | +| padding | EdgeInsets.symmetric(horizontal: 20, vertical: 25) | Controller to trigger swipe actions | false | +| duration | 200 milliseconds | The duration that every animation should last | false | +| maxAngle | 30 | Maximum angle that the card can reach during swiping | false | +| threshold | 50 | Threshold from which the card is swiped away | false | +| scale | 0.9 | Scale of the card that is behind the front card | false | +| isDisabled | false | Set to `true` if swiping should be disabled, has no impact when triggered from the outside | false | +| isHorizontalSwipingEnabled | true | Set to `false` if you want your card to move only across the vertical axis when swiping | false | +| isVerticalSwipingEnabled | true | Set to `false` if you want your card to move only across the horizontal axis when swiping | false | +| isLoop | true | Set to `true` if the stack should loop | false | +| onTapDisabled | - | Function that get triggered when the swiper is disabled | false | +| onSwipe | - | Function that is called when the user swipes a card. If the function returns `false`, the swipe action is canceled. If it returns `true`, the swipe action is performed as expected | false | +| onEnd | - | Function that is called when there are no more cards left to swipe | false | +| direction | right | Direction in which the card is swiped away when triggered from the outside | false | +| numberOfCardsDisplayed | 2 | Number of cards to display at a time | false | #### Controller -The ```Controller``` is used to swipe the card from outside of the widget. You can create a controller called ```CardSwiperController``` and save the instance for further usage. Please have a closer look at our Example for the usage. +The `Controller` is used to swipe the card from outside of the widget. You can create a controller called `CardSwiperController` and save the instance for further usage. Please have a closer look at our Example for the usage. -| Method | Description -| ------------- |:------------- -| swipe | Changes the state of the controller to swipe and swipes the card in your selected direction. -| swipeLeft | Changes the state of the controller to swipe left and swipes the card to the left side. -| swipeRight | Changes the state of the controller to swipe right and swipes the card to the right side. -| swipeTop | Changes the state of the controller to swipe top and swipes the card to the top side. -| swipeBottom | Changes the state of the controller to swipe bottom and swipes the card to the | swipeBottom | Changes the state of the controller to swipe bottom and swipes the card to the right side. +| Method | Description | +| ----------- | :------------------------------------------------------------------------------------------- | +| swipe | Changes the state of the controller to swipe and swipes the card in your selected direction. | +| swipeLeft | Changes the state of the controller to swipe left and swipes the card to the left side. | +| swipeRight | Changes the state of the controller to swipe right and swipes the card to the right side. | +| swipeTop | Changes the state of the controller to swipe top and swipes the card to the top side. | +| swipeBottom | Changes the state of the controller to swipe bottom and swipes the card to the bottom side. |
diff --git a/lib/flutter_card_swiper.dart b/lib/flutter_card_swiper.dart index 02eebf1..9db9166 100644 --- a/lib/flutter_card_swiper.dart +++ b/lib/flutter_card_swiper.dart @@ -1,3 +1,8 @@ +/// A Tinder-like card swiper package. It allows you to swipe left, right, up, +/// and down and define your own business logic for each direction. Very smooth +/// animations supporting Android, iOS, Web & Desktop. +library flutter_card_swiper; + export 'package:flutter_card_swiper/src/card_swiper.dart'; export 'package:flutter_card_swiper/src/card_swiper_controller.dart'; export 'package:flutter_card_swiper/src/enums.dart'; diff --git a/lib/src/card_swiper.dart b/lib/src/card_swiper.dart index c2f61dc..af92b1a 100644 --- a/lib/src/card_swiper.dart +++ b/lib/src/card_swiper.dart @@ -7,61 +7,93 @@ import 'package:flutter_card_swiper/src/extensions.dart'; import 'package:flutter_card_swiper/src/typedefs.dart'; class CardSwiper extends StatefulWidget { - /// widget builder for rendering cards + /// Function that builds each card in the stack. + /// + /// The [int] parameter specifies the index of the card to build, and the [BuildContext] + /// parameter provides the build context. The function should return a widget that represents + /// the card at the given index. It can return `null`, which will result in an + /// empty card being displayed. final NullableIndexedWidgetBuilder cardBuilder; - /// cards count + /// The number of cards in the stack. + /// + /// The [cardsCount] parameter specifies the number of cards that will be displayed in the stack. + /// + /// This parameter is required and must be greater than 0. final int cardsCount; - /// index of the first card when the swiper is initialized + /// The index of the card to display initially. + /// + /// Defaults to 0, meaning the first card in the stack is displayed initially. final int initialIndex; - /// controller to trigger actions + /// The [CardSwiperController] used to control the swiper externally. + /// + /// If `null`, the swiper can only be controlled by user input. final CardSwiperController? controller; - /// duration of every animation + /// The duration of each swipe animation. + /// + /// Defaults to 200 milliseconds. final Duration duration; - /// padding of the swiper + /// The padding around the swiper. + /// + /// Defaults to `EdgeInsets.symmetric(horizontal: 20, vertical: 25)`. final EdgeInsetsGeometry padding; - /// maximum angle the card reaches while swiping + /// The maximum angle the card reaches while swiping. + /// + /// Must be between 0 and 360 degrees. Defaults to 30 degrees. final double maxAngle; - /// threshold from which the card is swiped away + /// The threshold from which the card is swiped away. + /// + /// Must be between 1 and 100 percent of the card width. Defaults to 50 percent. final int threshold; - /// scale of the card that is behind the front card + /// The scale of the card that is behind the front card. + /// + /// Must be between 0 and 1. Defaults to 0.9. final double scale; - /// set to true if swiping should be disabled, exception: triggered from the outside + /// Whether swiping is disabled. + /// + /// If `true`, swiping is disabled, except when triggered by the [controller]. + /// + /// Defaults to `false`. final bool isDisabled; - /// function that gets called with the new index and detected swipe direction when the user swiped or swipe is triggered by controller + /// Callback function that is called when a swipe action is performed. /// - /// If [onSwipe] returns false, the swipe action will be canceled and the current card will remain on top of the stack. - /// Otherwise, if it returns true, the swipe action will be performed as expected. + /// The function is called with the oldIndex, the currentIndex and the direction of the swipe. + /// If the function returns `false`, the swipe action is canceled and the current card remains + /// on top of the stack. If the function returns `true`, the swipe action is performed as expected. final CardSwiperOnSwipe? onSwipe; - /// function that gets called when there is no widget left to be swiped away + /// Callback function that is called when there are no more cards to swipe. final CardSwiperOnEnd? onEnd; - /// function that gets triggered when the swiper is disabled + /// Callback function that is called when the swiper is disabled. final CardSwiperOnTapDisabled? onTapDisabled; - /// direction in which the card gets swiped when triggered by controller, default set to right + /// The direction in which the card is swiped when triggered by the [controller]. + /// + /// Defaults to [CardSwiperDirection.right]. final CardSwiperDirection direction; - /// set to false if you want your card to move only across the vertical axis when swiping + /// A boolean value that determines whether the card can be swiped horizontally. The default value is true. final bool isHorizontalSwipingEnabled; - /// set to false if you want your card to move only across the horizontal axis when swiping + /// A boolean value that determines whether the card can be swiped vertically. The default value is true. final bool isVerticalSwipingEnabled; - /// set to true if the stack should loop + /// A boolean value that determines whether the card stack should loop. When the last card is swiped, + /// if isLoop is true, the first card will become the last card again. The default value is true. final bool isLoop; - /// here you can change the number of cards that are displayed at the same time + /// An integer that determines the number of cards that are displayed at the same time. + /// The default value is 2. Note that you must display at least one card, and no more than the [cardsCount] parameter. final int numberOfCardsDisplayed; const CardSwiper({ diff --git a/lib/src/card_swiper_controller.dart b/lib/src/card_swiper_controller.dart index 8e3e84d..fc0c1c6 100644 --- a/lib/src/card_swiper_controller.dart +++ b/lib/src/card_swiper_controller.dart @@ -1,35 +1,35 @@ import 'package:flutter/foundation.dart'; import 'package:flutter_card_swiper/src/enums.dart'; -//to call the swipe function from outside of the CardSwiper +/// A controller that can be used to trigger swipes on a CardSwiper widget. class CardSwiperController extends ChangeNotifier { CardSwiperState? state; - //swipe the card by changing the status of the controller + /// Swipe the card by changing the status of the controller void swipe() { state = CardSwiperState.swipe; notifyListeners(); } - //swipe the card to the left side by changing the status of the controller + /// Swipe the card to the left side by changing the status of the controller void swipeLeft() { state = CardSwiperState.swipeLeft; notifyListeners(); } - //swipe the card to the right side by changing the status of the controller + /// Swipe the card to the right side by changing the status of the controller void swipeRight() { state = CardSwiperState.swipeRight; notifyListeners(); } - //swipe the card to the top side by changing the status of the controller + /// Swipe the card to the top side by changing the status of the controller void swipeTop() { state = CardSwiperState.swipeTop; notifyListeners(); } - //swipe the card to the bottom side by changing the status of the controller + /// Swipe the card to the bottom side by changing the status of the controller void swipeBottom() { state = CardSwiperState.swipeBottom; notifyListeners(); diff --git a/pubspec.yaml b/pubspec.yaml index 77e6384..bdfa544 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -2,7 +2,7 @@ name: flutter_card_swiper description: This is a Tinder-like card swiper package. It allows you to swipe left, right, up, and down and define your own business logic for each direction. homepage: https://github.com/ricardodalarme/flutter_card_swiper issue_tracker: https://github.com/ricardodalarme/flutter_card_swiper/issues -version: 4.0.0 +version: 4.0.0+1 environment: sdk: ">=2.12.0 <3.0.0"