Recipe: Play and Pause video

example/pubspec.yaml

@@ -15,3 +15,5 @@ dev_dependencies:
   css_colors: 1.0.2
   web_socket_channel: 1.0.9
   sqflite: ^1.1.0
+  camera: ^0.4.0+3
+  video_player: ^0.10.0+2

src/docs/cookbook/persistence/key-value.md

@@ -4,8 +4,8 @@ prev:
   title: Reading and Writing Files
   path: /docs/cookbook/persistence/reading-writing-files
 next:
-  title: An introduction to integration testing
-  path: /docs/cookbook/testing/integration/introduction
+  title: Play and pause a video
+  path: /docs/cookbook/plugins/play-video
 ---
 
 If you have a relatively small collection of key-values that you'd like

src/docs/cookbook/plugins/index.md

@@ -0,0 +1,5 @@
+---
+title: Plugins
+---
+
+{% include cookbook_group_index.md %}

src/docs/cookbook/plugins/picture-using-camera.md

@@ -0,0 +1,368 @@
+---
+title: Take a picture using the Camera
+prev:
+  title: Play and pause a video
+  path: /docs/cookbook/plugins/play-video
+next:
+  title: An introduction to integration testing
+  path: /docs/cookbook/testing/integration/introduction
+---
+
+Many apps require working with the device's cameras to take photos and videos.
+Flutter provides the [`camera`](https://pub.dartlang.org/packages/camera) plugin
+for this purpose. The `camera` plugin provides tools to get a list of the
+available cameras, display a preview coming from a specific camera, and take
+photos or videos.
+
+This recipe demonstrates how to use the `camera` plugin to display a preview, 
+take a photo, and display it.
+
+## Directions
+
+  1. Add the required dependencies
+  2. Get a list of the available cameras
+  3. Create and initialize the `CameraController`
+  4. Use a `CameraPreview` to display the camera's feed
+  5. Take a picture with the `CameraController`
+  6. Display the picture with an `Image` Widget
+
+## 1. Add the required dependencies
+
+To complete this recipe, you need to add three dependencies to your app:
+
+  - [`camera`](https://pub.dartlang.org/packages/camera) - Provides tools to work with the cameras on device
+  - [`path_provider`](https://pub.dartlang.org/packages/path_provider) - Finds the correct paths to store images
+  - [`path`](https://pub.dartlang.org/packages/path) - Creates paths that work on any platform
+
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  camera:
+  path_provider:
+  path:
+```
+
+## 2. Get a list of the available cameras
+
+Next, you can get a list of available cameras using the `camera` plugin.
+
+<!-- skip -->
+```dart
+// Obtain a list of the available cameras on the device.
+final cameras = await availableCameras();
+
+// Get a specific camera from the list of available cameras
+final firstCamera = cameras.first; 
+```
+
+## 3. Create and initialize the `CameraController`
+
+Once you have a camera to work with, you need to create and initialize a
+`CameraController`. This process establishes a connection to the device's camera
+that allows you to control the camera and display a preview of the camera's
+feed.
+
+To achieve this, please:
+
+  1. Create a `StatefulWidget` with a companion `State` class 
+  2. Add a variable to the `State` class to store the `CameraController`
+  3. Add a variable to the `State` class to store the `Future` returned from
+  `CameraController.initialize`
+  4. Create and initialize the controller in the `initState` method
+  5. Dispose of the controller in the `dispose` method
+
+<!-- skip -->
+```dart
+// A screen that takes in a list of Cameras and the Directory to store images.
+class TakePictureScreen extends StatefulWidget {
+  final CameraDescription camera;
+
+  const TakePictureScreen({
+    Key key,
+    @required this.camera,
+  }) : super(key: key);
+
+  @override
+  TakePictureScreenState createState() => TakePictureScreenState();
+}
+
+class TakePictureScreenState extends State<TakePictureScreen> {
+  // Add two variables to the state class to store the CameraController and
+  // the Future
+  CameraController _controller;
+  Future<void> _initializeControllerFuture;
+
+  @override
+  void initState() {
+    super.initState();
+    // In order to display the current output from the Camera, you need to
+    // create a CameraController.
+    _controller = CameraController(
+      // Get a specific camera from the list of available cameras
+      widget.camera,
+      // Define the resolution to use
+      ResolutionPreset.medium,
+    );
+
+    // Next, you need to initialize the controller. This will return a Future
+    _initializeControllerFuture = _controller.initialize();
+  }
+
+  @override
+  void dispose() {
+    // Make sure to dispose of the controller when the Widget is disposed
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    // Fill this out in the next steps
+  }
+}
+```
+
+{{site.alert.warning}}
+If you do not initialize the `CameraController`, you will *not* be able to work with
+the camera.
+{{site.alert.end}}
+
+## 4. Use a `CameraPreview` to display the camera's feed
+
+Next, you can use the `CameraPreview` Widget from the `camera` package to
+display a preview of the camera's feed.
+
+Remember: You must wait until the controller has finished initializing before
+working with the camera. Therefore, you must wait for the
+`_initializeControllerFuture` created in the previous step to complete before
+showing a `CameraPreview`.
+
+You can use a
+[`FutureBuilder`](https://docs.flutter.io/flutter/widgets/FutureBuilder-class.html)
+for exactly this purpose.
+
+<!-- skip -->
+```dart
+// You must wait until the controller is initialized before displaying the
+// camera preview. Use a FutureBuilder to display a loading spinner until the
+// controller has finished initializing
+FutureBuilder<void>(
+  future: _initializeControllerFuture,
+  builder: (context, snapshot) {
+    if (snapshot.connectionState == ConnectionState.done) {
+      // If the Future is complete, display the preview
+      return CameraPreview(_controller);
+    } else {
+      // Otherwise, display a loading indicator
+      return Center(child: CircularProgressIndicator());
+    }
+  },
+)
+```
+
+## 5. Take a picture with the `CameraController`
+
+You can also use the `CameraController` to take pictures using the
+[`takePicture`](https://pub.dartlang.org/documentation/camera/latest/camera/CameraController/takePicture.html)
+method. In this example, create a `FloatingActionButton` that takes a picture
+using the `CameraController` when a user taps on the button.
+
+Saving a picture requires 3 steps:
+
+  1. Ensure the camera is initialized
+  2. Construct a path that defines where the picture should be saved
+  3. Use the controller to take a picture and save the result to the path
+
+It is good practice to wrap these operations in a `try / catch` block in order
+to handle any errors that might occur.
+
+<!-- skip -->
+```dart
+FloatingActionButton(
+  child: Icon(Icons.camera_alt),
+  // Provide an onPressed callback
+  onPressed: () async {
+    // Take the Picture in a try / catch block. If anything goes wrong,
+    // catch the error.
+    try {
+      // Ensure the camera is initialized
+      await _initializeControllerFuture;
+
+      // Construct the path where the image should be saved using the path
+      // package.
+      final path = join(
+        // In this example, store the picture in the temp directory. Find
+        // the temp directory using the `path_provider` plugin.
+        (await getTemporaryDirectory()).path,
+        '${DateTime.now()}.png',
+      );
+
+      // Attempt to take a picture and log where it's been saved
+      await _controller.takePicture(path);
+    } catch (e) {
+      // If an error occurs, log the error to the console.
+      print(e);
+    }
+  },
+)
+```
+## 6. Display the picture with an `Image` Widget
+
+If you take the picture successfully, you can then display the saved picture
+using an `Image` widget. In this case, the picture will be stored as a file on
+the device.
+
+Therefore, you must provide a `File` to the `Image.file` constructor. You
+can create an instance of the `File` class by passing in the path you created in
+the previous step.
+
+<!-- skip -->
+```dart
+Image.file(File('path/to/my/picture.png'))
+```
+
+## Complete Example
+
+```dart
+import 'dart:async';
+import 'dart:io';
+
+import 'package:camera/camera.dart';
+import 'package:flutter/material.dart';
+import 'package:path/path.dart' show join;
+import 'package:path_provider/path_provider.dart';
+
+Future<void> main() async {
+  // Obtain a list of the available cameras on the device.
+  final cameras = await availableCameras();
+
+  // Get a specific camera from the list of available cameras
+  final firstCamera = cameras.first;
+
+  runApp(
+    MaterialApp(
+      theme: ThemeData.dark(),
+      home: TakePictureScreen(
+        // Pass the appropriate camera to the TakePictureScreen Widget
+        camera: firstCamera,
+      ),
+    ),
+  );
+}
+
+// A screen that allows users to take a picture using a given camera
+class TakePictureScreen extends StatefulWidget {
+  final CameraDescription camera;
+
+  const TakePictureScreen({
+    Key key,
+    @required this.camera,
+  }) : super(key: key);
+
+  @override
+  TakePictureScreenState createState() => TakePictureScreenState();
+}
+
+class TakePictureScreenState extends State<TakePictureScreen> {
+  CameraController _controller;
+  Future<void> _initializeControllerFuture;
+
+  @override
+  void initState() {
+    super.initState();
+    // In order to display the current output from the Camera, you need to
+    // create a CameraController.
+    _controller = CameraController(
+      // Get a specific camera from the list of available cameras
+      widget.camera,
+      // Define the resolution to use
+      ResolutionPreset.medium,
+    );
+
+    // Next, you need to initialize the controller. This will return a Future!
+    _initializeControllerFuture = _controller.initialize();
+  }
+
+  @override
+  void dispose() {
+    // Make sure to dispose of the controller when the Widget is disposed
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: Text('Take a picture!')),
+      // You must wait until the controller is initialized before displaying the
+      // camera preview. Use a FutureBuilder to display a loading spinner until
+      // the controller has finished initializing!
+      body: FutureBuilder<void>(
+        future: _initializeControllerFuture,
+        builder: (context, snapshot) {
+          if (snapshot.connectionState == ConnectionState.done) {
+            // If the Future is complete, display the preview
+            return CameraPreview(_controller);
+          } else {
+            // Otherwise, display a loading indicator
+            return Center(child: CircularProgressIndicator());
+          }
+        },
+      ),
+      floatingActionButton: FloatingActionButton(
+        child: Icon(Icons.camera_alt),
+        // Provide an onPressed callback
+        onPressed: () async {
+          // Take the Picture in a try / catch block. If anything goes wrong,
+          // catch the error.
+          try {
+            // Ensure the camera is initialized
+            await _initializeControllerFuture;
+
+            // Construct the path where the image should be saved using the path
+            // package.
+            final path = join(
+              // In this example, store the picture in the temp directory. Find
+              // the temp directory using the `path_provider` plugin.
+              (await getTemporaryDirectory()).path,
+              '${DateTime.now()}.png',
+            );
+
+            // Attempt to take a picture and log where it's been saved
+            await _controller.takePicture(path);
+
+            // If the picture was taken, display it on a new screen
+            Navigator.push(
+              context,
+              MaterialPageRoute(
+                builder: (context) => DisplayPictureScreen(imagePath: path),
+              ),
+            );
+          } catch (e) {
+            // If an error occurs, log the error to the console.
+            print(e);
+          }
+        },
+      ),
+    );
+  }
+}
+
+// A Widget that displays the picture taken by the user
+class DisplayPictureScreen extends StatelessWidget {
+  final String imagePath;
+
+  const DisplayPictureScreen({Key key, this.imagePath}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: Text('Display the Picture')),
+      // The image is stored as a file on the device. Use the `Image.file`
+      // constructor with the given path to display the image
+      body: Image.file(File(imagePath)),
+    );
+  }
+}
+```