Merge branch 'develop'

Author: juliansteenbakker

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 7.0.1
+
+* Added error handling for when `MobileScannerController.start` is called without an active `MobileScanner` widget.
+
 ## 7.0.0
 
 This version finalizes all changes from the beta and release candidate cycles and introduces major improvements, bug fixes, and breaking changes.
@@ -13,6 +17,7 @@ This version finalizes all changes from the beta and release candidate cycles an
 **Highlights**
 
 * [iOS/macOS] Migrated to the Vision API with a unified Apple codebase.
+* [iOS] Minimum iOS version changed from 15 to 12.
 * [Android] Removed dependency on `kotlin-bom` and updated CameraX and camera-camera2 dependencies.
 * Support for pause/resume functionality across platforms.
 * `MobileScannerErrorCode` now includes readable error messages in debug mode.

android/build.gradle

@@ -9,7 +9,7 @@ buildscript {
     }
 
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.9.2'
+        classpath 'com.android.tools.build:gradle:8.10.1'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }
@@ -78,5 +78,5 @@ dependencies {
     implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
 
     testImplementation 'org.jetbrains.kotlin:kotlin-test'
-    testImplementation 'org.mockito:mockito-core:5.17.0'
+    testImplementation 'org.mockito:mockito-core:5.18.0'
 }

lib/src/enums/mobile_scanner_error_code.dart

@@ -45,14 +45,122 @@ enum MobileScannerErrorCode {
   /// The controller is not attached to any widget.
   ///
   /// This error occurs when [MobileScannerController.start] is called
-  /// before the controller has been attached to a [MobileScanner] widget.
-  ///
-  /// To fix this error:
-  /// - Ensure that a [MobileScanner] widget is built and linked to the
-  ///   controller.
-  /// - The [MobileScanner] widget automatically attaches the controller
-  ///   when it is initialized.
-  /// - Wait until the widget is fully built before calling start.
+  /// but there is no active [MobileScanner] widget
+  /// for the [MobileScannerController] in the widget tree.
+  ///
+  /// To avoid this error, ensure that a [MobileScanner] widget
+  /// is attached to the widget tree
+  /// when [MobileScannerController.start] is called.
+  ///
+  /// BAD:
+  ///
+  /// ```dart
+  /// class ScannerExample extends StatefulWidget {
+  ///   const ScannerExample({super.key});
+  ///
+  ///   @override
+  ///   State<ScannerExample> createState() => _ScannerExampleState();
+  /// }
+  ///
+  /// class _ScannerExampleState extends State<ScannerExample> {
+  ///   final MobileScannerController controller = MobileScannerController();
+  ///
+  ///   bool _showScanner = false;
+  ///
+  ///   @override
+  ///   void initState() {
+  ///     super.initState();
+  ///     // The MobileScanner is only in the widget tree after the button is pressed.
+  ///     controller.start();
+  ///   }
+  ///
+  ///   @override
+  ///   Widget build(BuildContext context) {
+  ///     return Column(
+  ///       children: [
+  ///         ElevatedButton(
+  ///           onPressed: () {
+  ///             setState(() {
+  ///               _showScanner = true;
+  ///             });
+  ///           },
+  ///           child: const Text('Button'),
+  ///         ),
+  ///         if (_showScanner)
+  ///           Expanded(child: MobileScanner(controller: controller)),
+  ///       ],
+  ///     );
+  ///   }
+  /// }
+  /// ```
+  ///
+  /// GOOD:
+  ///
+  /// ```dart
+  /// class ScannerExample extends StatefulWidget {
+  ///   const ScannerExample({super.key});
+  ///
+  ///   @override
+  ///   State<ScannerExample> createState() => _ScannerExampleState();
+  /// }
+  ///
+  /// class _ScannerExampleState extends State<ScannerExample> {
+  ///   final MobileScannerController controller = MobileScannerController();
+  ///
+  ///   @override
+  ///   Widget build(BuildContext context) {
+  ///     return Column(
+  ///       children: [
+  ///         ElevatedButton(
+  ///           // The MobileScanner is already in the widget tree.
+  ///           onPressed: controller.start,
+  ///           child: const Text('Button'),
+  ///         ),
+  ///         Expanded(child: MobileScanner(controller: controller)),
+  ///       ],
+  ///     );
+  ///   }
+  /// }
+  /// ```
+  ///
+  /// GOOD:
+  ///
+  /// ```dart
+  /// class ScannerExample extends StatefulWidget {
+  ///   const ScannerExample({super.key});
+  ///
+  ///   @override
+  ///   State<ScannerExample> createState() => _ScannerExampleState();
+  /// }
+  ///
+  /// class _ScannerExampleState extends State<ScannerExample> {
+  ///   final MobileScannerController controller = MobileScannerController();
+  ///
+  ///   bool _showScanner = false;
+  ///
+  ///   void start() {
+  ///     if (_showScanner) return;
+  ///
+  ///     setState(() {
+  ///       _showScanner = true;
+  ///     });
+  ///
+  ///     // The MobileScanner will be in the widget tree in the next frame.
+  ///     controller.start();
+  ///   }
+  ///
+  ///   @override
+  ///   Widget build(BuildContext context) {
+  ///     return Column(
+  ///       children: [
+  ///         ElevatedButton(onPressed: start, child: const Text('Button')),
+  ///         if (_showScanner)
+  ///           Expanded(child: MobileScanner(controller: controller)),
+  ///       ],
+  ///     );
+  ///   }
+  /// }
+  /// ```
   controllerNotAttached;
 
   /// Convert the given [PlatformException.code] to a [MobileScannerErrorCode].

lib/src/mobile_scanner.dart

@@ -328,7 +328,7 @@ class _MobileScannerState extends State<MobileScanner>
   }
 
   @override
-  Future<void> dispose() async {
+  void dispose() {
     super.dispose();
     unawaited(disposeMobileScanner());
   }

lib/src/mobile_scanner_controller.dart

@@ -6,6 +6,7 @@ import 'dart:async';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter/widgets.dart';
+import 'package:meta/meta.dart';
 import 'package:mobile_scanner/src/enums/barcode_format.dart';
 import 'package:mobile_scanner/src/enums/camera_facing.dart';
 import 'package:mobile_scanner/src/enums/detection_speed.dart';
@@ -128,7 +129,10 @@ class MobileScannerController extends ValueNotifier<MobileScannerState> {
   StreamSubscription<DeviceOrientation>? _deviceOrientationSubscription;
 
   bool _isDisposed = false;
-  bool _isAttached = false;
+  // This completer keeps track of whether the MobileScanner widget,
+  // that is attached to this controller,
+  // called its `initState()` lifecycle method.
+  final Completer<void> _isAttachedCompleter = Completer<void>();
 
   void _disposeListeners() {
     _barcodesSubscription?.cancel();
@@ -336,13 +340,35 @@ class MobileScannerController extends ValueNotifier<MobileScannerState> {
       );
     }
 
-    if (!_isAttached) {
-      throw MobileScannerException(
-        errorCode: MobileScannerErrorCode.controllerNotAttached,
-        errorDetails: MobileScannerErrorDetails(
-          message: MobileScannerErrorCode.controllerNotAttached.message,
-        ),
-      );
+    // If start was called before the MobileScanner widget
+    // had a chance to call its initState method,
+    // wait for it to be called, using a timeout.
+    if (!_isAttachedCompleter.isCompleted) {
+      // The timeout is currently an arbitrary value,
+      // which should be long enough for the next frame
+      // to propagate any pending changes to the widget tree.
+      await _isAttachedCompleter.future
+          .timeout(const Duration(milliseconds: 500))
+          .catchError((Object error, StackTrace stackTrace) {
+            throw MobileScannerException(
+              errorCode: MobileScannerErrorCode.controllerNotAttached,
+              errorDetails: MobileScannerErrorDetails(
+                message: MobileScannerErrorCode.controllerNotAttached.message,
+                details: stackTrace.toString(),
+              ),
+            );
+          });
+
+      // Abort if the controller was disposed
+      // while waiting for the widget to be attached.
+      if (_isDisposed) {
+        throw MobileScannerException(
+          errorCode: MobileScannerErrorCode.controllerDisposed,
+          errorDetails: MobileScannerErrorDetails(
+            message: MobileScannerErrorCode.controllerDisposed.message,
+          ),
+        );
+      }
     }
 
     if (cameraDirection == CameraFacing.unknown) {
@@ -531,16 +557,23 @@ class MobileScannerController extends ValueNotifier<MobileScannerState> {
     }
 
     _isDisposed = true;
-    _isAttached = false;
     unawaited(_barcodesController.close());
     super.dispose();
 
     await MobileScannerPlatform.instance.dispose();
   }
 
-  /// Keeps track if the controller is correctly attached to the MobileScanner
-  /// widget.
+  /// Signal to this [MobileScannerController] that it is attached
+  /// to a [MobileScanner] widget.
+  ///
+  /// This method is called by `_MobileScannerState.initState()`
+  /// and is not intended to be used directly.
+  @internal
   void attach() {
-    _isAttached = true;
+    if (_isAttachedCompleter.isCompleted) {
+      return;
+    }
+
+    _isAttachedCompleter.complete();
   }
 }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: mobile_scanner
 description: A universal Flutter barcode and QR code scanner using CameraX/ML Kit for Android, AVFoundation/Apple Vision for iOS & macOS, and ZXing for web.
-version: 7.0.0
+version: 7.0.1
 repository: https://github.com/juliansteenbakker/mobile_scanner
 
 screenshots:
@@ -21,14 +21,15 @@ dependencies:
     sdk: flutter
   flutter_web_plugins:
     sdk: flutter
+  meta: ">=1.16.0 <2.0.0"
   plugin_platform_interface: ^2.0.2
   web: ">=0.5.1 <2.0.0"
 
 dev_dependencies:
   flutter_test:
     sdk: flutter
   mocktail: ^1.0.4
-  very_good_analysis: ^7.0.0
+  very_good_analysis: ">=7.0.0 <9.0.0"
 
 flutter:
   plugin: