This tutorial gives an introduction into the Flutter framework and explains how to setup your development environment.

1. About this guide

This tutorial gives an introduction into the Flutter framework Other guides in this Flutter series explains the development with Flutter:

2. What is Flutter

2.1. Introduction to Flutter

Flutter is a UI toolkit to build native, fast and beautiful apps for iOS, Android, the web and desktop with a single codebase. It was introduced by Google in 2017 and has had its first 1.0 release on December 4th, 2018.

Flutter is written in C, C++ and Dart. Unlike Javascript, Dart is a statically typed, class-based language which is able to compile Just in Time (JIT) or Ahead of Time (AOT). Flutter supports hot reload of the code during development, which results in an extremely fast stateful reload of your app during development. The SDK utilizes the Skia Graphics Engine to render.

The following image shows the general Flutter architecture.

flutter sdk overview

The top layer provides the building blocks of Flutter and is purely written in Dart. It contains libraries for animation, painting, rendering and widgets.

The Framework runs on top of the engine, which is primarily written in C/C++. The engine contains three core libraries:

  • Skia — An open source graphics engine used by Google Chrome, Android, Chrome Os and may more.

  • Dart runtime

  • Text — Engine used to render and layout text

The bottom layer is the embedder. This layer is platform specific and is where the surface for rendering Flutter is configured.

Flutter is motivated by the fact that the most successful apps, like the Netflix one, looks the same on platforms like iOS and Android. Platform specific behavior like the scroll behavior is still supported by Flutter.

Flutter draws everything itself. Native component like the one used in the Android SDK may handle such updates in the native components.

2.2. Libraries

https://pub.dev/ provides Flutter and Dart libraries. The Flutter tooling uses the pub tooling to read library and build configuration from a pubspec.yaml file and downloads and updates the application with the required libraries.

2.3. Development environment

Flutter can be developed by only using a text editor and the command line.

More advanced support is delivered by the following tools:

We currently recommend Visual Studio Code as the development tool, as it is fast, stable and lightweight.

3. Getting started with Flutter

The following assume that you already installed installed Flutter. Create a new Flutter app named getting_started by using the instructions from Create a Flutter app.

Open the lib\main.dart file and remove all code. Replace the code with the following:

import 'package:flutter/material.dart';(1)

void main() => runApp(MyApp()); (2)

class MyApp extends StatelessWidget {(3)
  @override
  Widget build(BuildContext context) {(4)
    return MaterialApp(
      title: 'Flutter starter app',
      home: Scaffold( (5)
        appBar: AppBar(
          title: Text('Welcome to Flutter'),
        ),
        body: Center( (6)
          child: Text('Hello World'),
        ),
      ),
    );
  }
}

1 Makes the material library available
2 Arrow notation is a short notation for one-line methods or functions
3 Stateless widget is one of the fundamental widgets, you compose your app out of widgets
4 The build method of a widget describes how to create the widgets contained in this widget
5 Scaffold widget provides a default app bar, a title, and a body property that holds the widget tree for the home screen
6 The Center widget center its child into its container, in this case in the center of the screen

The app should look like the following:

flutter starter10

4. Flutter core concepts

4.1. Applications

The main entry point for Flutter apps is the lib/main.dart file. This file contains a main() method that calls the runApp(…​) method of the Flutter framework. This method creates the widget hierarchy. The top level widget created by the runApp(…​) method is the root of your widget hierarchy.

Typical, you create a MaterialApp from the build(BuildContext context) method of the root widget.

MaterialApp can be used to:

  • set routes (navigation)

  • set the theme

  • and various other default settings.

The following listing shows a main.dart file which creates a small app with a custom widget named SimpleWidget.

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';

void main() => runApp(MyApp()); (1)


class MyApp extends StatelessWidget {
  // This widget is the root of your application
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: SimpleWidget(title: 'Flutter Demo Home Page'), (2)
    );
  }
}


class SimpleWidget extends StatelessWidget {
  final String title;
  SimpleWidget({Key key, this.title}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(title),
      ),
      body: Text('Hello'),
    );
  }
}
1 The main method is called on startup
2 The widget initially shown in the material app

4.2. Widgets

In Flutter UI element is a widget with the base type Widget. Widgets can be customized using properties and may have one or several children.

The Flutter library provides lots of standard widgets. These range from button implementations to more complex widgets like lists or stacks.

Flutter uses StatelessWidget and StatefulWidget widgets:

  • StatelessWidget - widgets without mutable state

  • StatefulWidget - widgets with manages mutable state

4.2.1. StatelessWidget

Stateless widgets are immutable, their properties cannot change. Hence, every field in it should be marked as final.

The Dart compiler does not enforce immutability. So it is possible to use non-final fields in StatelessWidgets. However, changing their values can result in negative site-effects.

Consider this simple example:

import 'package:flutter/material.dart';

void main() => runApp(App());

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Homepage(count: 10),
    );
  }
}

class Homepage extends StatelessWidget {
  final int count; (1)

  Homepage({this.count});(2)

  @override
  Widget build(BuildContext context) {
    return Text('Pressed: $count');
  }
}
1 the count field was marked as final, therefore the Dart compiler does not allow any changes at runtime
2 count is defined as an optional parameter using the {} notation

Stateless widgets can be optimized by the Flutter runtime and therefore should be preferred if not state is necessary in a certain widget.

4.2.2. StatefulWidget

A stateful widget extends StatefulWidget and contains data which may change during the lifetime of the widget. A widget’s state consists of properties of its class.

Implementing a stateful widget requires two classes:

  • A Stateful widget that creates an instance of a State class.

  • The State class for this widget

The Stateful widget itself is immutable, which its state object persist over the lifetime of the widget.

This state class extends State<T> with T being the type of the corresponding StatefulWidget. The created state class is exclusive to T and cannot be used in other StatefulWidget implementations.

You have to use the setState(…​) function to update the state. This method is available in all State<T> classes. setState(…​) takes a function (VoidCallback) as an argument. In this VoidCallback you can modify the widget’s properties. Flutter will then re-render all impacted widgets.

A stateless widget can contain stateful widgets and vice-versa.

The following is an example for an application using a stateful widget.

import 'package:flutter/material.dart';

void main() => runApp(App());

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Homepage(),
    );
  }
}

class Homepage extends StatefulWidget {
  @override
  _HomepageState createState() => _HomepageState();
}

class _HomepageState extends State<Homepage> {      (1)
  int count = 0;                                    (2)

  @override
  Widget build(BuildContext context) {
    return MaterialButton(
      child: Text('Pressed: $count'),
      onPressed: () => setState(() => count++),     (3)
    );
  }
}
1 _ (an underscore) marks the class as private
2 this attribute isthe state of the widget in this example
3 In setState(…​) we update the value of the count field. Flutter then updates the relevant widgets.

Flutter takes care of a lot of the state related operations for you. In other words: You don’t have to care about which (nested) widget needs to be updated or repainted, etc.

There are libraries and patterns that allow for more complex state management. Some of them will be covered in a later chapter.

4.2.3. Use a StatelessWidget instead of extending existing widgets

Sometimes it might seem intuitive to just extend a Button widget if you want to generalize an often used configuration. But in this case you should rather use a StatelessWidget and return a Button with the desired configuration.

4.3. Using Keys

Key are used to identify StatefulWidgets.

Keys are not required for StatelessWidgetss, as they don’t have any state associated with it. This means they can be recycled without messing up the state.

So in case StatefulWidgets of the same type are dynamically reordered, added or removed you need to use keys. This is necessary so that Flutter can reconnect the state object with the correct element in the widget tree.

An example would be a list in which you can reorder list items.

The key should be placed on the top of the widget tree which should be preserved.

You can create keys with the UniqueKey() method or if it based on your data you can use ValueKey(yourdata.yourid);

For a detailed overview of using keys, see https://medium.com/flutter/keys-what-are-they-good-for-13cb51742e7d.

5. Important Widgets

5.1. Scaffold

The Scaffold widget provides convenient APIs for displaying common Material widgets like drawers, snack bars, bottom sheets and floating actions buttons. It sets various defaults (like theming), provides direct properties for a host of different child widgets and much more.

An example of a Scaffold could look like this:

Scaffold(
    appBar: AppBar(
        title: Text('App title')
    ),
    body: Text('A body'),
    floatingActionButton: FloatingActionButton(
        child: Icon(Icons.add)
    ),
    bottomNavigationBar: BottomNavigationBar(
        items: []
    )
)
Table 1. Scaffold properties
Property Type Description

appBar

AppBar

An AppBar at the top of the screen

body

Widget

The content of your page

floatingActionButton

Widget

A round button, commonly located near the bottom right of the screen. Typically used as a contextual action button for frequently performed actions. It is often referred to as a FAB.

bottomNavigationBar

Widget

A bar of actions at the bottom of the screen. Typically, this is an omnipresent navigation bar that provides access to other pages of the app.

Here is an example for a Scaffold widget with an app bar.

import 'package:flutter/material.dart';

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        leading: IconButton(
          icon: Icon(
            Icons.menu,
          ),
          onPressed: () {},
        ),
        title: Text("Hello"),
        actions: <Widget>[
          IconButton(
            icon: Icon(
              Icons.search,
              semanticLabel: 'search',
            ),
            onPressed: () {
              print('Search button');
            },
          ),
          IconButton(
            icon: Icon(
              Icons.filter_list,
              semanticLabel: 'filter',
            ),
            onPressed: () {
              print('Filter button');
            },
          ),
        ],
      ),

      // TODO: Add a grid view (102)
      body: Center(
        child: Text('Scaffold with AppBar'),
      ),
      resizeToAvoidBottomInset: false,
    );
  }
}
scaffold with appbar example10

There are quite a few more settings related to the positioning, theming and other behavior, which will be covered more in depth later.

As the scaffold shows the app bar and other structurally important parts of the app you typically want to do any dynamic loading inside of the body property instead of wrapping the Scaffold.

5.2. Container

The container widget is a simple container that can receive one child. A container widget without children tries to be as big as possible.

It can also have a background color and can be styled using its decoration property. As its height and width can also be set directly this can be used if you are certain about the constrains of the element.

Container(
    margin: EdgeInsets.all(10.0),
    child: Text('Text'),
    width: 150.0,
    height: 150.0,
    color: Colors.green
    decoration: BoxDecoration(
      border: Border.all(color: Colors.grey),
      borderRadius: BorderRadius.circular(5.0),
   ),
)

This would render a 150 by 150 pixel big, green box with the text "Text" displayed in it.

If a container widget is placed in a widget with unlimited space, like a SingleChildScrollView widget, it is not displayed.

5.3. Text and TextFields

  • Text is a label which shows some text

  • TextField allows the user enter text

5.4. Buttons

Flutter provides multiple default button implementations

  • RaisedButton - a button with a background color, used to represent the prominent button.

  • FlatButton - a text button

  • IconButton - a button with an icon, typical used in a application bar, has no child property but a icon property

  • OutlineButton

  • FloatingActionButton

  • ToogleButton

A layout should contain a single prominent button. This makes it clear that other buttons have less importance. This prominent button represents the action we most want our users to take in order to advance through our app.

These buttons typically have the following properties: * child: contains the Widget for this button, frequently a Text widget * onPressed: takes a method reference that will be executed when the button is pressed.

To group buttons you can use the ButtonBar which is similar to a Row but automatically wraps its children if their is not sufficient space.

Buttons which have no onPressed property set or only null assigned are disabled by the Flutter framework.

5.5. Images

The Image widget provides helper methods to create images from several sources.

  • Image.assert

  • Image.network

For example, Image.network("https://picsum.photos/id/10/200/200"); creates an image from the given URL.

By default, Image does not provide caching or a placeholder image until it is loaded. Use the cached_network_image package for that. This requires that you add a dependency to this library in you pubspec.yaml.

CachedNetworkImage(
  placeholder: (context, url) => CircularProgressIndicator(),
  imageUrl: 'https://picsum.photos/id/10/200/200',
);

Some widgets require an ImageProvider, e.g. NetworkImage.

You can use a ColorFiltered widget to change the color of an image. For example the following grays out an image.

ColorFiltered(
  colorFilter: ColorFilter.mode(
  Colors.grey,
  BlendMode.saturation,
),

5.6. Using GestureDetector

With a GestureDector you can register a click listener to any widget.

Contain
GestureDetector(
  onTap: () {
    print("onTap called.");
  },
  child: Text("foo"),
),

5.7. Flexible, Column, Row

The widgets of the Flex family are widgets that allow putting multiple widgets next to each other on the same axis. The Column and Row widgets are specialized versions of the Flex widget. They set the direction attribute of the Flex constructor set to Axis.vertical and Axis.horizontal respectively. So if you know in what direction the widget will layout its children, use the Column or Row directly.

All of these widgets also take a <Widget>[…​] (list of Widget) as a constructor parameter. In here you can add all the widgets that should be displayed.

Column lays out its children vertically.

Column(
    children: <Widget>[
        Text('I will be above'),
        Text('I will be below'),
    ]
)

Row lays out its children horizontal.

Or for the Row widget:

Row(
    children: <Widget>[
        Text('I will be left'),
        Text('I will be right'),
    ]
)

Flexible (or its specialized version of Expanded) allow to distribute the available space based on the weight defined by the flex attribute. Default for the flex attribute is 1.

Column(
  children: <Widget>[
    Flexible(
      child: Container(color: Colors.black, child: Text("Hello")),
      flex: 2,
    ),
    Flexible(
      child: Container(color: Colors.red, child: Text("Testing")),
    flex: 1,
    )
   ],
)
You can control the actual direction of the list by setting the mainAxisAlignment property.

5.8.1. Wrap

If there is not enough space to display all children, Flutter will show an error.

column no wrap

The Wrap widgets wraps its children, if there is not enough space.

column wrap

5.8.2. SizedBox, FittedBox and Spacer

SizedBox can be used to force a widget into a certain size or to add some fixed sized space between widgets. Spacer can be used to allocate empty space. FittedBox can be used to resize a SizedBox based on give constraints from its container

5.9. ListView, GridView and ListTile

The ListView and GridView widgets allow to show multiple widgets in a list or in a grid. It takes care of overflowing widgets by automatically enabling scrolling if its children extend over the screen edge.

class TestWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ListView(
      children: _createChildren(),
    );
  }
}

 List<Widget> _createChildren() {
  return [Text("Hello"), Text("Lars"), Text("Testing")];
}

List provides also a builder to create list items.

class TestWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemBuilder: (_, index)=>
      Text('Item $index'),
    );
  }
}

You can also use a separator.

class TestWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ListView.separated(
      itemBuilder: (_, index)=>
      Text('Item $index'),
      separatorBuilder: (_,index) =>Divider(),
      itemCount: 100,
    );
  }
}

If your list you be reorderable, use the ReorderableListView widget.

One drawback to keep in mind is that you have to know the height of a widget beforehand or else you will get exceptions as the ListView does not know how much space it should calculate. There are however solutions to this, as some specialized widgets take care of this for you.

5.10. PageView

The PageView widget allows to swipe between different screens. It allows to define a controller which can set the initial page.

pageview
import 'package:flutter/material.dart';
import 'listview.dart';
import 'listviewbuilder.dart';

class MyPager extends StatelessWidget {
  final PageController controller = PageController(
    initialPage: 1,
  );

  @override
  Widget build(BuildContext context) {
    return Container(
      child: PageView(
        children: <Widget>[
          MyListView(), // a custom widget
          ListViewBuilder(), // another custom widget
        ],
      ),
    );
  }
}

5.11. Loading asserts

Asserts must be declared in the pubspec.yaml.

flutter:

  # The following line ensures that the Material Icons font is
  # included with your application, so that you can use the icons in
  # the material Icons class.
  uses-material-design: true

  # To add assets to your application, add an assets section, like this:
  # assets:
  #  - images/a_dot_burr.jpeg
  #  - images/a_dot_ham.jpeg
  asserts:
    asserts/events.json

Afterwards you can load them, for example to load a text file:

DefaultAssetBundle.of(context).loadString("asserts/events.json");

5.12. Flavor specific widgets

Most components are available in both Cupertino (iOS) and Material (Android) styles. But of course it is up to you, which flavor you use and not dependent on the host OS. However, it is important to keep in mind, that users of the Android platform might expect Material style apps and iOS users Cupertino styles.

Conditional styling is possible, but it increases complexity in the app and depending on the size of the app might make UI-testing a lot harder. You can access the currently running host OS using Platform.isIOS and Platform.isAndroid.

6. Implementing Navigation in Flutter via Routing

Flutter supports navigation between different pages. As everything in Flutter, a page is just a widget. It can either be a StatelessWidget or a StatefulWidget.

Using different widgets which can be reached via navigations helps separating concerns, encourages encapsulation of code and thus makes the code base easier to read and maintain.

The navigation is handled by the Navigator class. It has different functions available that allow for either:

  • showing a page directly.

  • using named routes

This works as follows:

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

With named routes, you pass a map of all routes to the routes parameter of the MaterialApp constructor. The keys of the map should be a string with the name of the route (typically these start with a /, similar to HTTP paths). The value of each key is a function that takes the context of the app as an argument and returns an instance of the widget of the page.

For a larger code base it is recommended to use a central map of all named routes. This way you can always change the class that is shown on a route in one single place instead of searching the code base for occurrences of the route. However sometimes it might be useful to just show a widget as a page.

Named routes may be pushed like this:

Navigator.pushNamed(context, '/issue')

Keep in mind though, that you have to register each route during instantiation of the app.

This could look like this:

MaterialApp(
        // ...
        routes: {
            '/': (context) => Homepage(),
            '/second': (context) => SecondPage(),
            // etc.
        },
        initialRoute: '/', (1)
    ),
1 The initial route is the first page the app shows when opening the app
As the app grows larger this part could become very crowded. One simple way to do this is, storing these routes and their builder functions in a separate file and expose them via a map. This is very common and you might see this in existing Flutter apps.

6.1. Passing data to a route

Sometimes you might want to pass data to a route. This could be a user id for showing their details or just something a user entered on the first screen.

For this, Navigator.pushNamed(…​) accepts an optional named argument called arguments. You may pass any Dart object to it but is is advisable to create a "wrapper" object that has the fields you want to pass for type safety.

Creating a wrapper object might look like this:

class RouteArguments {
    final int userId;
    final String message;

    RouteArguments(this.userId, this.message);
}

Passing the argument to the route:

Navigator.pushNamed(context, '/second', arguments: RouteArguments(8, 'This is a message'));

To access this data in a route, you will need to add it to the constructor of the widget.

@override
Widget build(BuildContext context) {
    // ...
    final RouteArguments args = ModalRoute.of(context).settings.arguments;
    // ...
    // And later you may access its values directly
    int id = args.userId;
}
You can only receive these arguments where you have a BuildContext instance.

Dart automatically assigns the object to your RouteArguments type. But keep in mind that it can’t do so, if the object passed in was not of type RouteArguments. In this case it would throw an exception.

6.2. Handling unknown routes

In some cases you might want to generate the routes dynamically or you want to be safe and have an unknown route screen.

Luckily there is a onUnknownRoute handler in the MaterialApp constructor. This takes a function that returns a Route (e.g. a MaterialPageRoute or CuptertinoPageRoute). Its builder should return an instance of your page.

MaterialApp(
        // ...
        routes: ...,
        onUnknownRoute: (settings) {
            return MaterialPageRoute(builder: (context) => NotFoundPage());
        },
        initialRoute: '/',
    ),

7. Managing application state in Flutter

An application needs to handle its state (data). The following explanation speaks about state, keep in mind that this is data, e.g., one or several objects stored somewhere.

While each stateful widget in Flutter can have its own state, state typically needs to be available in multiple widgets in the application. In Flutter it is common to keep the state in the hierarchy above the widgets which use it as you have to rebuild your widgets to change the UI.

As developer you can:

  • manage this state yourself via widget constructors

  • use InheritedWidget which is provided by the Flutter SDK

  • use Provider which is an external library and currently the recommended approach for doing this

  • Using Bloc

  • Using other alternatives

7.1. Using widget constructors

Once approach to manage the state is that the root widget stores the data and pass it down the widget tree via the widget constructor. Widgets which update the state would have to call the other widgets which would lead to highly coupled widgets. It also create a lot of overhead and maintaining these kinds of apps can be difficult.

Therefore, this solution is not recommended.

7.2. Using InheritedWidget

InheritedWidget provides a simple way of accessing data in a widget hierarchy. The parent widget extends InheritedWidget

class MyWidget extends InheritedWidget {
  const MyWidget({
    Key key,
    this.color,
    Widget child,
  }) : assert(color != null),
       assert(child != null),
       super(key: key, child: child);

  final Color color;

  static MyWidget of(BuildContext context) {
    return context.inheritFromWidgetOfExactType(MyWidget) as MyWidget;
  }

  @override
  bool updateShouldNotify(MyWidget old) => color != old.color;
}

Widgets below the hierarchy can access the data via the convenient MyWidget.of(context) method.

InheritedWidget works fine, but a even better solution is the usage of the provider package as described in the next chapter.

7.3. Using the Provider package

The Provider package provides a means to handle state. Google recommended currently this approach for state management in Flutter apps.

See https://pub.dev/packages/provider for its latest version, which you can add as dependency to your pubspec.yaml file.

It consists of providers that can provide any kind of data (from singleton services to data values that might change during the runtime of the app) down the widget hierarchy.

To provide data for all children of a widget, wrap this widget with a Provider widget. This widget allows to set the state via the builder property. If you want to provide data for your whole application, wrap your top level widget.

For example, if you want to provide one instance of UserService in your app, you can provide an instance of this class via a Provider widget.

@override
Widget build(BuildContext context) {
  return Provider(
    create: (context) => UserService(),
    child: MaterialApp(
      // Relevant app configuration
    )
  );
}

To access this instance of UserService in another widget use the static function Provider.of<T>(context) where T is the type of your value (in this case the UserService).

//...
var userService = Provider.of<UserService>(context);
//...

This enables you to build your own providers for your data and consume them inside any children of your initial provider.

Keep in mind that this always requires a BuildContext which is available in any build(…​) method in your State<T> or StatelessWidget classes.

7.3.1. Multiple Provider

In case you have multiple providers, you can use the MultiProvider class. It has a providers parameter that accepts a list of providers.

To use it, wrap your MaterialApp with a MultiProvider.

@override
Widget build(BuildContext context) {
  return MultiProvider(
    providers: [
      Provider(
        create: (context) => UserService(),
      ),
      Provider(
        create: (context) => EventService(),
      ),
    ],
    child: MaterialApp(
      // Relevant app configuration
    )
  );
}

To access any of these providers in the widget hierarchy below its declaration, you can again use the Provider.of<T>(context) function.

7.3.2. Change Notifiers

ChangeNotifier which is part of the Flutter SDK and provides change notifications to its listeners. The function notifyListeners() can be called to notify listeners that something changed. Other frameworks calls such a class an observable, in case you are familiar with this term.

class TaskModel with ChangeNotifier {
 final List<String> _todos = [];

  void addTask(String task) {
    _items.add(task);
    notifyListeners();
  }
}

This also works with asynchronous methods.

class AuthenticationService with ChangeNotifier {

  bool isAuthenticated = false;

  Future<void> _authenticate(String email, String password) async {
    // do authentication
    isAuthenticated = true;
    notifyListeners();
  }
}

7.3.3. Using ChangeNotifier with the Provider package

A class that implements ChangeNotifier can be provided through a ChangeNotifierProvider.

ChangeNotiferProvider(
    create: (context) => TaskModel(),
    child: MyApp(),
),

Changes can be listened to by Consumer<T> widgets where T is the type of your ChangeNotifier. Inside its builder parameter you can return other widgets based on the changed value.

@override
Widget build(BuildContext context) {
  return Consumer<AuthenticationService>(
    builder: (context, authenticationService, child) { (1)
      if(authenticationService.isAuthenticated) {
        return UserPage();
      } else {
        return LoginPage();
      }
    }
  )
}
1 The builder also receives the optional child parameter of the Consumer which can be returned inside the builder if you just want to do updates to the local state.

7.3.4. Using the Consumer widget

You can access your ChangeNotifierProvider via the Consumer widget.

return Consumer<TaskModel>(
  builder: (context, tasks, child) {
    return Text("Total number of items: ${tasks.size()}");
  },
);

The builder is called with three arguments.

  • The first one is context, which you also get in every build method

  • The second argument of the builder function is the instance of the ChangeNotifier. You can use the data in the model to define what the UI

  • The third argument is child, which is there for optimization. If you have a large widget subtree under your Consumer that doesn’t change when the model changes, you can construct it via the child attribute. This will be passed here to you.

7.4. BLoC

The BLoC pattern is a little bit more Dart specific as it’s based on streams which are implemented as a first class citizen in Dart. BLoC stand for Business Logic Component. The gist of this is that business logic, the logic of your app, should be moved to so called BLoCs. This removes said logic from the presentation layer and helps separating the logic from UI.

Per definition these BLoCs should also be platform independent. This has the added benefit of being very transportable to other versions of your app (for example a Dart server backend or an AngularDart frontend). These BLoCs rely exclusively on Streams as their primary means of communication to other parts of the app.

BLoC helper packages are also available from pub.dev.

7.5. MobX and Redux

The MobX and Redux approaches originate from the JavaScript world and are already used in a host of different JavaScript apps. They have been ported to Dart and are available from the pub store: MobX and Redux.

8. Network Communication

8.1. Futures

A Future<T> is a special class that is essential for async computation in Dart. It provides a way to delay reactions to data until the data is actually there. Use cases for this is network communication as you most likely want to wait for the data returned from the server before proceding with your computation.

Futures are very deeply integrated into the core of the Dart language. The async/await syntax can be used to "await" the result of a computation before going further in the current method’s execution.

This does not mean that the main thread is blocked while waiting. You can read more on that here: https://dart.dev/codelabs/async-await#execution-flow-with-async-and-await

Many built-in methods of the Dart & Flutter SDKs return futures where appropriate.

A Future<T> is very similar to a Promise in JavaScript, Task<T> in C# or a CompletableFuture<T> in Java.

8.2. The http Library

Network communication in Flutter can be simplified by using the http library by the dart.dev team. To use the library you have to add it to the pubspec.yaml file of the project:

dependencies:
# ... more dependencies

  http: 0.12.0+2
# ...

The library contains a set of high level APIs to make working with network requests easy.

The usage of http is pretty straightforward.

It exposes the most common HTTP operations directly and returns the responses wrapped in a Future.

  • http.get(…​)

  • http.post(…​)

  • http.put(…​)

  • http.delete(…​)

  • For a full list refer to the official documentation.

This is useful as you can use the async/await syntax to "await" the response.

import 'package:http/http.dart' as http;

var response = await http.post('https://api.dev/...', { body: 'Some body'}); (1)
1 The await keyword is special Dart syntax that waits the current method execution and unwraps the returned Future. The response variable is now of type Response and not Future<Response>.

8.3. Using Futures in UI

Normally, when working with network requested data, you want to wait until the data is loaded before your show the user the corresponding UI elements. In Flutter this can be done using the FutureBuilder widget.

It takes three parameters:

  • future: The future that should be waited upon

  • initialData: The data contained in the snapshot parameter of the builder until the future is completed.

  • builder: A function with the signature (BuildContext context, AsyncSnapshot<T> snapshot). It will be called every time something changes in the future (successful or erroneous completion). Typically this method should return a widget.

The documentation advises that the builder method could be called on every frame.

An example usage of the FutureBuilder:

Scaffold(
  body: FutureBuilder(
    future: _someFuture, (1)
    builder: (BuildContext context, AsyncSnapshot<String> snapshot) { (2)
      if (snapshot.hasData) { (3)
          return Text(snapshot.data);
      } else if (snapshot.hasError) { (4)
        return Text(snapshot.error.toString());
      } else { (5)
        return CircularProgressIndicator();
      }
    },
  ),
);
1 A previously defined Future<String>
2 In this case the type of Data contained in the AsyncSnapshot is of type String. But it could be of any type.
3 If the snapshot has data, a Text widget is returned that displays the data
4 If the Future was erroneous its error should be displayed
5 The default case, when there is no data yet

9. Calling native code

The communication with Flutter and native code works via channels.

Both the native components as well as the Flutter components have to use the same key for the channels to address them.

The channels need to be registered in the Android activity.

private static final String BATTERY_CHANNEL = "samples.flutter.dev/battery";
// more code

//This goes to the end of the onCreate method

new MethodChannel(getFlutterView(), BATTERY_CHANNEL).setMethodCallHandler(
  new MethodCallHandler() {
    @Override
    public void onMethodCall(MethodCall call, Result result) {
      if (call.method.equals("getBatteryLevel")) {
        int batteryLevel = getBatteryLevel();

        if (batteryLevel != -1) {
          result.success(batteryLevel);
        } else {
          result.error("UNAVAILABLE", "Battery level not available.", null);
        }
      } else {
        result.notImplemented();
      }
    }
  }
);

And Flutter needs to call it.

class _MyHomePageState extends State<MyHomePage> {
  final logger = Logger();
  static const platform = const MethodChannel('samples.flutter.dev/battery');

  // Get battery level.
  // Get battery level.
  String _batteryLevel = 'Unknown battery level.';

  Future<void> _getBatteryLevel() async {
    String batteryLevel;
    try {
      final int result = await platform.invokeMethod('getBatteryLevel');
      batteryLevel = 'Battery level at $result % .';
    } on PlatformException catch (e) {
      batteryLevel = "Failed to get battery level: '${e.message}'.";
    }

    setState(() {
       logger.e("Called");
      _batteryLevel = batteryLevel;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Material(
      child: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.spaceEvenly,
          children: [
            RaisedButton(
              child: Text('Get Battery Level'),
              onPressed: _getBatteryLevel,
            ),
            Text(_batteryLevel),
          ],
        ),
      ),
    );
  }
}

10. Activate code checks

It is time to inherit to Dart conventions by activating automatic checks for it via the Dart linter.

Create the analysis_options.yaml file in your top-level folder. Add the following content.

linter:
  rules:
    - avoid_empty_else
    - avoid_init_to_null
    - avoid_relative_lib_imports
    - avoid_return_types_on_setters
    - avoid_shadowing_type_parameters
    - avoid_types_as_parameter_names
    - curly_braces_in_flow_control_structures
    - empty_catches
    - empty_constructor_bodies
    - library_names
    - library_prefixes
    - no_duplicate_case_values
    - null_closures
    - prefer_contains
    - prefer_equal_for_default_values
    - prefer_is_empty
    - prefer_is_not_empty
    - prefer_iterable_whereType
    - recursive_getters
    - slash_for_doc_comments
    - type_init_formals
    - unawaited_futures
    - unnecessary_const
    - unnecessary_new
    - unnecessary_null_in_if_null_operators
    - unrelated_type_equality_checks
    - use_rethrow_when_possible
    - valid_regexps

The Flutter and Dart compiler should start complaining about violations against this standard. Fix them until you have no more errors. If you see no errors / warnings, try adding the new keyword in front of your widgets and ensure that you see a warning.

11. Guide to write standard, clean and effective Dart code

  • Be consistent

Try to make two pieces of code similar. Different only in meaningful way.

  • Be brief

If there is multiple way to say something, pick the concise one. The goal is to make code economical, not dense.

11.1. Naming TODO

  • class name example: SliderMenu(), HttpRequest…​

  • file name, package name, directories and library: file_system.dart, slider_menu.dart…​

  • make import prefix lowercase: import 'dart.math' as math

  • name identifiers, constatn names in lowerCamelCase:

i.e., the first word starts with lowercase with following start with uppercase

var item;

HttpRequest httpRequest

11.2. Naming NOT TODO

  • capitalize acronyms

not to do:

HTTPConnection (better: HttpConnectionInfo)

IOStream (better: IoStream)

  • Make abbreviation like words:

not to do:

ID (better: Id)

  • Do not use leading underscore for identifiers if not private

  • Do not use prefix letters: kDefaultTimeout

11.3. Ordering

  • dart imports before other imports

  • package imports before relative imports

  • place external package imports before other imports

  • specify exports in a separate section after all imports

  • order each subsection alphabetically

import 'dart:async';
import 'dart:html';

import 'package:bar/bar.dart';
import 'package:foo/foo.dart';

import 'package:my_package/util.dart';

import 'util.dart';

export 'src/error.dart';

11.4. format

For formatting, Dart provides a automated code formatter dartfmt.

Avoid lines longer than 80 characters.

11.5. Documentation

  • Format comments like sentences and use '//':

// Not if there is nothing before it.
if (_chunks.isEmpty) return false;
  • use '///' to doc comments for members and types

11.6. Automatically check your code for code violations

You can check if your code aligns with the style guide guidelines by adding the following.

include: package:pedantic/analysis_options.1.9.0.yaml
  • About Dart Linter, it enforces code standards, giving effective and standard code guide.

Simply create 'analysis_options.yaml' in your root folder containing your rules.

Refer previous sections for more details on analysis_options.yaml

11.7. Reference

For more detailed guides, refer to Guide

12. Using OAuth2.0 to connect with StackOverflow

12.1. OAuth2.0

The basic idea of OAuth2.0 is commonly used nowadays.

When someone try to login from one website, he might be asked to login via Facebook. This case he authenticates with Facebook, giving the website access to required user-info from Facebook.

Here you use your application, StackOverflow, and one general user as a example.

For the explicit flow, you first register your app with StackOverflow (SO). Then you can get the client_id and client_secret from SO.

Then, you send the user, who is using your app, to the SO OAuth page. While connecting to the authentication page, you also send your client_id (so that SO recognizes that this is your app), scope(the data for which out app needs), the redirectUri (the Uri which you redirect to after user authenticates with the SO).

Once the user is at the SO page, he types in his Id and password to authenticate himself with SO authentication server.

Upon one successful authentication, the user is redirected to the redirectUri. Also one Code (the authentication code you need for access token later) you get from SO authentication server.

Then after getting the code, your app, together with the client_id and client_secret, connects with SO server. You ask for the relevant access_token which allows us to interact with SO database.

And the access_token is what you interact with SO API to get the relevant data of the user.

Note that in the process, client_id and client_secret are used to identify your identity (the app) to SO.

And the reason for having both code and access_token passed is because the authentication code is passed in frontend through browsers. This is considered unsafe. But your client_secret and the code can be used together to get the access_token from server side. This is then considered more safe.

12.2. Other OAuth2.0 methods with flutter

There are some packages you can use to reduce the work load when working with OAuth on flutter.

For general requesting, authentication, etc. FlutterOAuth

For getting the Authorization code grant, client credentials, Respurces Owner Password Grant: oauth2

For already pre-implemented calls for different API, Amazon, Dropbox, Facebook, etc. simple_auth

13. Keep Secret Keys Out

This section introduces you the way to securely store secret keys. As some private keys might be needed for configuration, you need to keep them out of your app. The way used here is to store them locally, as one asset.

13.1. Setup

Create one secret.json file under assets folder. Create one file for storing and handling data, key.dart. Then add this to the yaml file, to claim your dependency.

flutter:
  assets:
    - assets/secret.json

13.2. Adding the data to json file

First, put your secret in json file.

{
    "key": "***the key to be added***"
}

13.3. Data File

To handle the data from json file, you need to first define one data class.

class Secret{
  final String key;

  Secret({this.key = ""});

  factory Secret.fromJson(Map<String, dynamic> jsonMap){
    return Secret(key: jsonMap["key"]);
  }
}

Then since the json file is stored locally, you need to implement the methods to extract the local json data.

create on SecretLoader class.

class SecretLoader{
 final String secretPath;

 SecretLoader({this.secretPath});

 Future<Secret> load() {
   return rootBundle.loadStructuredData<Secret>(this.secretPath,
   (jsonStr) async{
     final secret = Secret.fromJson(json.decode(jsonStr));
     return secret;
   });
 }
}

13.4. Using Key

After you implemented the Json file and data class, then you can use it in the source code. This way, you avoid putting secrets in source code and keeping it out of version control system.

Secret secret = await SecretLoader(secretPath: "assets/secret.json").load();

14. Links and Literature