tal-tech · PawelSzymanski89 · Apr 24, 2022 · May 1, 2022 · May 1, 2022 · May 2, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,15 @@
+## [3.0.2]
+
+* Migrate to `3.0.0`.
+
+## [3.0.1]
+
+* Change `Intro.of(context)?.start()` to `Intro.of(context).start()`.
+
+## [3.0.0]
+
+* Completely rewritten, please refer to example for usage.
+
 ## [2.3.1]
 
 * Throw a friendly error when something goes wrong.

diff --git a/README.md b/README.md
@@ -4,173 +4,139 @@
 
 A better way for new feature introduction and step-by-step users guide for your Flutter project.
 
-# Since I no longer work at Tal, the repository has been moved to [https://github.com/minaxorg/flutter_intro](https://github.com/minaxorg/flutter_intro)
+## Since I no longer work at Tal, the repository has been moved from [https://github.com/tal-tech/flutter_intro](https://github.com/tal-tech/flutter_intro) to here.
 
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/example1.gif' width='300' />
+## This is `3.0.0` version, if you find `2.x` documentation, [click here](./README_V2.md).
+
+I completely rewritten the 3.0 version, and the usage is clearer and more concise.
+
+<img src='https://raw.githubusercontent.com/minaxorg/flutter_intro/master/doc/v3/example1.gif' width='300' />
 
 Automatically adapt when the device screen orientation is switched.
 
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/example2.gif' width='300' />
+<img src='https://raw.githubusercontent.com/minaxorg/flutter_intro/master/doc/example2.gif' width='300' />
 
 ## Usage
 
 To use this package, add `flutter_intro` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/packages-and-plugins/using-packages).
 
 ### Init
 
+Wrap the app root widget with `Intro`, also you can set some global properties on `Intro`.
+
 ```dart
 import 'package:flutter_intro/flutter_intro.dart';
 
-Intro intro = Intro(
-  /// You can set it true to disable animation
-  noAnimation: false,
-
-  /// The total number of guide pages, must be passed
-  stepCount: 4,
-
-  /// Click on whether the mask is allowed to be closed.
-  maskClosable: true,
-
-  /// When highlight widget is tapped.
-  onHighlightWidgetTap: (introStatus) {
-    print(introStatus);
-  },
-
+Intro(
   /// The padding of the highlighted area and the widget
-  padding: EdgeInsets.all(8),
+  padding: const EdgeInsets.all(8),
 
   /// Border radius of the highlighted area
   borderRadius: BorderRadius.all(Radius.circular(4)),
 
-  /// Use the default useDefaultTheme provided by the library to quickly build a guide page
-  /// Need to customize the style and content of the guide page, implement the widgetBuilder method yourself
-  /// * Above version 2.3.0, you can use useAdvancedTheme to have more control over the style of the widget
-  /// * Please see https://github.com/tal-tech/flutter_intro/issues/26
-  widgetBuilder: StepWidgetBuilder.useDefaultTheme(
-    /// Guide page text
-    texts: [
-      'Hello, I\'m Flutter Intro.',
-      'I can help you quickly implement the Step By Step guide in the Flutter project.',
-      'My usage is also very simple, you can quickly learn and use it through example and api documentation.',
-      'In order to quickly implement the guidance, I also provide a set of out-of-the-box themes, I wish you all a happy use, goodbye!',
-    ],
-    /// Button text
-    buttonTextBuilder: (curr, total) {
-      return curr < total - 1 ? 'Next' : 'Finish';
-    },
-  ),
-);
-```
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/img1.png' width='500' />
+  /// The mask color of step page
+  maskColor: const Color.fromRGBO(0, 0, 0, .6);
 
-### Bind globalKey to widgets that need to be guided
+  /// No animation
+  noAnimation: false;
 
-The `intro` object in the first step contains the `keys` property, and `keys` is a `globalKey` array of length `stepCount`. Just bind the `globalKey` in the array to the corresponding component.
+  /// Click on whether the mask is allowed to be closed.
+  maskClosable: false;
 
-```dart
-Placeholder(
-  /// the first guide page is the first item in the binding keys
-  key: intro.keys[0]
+  /// Custom button text
+  buttonTextBuilder: (order) =>
+      order == 3 ? 'Custom Button Text' : 'Next',
+
+  child: const YourApp(),
 )
 ```
 
-### Run
+### Add guided widget
 
-That's it!
+This time, the `IntroStepBuilder` class is added to do this, which solves the problem that the previous version could not dynamically add a guide.
 
 ```dart
-intro.start(context);
+IntroStepBuilder(
+  /// Guide order, can n
EDBE
ot be repeated with other
+  order: 1,
+  /// At least one of text and overlayBuilder
+  /// Use text to quickly add leading text
+  text: 'guide text',
+  /// Using overlayBuilder can be more customized, please refer to advanced usage in example
+  overlayBuilder: (params) {
+    ///
+  }
+  /// You can specify configuration for individual guide here
+  borderRadius: const BorderRadius.all(Radius.circular(64)),
+  builder: (context, key) => NeedGuideWidget(
+    /// You should bind key here.
+    key: key,
+  ),
+)
 ```
 
-## Custom widgetBuilder method
+<img src='https://raw.githubusercontent.com/minaxorg/flutter_intro/master/doc/v3/img1.png' width='500' />
+
+### Run
 
-If you need to completely customize the style and content of the guide page, you need to implement the `widgetBuilder` method yourself.
+That's it!
 
 ```dart
-final Widget Function(StepWidgetParams params) widgetBuilder;
+Intro.of(context).start();
 ```
 
-This method will be called internally by `flutter_intro` when the intro page appears, 
-and will pass some data on the current page in the form of parameters `StepWidgetParams`, 
-and finally render the component returned by this method on the screen.
+## Advanced Usage
 
 ```dart
-class StepWidgetParams {
-  /// Return to the previous guide page method, or null if there is none
-  final VoidCallback onPrev;
-
-  /// Enter the next guide page method, or null if there is no
-  final VoidCallback onNext;
-
-  /// End all guide page methods
-  final VoidCallback onFinish;
-
-  /// Which guide page is currently displayed, starting from 0
-  final int currentStepIndex;
-
-  /// Total number of guide pages
-  final int stepCount;
-
-  /// The width and height of the screen
-  final Size screenSize;
-
-  /// The width and height of the highlighted component
-  final Size size;
-
-  /// The coordinates of the upper left corner of the highlighted component
-  final Offset offset;
-}
+IntroStepBuilder(
+  ...,
+  overlayBuilder: (StepWidgetParams params) {
+    return YourOverlay();
+  },
+)
 ```
 
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/img2.png' width='300' />
+<img src='https://raw.githubusercontent.com/minaxorg/flutter_intro/master/doc/img2.png' width='300' />
 
-`StepWidgetParams` provides all the parameters needed to generate the guide page. 
-The theme provided by default is also based on this parameter to generate the guide page.
+`StepWidgetParams` provides all the parameters needed to generate the guide overlay. 
 
 ## Troubleshoot
 
 Q1. What if the highlighted area is not displayed completely?
 
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/img3.jpg' width='300' />
+<img src='https://raw.githubusercontent.com/minaxorg/flutter_intro/master/doc/img3.jpg' width='300' />
 
 A1. That's because Intro provides 8px padding by default.
 
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/img4.jpg' width='300' />
+<img src='https://raw.githubusercontent.com/minaxorg/flutter_intro/master/doc/img4.jpg' width='300' />
 
 We can change it by setting the value of padding.
 
 ```dart
-intro = Intro(
+Intro(
   ...,
   /// Set it to zero
   padding: EdgeInsets.zero,
+  child: const YourApp(),
 );
 ```
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/img5.jpg' width='300' />
+<img src='https://raw.githubusercontent.com/minaxorg/flutter_intro/master/doc/img5.jpg' width='300' />

 <hr />
 
 Q2. Can I set different configurations for each step?
 
-A2. Above version `0.4.x`, you can set single or multiple step settings(padding & borderRadius) through setStepConfig and setStepsConfig.
-
+A2. Yes, you can set in every `IntroStepBuilder`.
 ```dart
-intro.setStepConfig(
-  1,
-  padding: EdgeInsets.symmetric(
+IntroStepBuilder(
+  ...,
+  padding: const EdgeInsets.symmetric(
     vertical: -5,
-    horizontal: -8,
-  ),
-);
-
-intro.setStepsConfig(
-  [0, 1],
-  borderRadius: BorderRadius.all(
-    Radius.circular(
-      16,
-    ),
+    horizontal: -5,
   ),
-);
+  borderRadius: const BorderRadius.all(Radius.circular(64)),
+  builder: (context, key) => YourWidget(),
+)
 ```
 
 <hr />
@@ -180,32 +146,30 @@ Q3. Can I make the highlight area smaller?
 A3. You can do it by setting padding to a negative number.
 
 ```dart
-intro.setStepConfig(
-  1,
-  padding: EdgeInsets.symmetric(
-    vertical: -10,
-    horizontal: -8,
+IntroStepBuilder(
+  ...,
+  padding: const EdgeInsets.symmetric(
+    vertical: -5,
+    horizontal: -5,
   ),
-);
+  builder: (context, key) => YourWidget(),
+)
 ```
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/img6.jpg' width='300' />
+<img src='https://raw.githubusercontent.com/minaxorg/flutter_intro/master/doc/img6.jpg' width='300' />
 
 <hr />
 
 Q4. How can I manually destroy the guide page, such as the user pressing the back button?
 
-A4. Above version `0.5.x`, you can call the dispose method of the intro instance.
-
-Notice: You can call the getStatus method only above version `2.1.0`.
+A4. You can call the dispose method of the intro instance.
 
 ```dart
 WillPopScope(
   child: Scaffold(...),
   onWillPop: () async {
-    // sometimes you need get current status to make some judgements
-    IntroStatus introStatus = intro.getStatus();
-    if (introStatus.isOpen) {
-      // destroy guide page when tap back key
+    Intro intro = Intro.of(context);
+
+    if (intro.status.isOpen == true) {
       intro.dispose();
       return false;
     }
@@ -214,14 +178,6 @@ WillPopScope(
 )
 ```
 
-<hr />
-
-Q5: How to use in the web environment?
-
-A5: Due to [this bug](https://github.com/flutter/flutter/issues/69849) in Flutter, it is temporarily not supported for use on the Web.(Update: It works in Flutter 2.0+)
-
-<img src='https://raw.githubusercontent.com/tal-tech/flutter_intro/master/doc/example3.gif' width='600' />
-
 ## Example
 
 Please check the example in `example/lib/main.dart`.