Flutter MySpot is a plugin alowing you to easily implement tutorial in your app

Features

Manage scenario with scene to explain élément on your flutter widget adding key to desired widget

  • Allow reponsive and moving widget as target,
  • Audio support (using audioplayer),
  • Handle play once (using flutter_secure_storage),
  • Deformable spot to accept all widget geometrie,
  • Simply add help button to call your scénario,
  • Support multiple scenarion on one screen,
  • Getting started

    To install plug-in add to your public.yaml :

    dependencies:
      flutter:
        sdk: flutter
    
      flutter_myspot:
        git: https://github.com/mynumeric-mobile/flutter_myspot
    

    Usage

    examples for package could be found in example folder

    • first wrap your page with HoleWidget

    this widget hold scenario. Scenario is composed by properties and an array of scenes. Each scene is used sequencialy to highlight a designet widget.

    note that your widget must have a key :

    HoleWidget(
              scenario: SpotScenario(
                titleWidget: SpotScenario.textWidgetBuilder(text: "Wellcome to our tutorial", context: context),
                // and a scene for each widget to highlight
                scenes: [
                  SpotScene(
                    description: SpotScenario.textWidgetBuilder(
                        text: "You can change this number",
                        context: context,
                        style: const TextStyle(color: Colors.white, fontSize: 20)),
                    audioAsset: "number.mp3",
                  ),
                ],
                
              ),
              child: MyHomePage(title: 'Flutter Demo Home Page', key: GlobalKey()),
            ));
      }
    
    • Next designate widget to highlight : add in top of your main widget an array 'tutorialKeys' add as many GlobalKey as you want scene
    class MyHomePage extends StatefulWidget {
      MyHomePage({super.key, required this.title});
      final List<GlobalKey> tutorialKeys = [GlobalKey()];// add this line
    ....
    

    and add tutorialKey to desired widget.

      Text(
        key: widget.tutorialKeys[0],
    

    Handle play once

    If you want to display tutorial only on first use, you can call createState("home") where "home" is a unique id for your scene. Your state must be set before any scenario is play in main or in splashscreen. When state is created you just have to set key property of your scene to limit to display her content to first run.

    For exemple :

    Future<void> main() async {
      WidgetsFlutterBinding.ensureInitialized();
      await SpotScenario.createState(["home"]); //option if you want to display only once
      runApp(const MyApp());
    }
    

    in your scenario declaration add

    HoleWidget(
              scenario: SpotScenario(
                titleWidget: SpotScenario.textWidgetBuilder(text: "Wellcome to our tutorial", context: context),
                // and a scene for each widget to highlight
                scenes: [
                  SpotScene(
                    id:"home,
                    description: SpotScenario.textWidgetBuilder(
                        text: "You can change this number",
    ...
    

    Note that you can use state for other purpose. You just need to at a unique ID.

    to set value

    SpotScenario.setState("myUniqueID", false);
    

    to read state

    SpotScenario.spotIDs["myUniqueID"]
    

    Scénario life cycle

  • 1 Display title
  • 2 Play audio title and wait to the end if exist
  • 3 Move to first scene object using movmentDuration*
  • 4 Display first scene description
  • 5 Play first scene audio if exist and wait to the end
  • 6 Wait for delay*
  • 7 hide first scene description
  • Go to next scene (step 3) or quit
  • *user define scenario properties.

    Adding help button

    MySpot provide a widget to easily add help button to your screen:

    SpotButton.tutorial(
                context,HoleWidget(...
    

    Defining scenario

    To have more readable code you could define your tutorials in external class

    class Tutorial {
      static HoleWidget home(context) => HoleWidget(
            scenario: SpotScenario(
              id: "home",
                ...
              child:MyScreenWidget()
              }
    

    and then you can use just like this :

    Navigator.push(
                          context,
                          MaterialPageRoute(
                            builder: (context) => Tutorial.home(context),
                          ),
                        );
    

    And help button become just :

    SpotButton.tutorial(context, Tutorial.home(context))
    

    Defining endMode

    EndMode define behavior after end of scenario. There is 3 modes :

  • redirectTochild
  • This is the default one. When end is reach we leave tutorial and navigate to the child widget.

  • loop
  • In this mode we play scenario in loop.

  • stayInactive
  • If you want to keep MySpot to read another scenario for exemple you must use this one.

    Changing scénario

    In some case it could be intresting having svereal scenario for one screen. For exemple a scenario for introducing screen then give the hand to user to do an action and play after that an other scenario or after returning from popup. For that you have to add key for HoleWidget et the use it as follow:

    widget.spotKey?.currentState?.changeScenario(Tutorial.home2(
                          context,
                          HomeWidget()));
    

    dependencies

    shared_preferences: ^2.2.0 audioplayers: ^4.1.0

    Powered by My-Numeric.com

    Libraries

    flutter_myspot