From dd45f1d9ce674706fa5075008f885a510bbdd5d0 Mon Sep 17 00:00:00 2001 From: Vick Top Date: Mon, 19 Feb 2024 16:53:21 +0100 Subject: [PATCH] doc: create documentation for file --- README.md | 2 +- .../lib/flutter_introduction.dart | 9 ++++ .../lib/src/introduction_interface.dart | 15 ++++++ .../lib/src/local_introduction.dart | 8 +++ .../lib/src/introduction_service.dart | 21 ++++++++ ...utter_introduction_shared_preferences.dart | 11 ++++ .../lib/src/types/page_introduction.dart | 50 ++++++++++++++++++- .../lib/src/types/single_introduction.dart | 3 ++ .../lib/src/widgets/background.dart | 5 ++ .../lib/src/widgets/indicator.dart | 29 ++++++++--- .../lib/src/widgets/page_content.dart | 11 ++++ 11 files changed, 155 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 2a71b0e..7dd3563 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Please file any issues, bugs or feature request as an issue on our [GitHub](http ## Want to contribute -If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our [contribution guide](../CONTRIBUTING.md) and send us your [pull request](https://github.com/Iconica-Development/flutter_introduction/pulls). +If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our [contribution guide](./CONTRIBUTING.md) and send us your [pull request](https://github.com/Iconica-Development/flutter_introduction/pulls). ## Author diff --git a/packages/flutter_introduction/lib/flutter_introduction.dart b/packages/flutter_introduction/lib/flutter_introduction.dart index fc7965c..a45d215 100644 --- a/packages/flutter_introduction/lib/flutter_introduction.dart +++ b/packages/flutter_introduction/lib/flutter_introduction.dart @@ -19,10 +19,19 @@ class Introduction extends StatefulWidget { super.key, }); + /// Callback function to navigate to the next screen. final VoidCallback navigateTo; + + /// The introduction service to use. final IntroductionService? service; + + /// Options for configuring the introduction screen. final IntroductionOptions options; + + /// The scrolling physics for the introduction screen. final ScrollPhysics? physics; + + /// Child widget to display. final Widget? child; @override diff --git a/packages/flutter_introduction_interface/lib/src/introduction_interface.dart b/packages/flutter_introduction_interface/lib/src/introduction_interface.dart index 6fa3020..5a72f26 100644 --- a/packages/flutter_introduction_interface/lib/src/introduction_interface.dart +++ b/packages/flutter_introduction_interface/lib/src/introduction_interface.dart @@ -6,20 +6,35 @@ import 'package:flutter_data_interface/flutter_data_interface.dart'; import 'package:flutter_introduction_interface/src/local_introduction.dart'; abstract class IntroductionInterface extends DataInterface { + /// Constructs an instance of [IntroductionInterface]. + /// + /// The [token] is used for verification purposes. IntroductionInterface() : super(token: _token); static final Object _token = Object(); static IntroductionInterface _instance = LocalIntroductionDataProvider(); + /// Retrieves the current instance of [IntroductionInterface]. static IntroductionInterface get instance => _instance; + /// Sets the current instance of [IntroductionInterface]. + /// + /// Throws an error if the provided instance does not match the token. static set instance(IntroductionInterface instance) { DataInterface.verify(instance, _token); _instance = instance; } + /// Sets whether the introduction is completed or not. + /// + /// The [value] parameter specifies whether the introduction is completed. + /// By default, it is set to `true`. Future setCompleted({bool value = true}); + /// Checks if the introduction should be shown. + /// + /// Returns `true` if the introduction should be shown; + /// otherwise, returns `false`. Future shouldShow(); } diff --git a/packages/flutter_introduction_interface/lib/src/local_introduction.dart b/packages/flutter_introduction_interface/lib/src/local_introduction.dart index ce8fb6e..71b93d8 100644 --- a/packages/flutter_introduction_interface/lib/src/local_introduction.dart +++ b/packages/flutter_introduction_interface/lib/src/local_introduction.dart @@ -4,9 +4,17 @@ import 'package:flutter_introduction_interface/src/introduction_interface.dart'; +/// Provides local data storage for managing introduction data. +/// +/// This class extends [IntroductionInterface] and implements methods to manage +/// introduction data locally. class LocalIntroductionDataProvider extends IntroductionInterface { + /// Constructs an instance of [LocalIntroductionDataProvider]. + /// + /// Initializes the [hasViewed] flag to `false`. LocalIntroductionDataProvider(); + /// Flag indicating whether the introduction has been viewed or not. bool hasViewed = false; @override diff --git a/packages/flutter_introduction_service/lib/src/introduction_service.dart b/packages/flutter_introduction_service/lib/src/introduction_service.dart index 1bfe862..73d1e20 100644 --- a/packages/flutter_introduction_service/lib/src/introduction_service.dart +++ b/packages/flutter_introduction_service/lib/src/introduction_service.dart @@ -4,15 +4,36 @@ import 'package:flutter_introduction_interface/flutter_introduction_interface.dart'; +/// A service for managing introduction-related operations. +/// +/// This class provides methods for handling introduction-related actions +/// such as skipping, completing, +/// and determining whether to show the introduction. class IntroductionService { + /// Constructs an instance of [IntroductionService]. + /// + /// Optionally takes a [dataProvider] parameter, + /// which is an implementation of [IntroductionInterface]. + /// If no data provider is provided, + /// it defaults to [LocalIntroductionDataProvider]. IntroductionService([IntroductionInterface? dataProvider]) : _dataProvider = dataProvider ?? LocalIntroductionDataProvider(); late final IntroductionInterface _dataProvider; + /// Marks the introduction as skipped. + /// + /// Calls [_dataProvider.setCompleted] with the value `true`. Future onSkip() => _dataProvider.setCompleted(value: true); + /// Marks the introduction as completed. + /// + /// Calls [_dataProvider.setCompleted] with the value `true`. Future onComplete() => _dataProvider.setCompleted(value: true); + /// Checks whether the introduction should be shown. + /// + /// Returns a `Future` indicating whether the + /// introduction should be shown. Future shouldShow() => _dataProvider.shouldShow(); } diff --git a/packages/flutter_introduction_shared_preferences/lib/flutter_introduction_shared_preferences.dart b/packages/flutter_introduction_shared_preferences/lib/flutter_introduction_shared_preferences.dart index afeab4d..b11bf46 100644 --- a/packages/flutter_introduction_shared_preferences/lib/flutter_introduction_shared_preferences.dart +++ b/packages/flutter_introduction_shared_preferences/lib/flutter_introduction_shared_preferences.dart @@ -5,16 +5,27 @@ import 'package:flutter_introduction_interface/flutter_introduction_interface.dart'; import 'package:shared_preferences/shared_preferences.dart'; +/// Provides data storage using SharedPreferences for +/// managing introduction data. +/// +/// This class extends [IntroductionInterface] and implements methods to manage +/// introduction data using SharedPreferences. class SharedPreferencesIntroductionDataProvider extends IntroductionInterface { + /// Constructs an instance of [SharedPreferencesIntroductionDataProvider]. SharedPreferencesIntroductionDataProvider(); SharedPreferences? _prefs; String key = '_completedIntroduction'; + /// Writes a key-value pair to SharedPreferences. + /// + /// The [key] is the key under which to store the [value]. + /// The [value] is the boolean value to be stored. Future _writeKeyValue(String key, bool value) async { await _prefs!.setBool(key, value); } + /// Initializes the SharedPreferences instance. Future _init() async { _prefs ??= await SharedPreferences.getInstance(); } diff --git a/packages/flutter_introduction_widget/lib/src/types/page_introduction.dart b/packages/flutter_introduction_widget/lib/src/types/page_introduction.dart index 8d2a837..e7d89d0 100644 --- a/packages/flutter_introduction_widget/lib/src/types/page_introduction.dart +++ b/packages/flutter_introduction_widget/lib/src/types/page_introduction.dart @@ -11,7 +11,12 @@ import 'package:flutter_introduction_widget/src/widgets/background.dart'; import 'package:flutter_introduction_widget/src/widgets/indicator.dart'; import 'package:flutter_introduction_widget/src/widgets/page_content.dart'; +/// A screen widget for displaying a multi-page introduction. +/// +/// This widget provides a multi-page introduction experience with options +/// for handling navigation and completion callbacks. class MultiPageIntroductionScreen extends StatefulWidget { + /// Creates a new instance of [MultiPageIntroductionScreen]. const MultiPageIntroductionScreen({ required this.options, required this.onComplete, @@ -22,12 +27,22 @@ class MultiPageIntroductionScreen extends StatefulWidget { super.key, }); + /// Callback function triggered when the introduction is completed. final VoidCallback onComplete; - final VoidCallback? onSkip; + + /// Callback function triggered when the "Next" button is pressed. final void Function(IntroductionPage)? onNext; + + /// Callback function triggered when the "Previous" button is pressed. final void Function(IntroductionPage)? onPrevious; + + /// Callback function triggered when the "Skip" button is pressed. + final VoidCallback? onSkip; + + /// Physics for the scrolling behavior. final ScrollPhysics? physics; + /// Introduction options specifying the configuration of the introduction. final IntroductionOptions options; @override @@ -35,6 +50,9 @@ class MultiPageIntroductionScreen extends StatefulWidget { _MultiPageIntroductionScreenState(); } +/// State class for [MultiPageIntroductionScreen]. +/// +/// Manages the state and behavior of the [MultiPageIntroductionScreen] widget. class _MultiPageIntroductionScreenState extends State { final PageController _controller = PageController(); @@ -449,16 +467,31 @@ class IntroductionOneButton extends StatelessWidget { super.key, }); + /// Options specifying the configuration of the introduction. final IntroductionOptions options; + + /// Controller for managing the pages of the introduction. final PageController controller; + + /// Callback function triggered when the introduction is completed. final VoidCallback? onFinish; + + /// Callback function triggered when the "Next" button is pressed. final VoidCallback? onNext; + + /// Callback function triggered when the "Previous" button is pressed. final VoidCallback? onPrevious; + /// Indicates whether there are previous pages. final bool previous; + + /// Indicates whether there are next pages. final bool next; + + /// Indicates whether this is the last page. final bool last; + /// Handles the navigation to the previous page. Future _previous() async { await controller.previousPage( duration: kAnimationDuration, @@ -585,16 +618,31 @@ class IntroductionIconButtons extends StatelessWidget { super.key, }); + /// Options specifying the configuration of the introduction. final IntroductionOptions options; + + /// Controller for managing the pages of the introduction. final PageController controller; + + /// Callback function triggered when the introduction is completed. final VoidCallback? onFinish; + + /// Callback function triggered when the "Next" button is pressed. final VoidCallback? onNext; + + /// Callback function triggered when the "Previous" button is pressed. final VoidCallback? onPrevious; + /// Indicates whether there are previous pages. final bool previous; + + /// Indicates whether there are next pages. final bool next; + + /// Indicates whether this is the last page. final bool last; + /// Handles the navigation to the previous page. Future _previous() async { await controller.previousPage( duration: kAnimationDuration, diff --git a/packages/flutter_introduction_widget/lib/src/types/single_introduction.dart b/packages/flutter_introduction_widget/lib/src/types/single_introduction.dart index 86fa514..f58b8ca 100644 --- a/packages/flutter_introduction_widget/lib/src/types/single_introduction.dart +++ b/packages/flutter_introduction_widget/lib/src/types/single_introduction.dart @@ -6,12 +6,15 @@ import 'package:flutter/cupertino.dart'; import 'package:flutter_introduction_widget/src/config/introduction.dart'; +/// Widget representing a single introduction page. class SingleIntroductionPage extends StatelessWidget { + /// Constructs a [SingleIntroductionPage] widget. const SingleIntroductionPage({ required this.options, super.key, }); + /// Options specifying the configuration of the introduction. final IntroductionOptions options; @override diff --git a/packages/flutter_introduction_widget/lib/src/widgets/background.dart b/packages/flutter_introduction_widget/lib/src/widgets/background.dart index 86c05e4..9eae380 100644 --- a/packages/flutter_introduction_widget/lib/src/widgets/background.dart +++ b/packages/flutter_introduction_widget/lib/src/widgets/background.dart @@ -4,14 +4,19 @@ import 'package:flutter/material.dart'; +/// Widget representing a background with optional decoration. class Background extends StatelessWidget { + /// Constructs a Background widget. const Background({ required this.child, this.background, super.key, }); + /// Optional decoration for the background. final BoxDecoration? background; + + /// The widget to be placed on the background. final Widget child; @override diff --git a/packages/flutter_introduction_widget/lib/src/widgets/indicator.dart b/packages/flutter_introduction_widget/lib/src/widgets/indicator.dart index cb247e9..53bcf08 100644 --- a/packages/flutter_introduction_widget/lib/src/widgets/indicator.dart +++ b/packages/flutter_introduction_widget/lib/src/widgets/indicator.dart @@ -23,17 +23,22 @@ class Indicator extends StatelessWidget { 'must be provided', ); + /// The mode of the indicator. final IndicatorMode mode; + + /// The PageController for which the indicator is displayed. final PageController controller; - final Widget Function( - BuildContext, - PageController, - int, - int, - )? indicatorBuilder; - final int index; + + /// The total number of items managed by the PageController. final int count; + /// The index of the current item in the PageController. + final int index; + + /// Builder function for a custom indicator. + final Widget Function(BuildContext, PageController, int, int)? + indicatorBuilder; + @override Widget build(BuildContext context) { var theme = Theme.of(context); @@ -84,10 +89,20 @@ class DashIndicator extends AnimatedWidget { this.color = Colors.white, super.key, }) : super(listenable: controller); + + /// The PageController for which the indicator is displayed. final PageController controller; + + /// The color of the dashes. final Color color; + + /// The color of the selected dash. final Color selectedColor; + + /// The total number of items managed by the PageController. final int itemCount; + + /// Callback function called when a dash is selected. final Function(int) onPageSelected; int _getPage() { diff --git a/packages/flutter_introduction_widget/lib/src/widgets/page_content.dart b/packages/flutter_introduction_widget/lib/src/widgets/page_content.dart index 0146807..5449816 100644 --- a/packages/flutter_introduction_widget/lib/src/widgets/page_content.dart +++ b/packages/flutter_introduction_widget/lib/src/widgets/page_content.dart @@ -6,7 +6,9 @@ import 'package:flutter/material.dart'; import 'package:flutter_introduction_widget/src/config/introduction.dart'; +/// Widget representing the content of an introduction page. class IntroductionPageContent extends StatelessWidget { + /// Constructs an IntroductionPageContent widget. const IntroductionPageContent({ required this.title, required this.text, @@ -16,10 +18,19 @@ class IntroductionPageContent extends StatelessWidget { super.key, }); + /// The title widget. final Widget? title; + + /// The text widget. final Widget? text; + + /// The graphic widget. final Widget? graphic; + + /// The layout style of the content. final IntroductionLayoutStyle layoutStyle; + + /// Callback function called when the content is tapped. final VoidCallback onTap; @override