j3g
/
f_card_swiper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: improve documentation

This commit is contained in:
ricardodalarme 2023-03-23 23:10:34 -03:00
parent 3d74bcedb2
commit 33915ff416
5 changed files with 95 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
README.md
View File

@ -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. |
<hr/>

5
lib/flutter_card_swiper.dart
View File

@ -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';

72
lib/src/card_swiper.dart
View File

@ -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({

12
lib/src/card_swiper_controller.dart
View File

@ -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();

2
pubspec.yaml
View File

@ -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"