5.6.0

Drawner · Drawner · commit ce7fda95366c · 2024-12-14T15:29:28.000-06:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,12 @@
 
+## 5.6.0
+December 14, 2024
+- Introduce Splash screen to example app
+- deferFirstFrame() in initState() in app_statefulwidget.dart
+- Add mixins: class AppErrorHandler with HandleError, StateXonErrorMixin {
+- Update the function, runApp(), with optional error handling
+  void runApp(m.Widget app, {FlutterExceptionHandler? onError, bool? runZoneGuard}) {
+
 ## 5.5.0
 December 11, 2024
 - Introduced parameter, themeAnimationStyle,for class MaterialApp
diff --git a/example/assets/images/meow.gif b/example/assets/images/meow.gif
diff --git a/example/integration_test/src/tests/unit/src/controller/test_app.dart b/example/integration_test/src/tests/unit/src/controller/test_app.dart
@@ -12,7 +12,7 @@ import '_unit_test_controller.dart';
 Future<void> testAppController() async {
   // This class extends StateXController but implements
   // initAsync(), onAsyncError() and onConnectivityChanged()
-  final app = AppController();
+  final app = AppStateXController();
 
   // Override to run any asynchronous operations before the app starts
   await app.initAsync();
diff --git a/example/lib/src/app/controller/example_controller.dart b/example/lib/src/app/controller/example_controller.dart
@@ -7,7 +7,7 @@ import '/src/model.dart' show Settings;
 import '/src/view.dart';
 
 ///
-class ExampleAppController extends AppController {
+class ExampleAppController extends AppStateXController {
   factory ExampleAppController() => _this ??= ExampleAppController._();
   ExampleAppController._();
   static ExampleAppController? _this;
@@ -251,9 +251,20 @@ class ExampleAppController extends AppController {
   /// **************  Life cycle events ****************
 
   /// Called to complete any asynchronous operations.
+  /// In production, this is where databases are opened, logins attempted, etc.
   @override
   Future<bool> initAsync() async {
     final init = await super.initAsync();
+
+    // Demonstrating ways to retrieve the StatefulWidget
+    var widget = firstState!.widget as FlutteryExampleApp;
+    widget = rootState!.widget as FlutteryExampleApp;
+
+    // For demonstration purposes, wait for the Splash Screen to appear for a time at startup.
+    await Future<bool>.delayed(const Duration(seconds: 10), () {
+      return true;
+    });
+
     //
     if (initAsyncError) {
       initAsyncError = false;
diff --git a/example/lib/src/app/view/app.dart b/example/lib/src/app/view/app.dart
@@ -5,12 +5,18 @@ import '/src/model.dart';
 
 import '/src/view.dart';
 
-/// App
+/// The App's State object
 class FlutteryExampleApp extends AppStatefulWidget {
-  FlutteryExampleApp({super.key});
+  FlutteryExampleApp({super.key}) : super(
+    splashScreen: const SplashScreen(),   // three ways to present a Splash screen
+    inSplashScreen: () => const SplashScreen(),
+  );
   // This is the 'App State object' of the application.
   @override
   AppStateX<FlutteryExampleApp> createAppState() => _ExampleAppState();
+
+  @override
+  Widget? onSplashScreen(BuildContext context) => const SplashScreen();
 }
 
 /// This is the 'View' of the application.
diff --git a/example/lib/src/app/view/splash_screen.dart b/example/lib/src/app/view/splash_screen.dart
@@ -0,0 +1,21 @@
+//
+import 'package:flutter/material.dart';
+
+/// A very simple Splash screen
+class SplashScreen extends StatelessWidget {
+  ///
+  const SplashScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) => const OverflowBox(
+        minWidth: 0,
+        minHeight: 0,
+        maxWidth: double.infinity,
+        maxHeight: double.infinity,
+        child: SizedBox(
+          width: 100,
+          height: 100,
+          child: Image(image: AssetImage('assets/images/meow.gif')),
+        ),
+      );
+}
diff --git a/example/lib/src/app/view_app.dart b/example/lib/src/app/view_app.dart
@@ -12,3 +12,6 @@ export 'view/menu/radio_material.dart';
 
 // Color picker routine
 export 'view/color_picker.dart';
+
+// Splash Screen
+export 'view/splash_screen.dart';
diff --git a/example/lib/src/main/controller/counter_controller.dart b/example/lib/src/main/controller/counter_controller.dart
@@ -5,7 +5,7 @@ import '/src/model.dart';
 
 import '/src/view.dart';
 
-class CounterController extends AppController {
+class CounterController extends AppStateXController {
   factory CounterController() => _this ??= CounterController._();
   CounterController._() : super() {
     //
diff --git a/example/lib/src/main/grid_app_example/gridview/images/view/random_cat.dart b/example/lib/src/main/grid_app_example/gridview/images/view/random_cat.dart
@@ -29,4 +29,8 @@ class _RandomCatState extends ImageAPIStateX<RandomCat> {
             path: 'api/v2/random/animal/cat',
           ),
         );
+
+  /// Supply a 'splash screen' while the FutureBuilder is processing.
+  @override
+  Widget? onSplashScreen(BuildContext context) => const SplashScreen();
 }
diff --git a/example/pubspec.lock b/example/pubspec.lock
@@ -312,7 +312,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "5.5.0"
+    version: "5.6.0"
   fuchsia_remote_debug_protocol:
     dependency: transitive
     description: flutter
diff --git a/example/pubspec.yaml b/example/pubspec.yaml
@@ -3,7 +3,7 @@ description: Create a production-ready Flutter App using a 'framework' full of f
 homepage: https://www.andrioussolutions.com
 repository: https://github.com/AndriousSolutions/flutter_framework/example
 
-version: 1.3.0
+version: 1.4.0
 
 environment:
   sdk: '>=3.0.0 <4.0.0'
@@ -82,7 +82,8 @@ flutter:
   # assets:
   #   - images/a_dot_burr.jpeg
   #   - images/a_dot_ham.jpeg
-
+  assets:
+    - assets/images/
   # An image asset can refer to one or more resolution-specific "variants", see
   # https://flutter.dev/assets-and-images/#resolution-aware.
 
diff --git a/lib/controller/error_handler.dart b/lib/controller/error_handler.dart
@@ -10,6 +10,8 @@
 import 'dart:ui' as i
     show ParagraphBuilder, ParagraphConstraints, ParagraphStyle, TextStyle;
 
+import '/controller.dart' show HandleError;
+
 import '/view.dart'
     show
         App,
@@ -36,6 +38,7 @@ import '/view.dart'
         PaintingContext,
         PaintingStyle,
         Rect,
+        StateXonErrorMixin,
         TextBaseline,
         TextDirection,
         Widget;
@@ -45,6 +48,7 @@ import 'package:flutter/rendering.dart'
         Color,
         DiagnosticPropertiesBuilder,
         EdgeInsets,
+        ErrorDescription,
         FlutterError,
         Offset,
         Paint,
@@ -62,14 +66,14 @@ typedef ReportErrorHandler = Future<void> Function(
 
 /// {@category Error handling}
 /// Your App's error handler.
-class AppErrorHandler {
+class AppErrorHandler with HandleError, StateXonErrorMixin {
   /// Singleton Pattern with only one instance of this Error Handler.
   /// Optionally supply the Error handler, Builder, and Report routines.
   factory AppErrorHandler({
     FlutterExceptionHandler? handler,
     ErrorWidgetBuilder? screen,
     ReportErrorHandler? report,
-    bool? presentError,
+    bool? presentError, //  Present error to user or not
     bool? allowNewErrorHandlers,
     i.ParagraphStyle? paragraphStyle,
     i.TextStyle? textStyle,
@@ -340,7 +344,7 @@ class AppErrorHandler {
     InformationCollector? informationCollector,
   }) async {
     if (_errorReport == null) {
-      message ??= 'while attempting to execute your app';
+      message ??= 'while attempting to run your app';
       library ??= 'Your app';
       _debugReportException(
         ErrorSummary(message),
@@ -356,22 +360,30 @@ class AppErrorHandler {
 
   /// Report the error in an isolate.
   void isolateError(dynamic ex, StackTrace stack) {
-    reportError(
-      ex,
-      stack,
-      message: 'while attempting to execute main()',
-      library: 'likely main.dart',
-    );
+
+    // Record the Exception
+    getError(ex);
+
+    FlutterError.reportError(FlutterErrorDetails(
+      exception: ex,
+      stack: StackTrace.current,
+      context: ErrorDescription('error in main()'),
+      library: 'main.dart',
+    ));
   }
 
   /// Report the error in a zone.
   void runZonedError(dynamic ex, StackTrace stack) {
-    reportError(
-      ex,
-      stack,
-      message: 'while attempting to execute runApp()',
-      library: 'controller/app.dart',
-    );
+
+    // Record the Exception
+    getError(ex);
+
+    FlutterError.reportError(FlutterErrorDetails(
+      exception: ex,
+      stack: stack,
+      context: ErrorDescription('error in file containing main()'),
+      library: 'main.dart',
+    ));
   }
 
   /// Supplies the error details to the designated error handler.
diff --git a/lib/controller/platforms/run_app.dart b/lib/controller/platforms/run_app.dart
@@ -5,18 +5,26 @@
 //          Created  28 Sep 2021
 //
 
+import 'dart:async' show runZonedGuarded;
+
 import 'dart:isolate' show Isolate, RawReceivePort;
 
-import 'package:flutter/foundation.dart' show kIsWeb;
+import 'package:flutter/foundation.dart'
+    show ErrorHint, FlutterErrorDetails, FlutterExceptionHandler, kDebugMode, kIsWeb;
 
-import 'package:flutter/material.dart' as m show Widget, runApp;
+import 'package:flutter/material.dart' as m
+    show FlutterError, FlutterErrorDetails, Widget, runApp;
 
 import '/controller.dart' as c show AppErrorHandler;
 
 /// Add an Error Handler right at the start.
-void runApp(m.Widget app) {
-  // Don't call WidgetsFlutterBinding.ensureInitialized()
-  // since the runApp() function itself calls it internally
+void runApp(
+  m.Widget app, {
+  FlutterExceptionHandler? onError,
+  bool? runZoneGuard,
+}) {
+  // Assign an error handler (Will be replaced after)
+  c.AppErrorHandler.set(handler: _RunAppErrorHandler(onError).handler);
 
   // Instantiate the app's error handler.
   final handler = c.AppErrorHandler();
@@ -36,5 +44,83 @@ void runApp(m.Widget app) {
     }).sendPort);
   }
 
-  m.runApp(app);
+  // Don't call WidgetsFlutterBinding.ensureInitialized()
+  // since the runApp() function itself calls it internally
+
+  // Run in a new zone with an error handler
+  if (runZoneGuard ?? true) {
+    // Catch any errors attempting to execute runApp();
+    runZonedGuarded(() {
+      m.runApp(app);
+    }, handler.runZonedError);
+  } else {
+    m.runApp(app);
+  }
+}
+
+class _RunAppErrorHandler {
+  _RunAppErrorHandler([this.onError]);
+  // Error handler function
+  final FlutterExceptionHandler? onError;
+
+  /// Handle any errors in this runApp().
+  void handler(m.FlutterErrorDetails details) {
+    // The Fluttery Framework's error handler
+    final appHandler = c.AppErrorHandler();
+
+    try {
+      // Record the error
+      appHandler.getError(details.exception);
+
+      // Handle the Flutter Error Details
+      handleException(appHandler, details);
+
+      // Possibly a routine is available
+      appHandler.onError(details);
+
+      // Call the supplied error handler
+      onError?.call(details);
+      //
+    } catch (e, stack) {
+      // Throw in DebugMode.
+      if (kDebugMode) {
+        // Set the original error routine. Allows the handler to throw errors.
+        m.FlutterError.onError = appHandler.oldOnError;
+        // Rethrow to be handled by the original routine.
+        rethrow;
+      } else {
+        // Record the error
+        appHandler.reportError(e, stack);
+      }
+    }
+  }
+
+  /// Handle the Exception
+  bool handleException(
+    c.AppErrorHandler handler,
+    m.FlutterErrorDetails details,
+  ) {
+    // ignore: prefer_final_locals
+    var handled = true;
+    final msg = details.exceptionAsString();
+    final name = msg.split('\n').first;
+    //
+    switch (name) {
+      case 'Zone mismatch.':
+        details = FlutterErrorDetails(
+          exception: details.exception,
+          stack: details.stack,
+          library: 'run_app.dart',
+          context: ErrorHint(
+            "with unnecessary call for binding.\nPlease remove call, WidgetsFlutterBinding.ensureInitialized();\nIf still required, please set the 'runZoneGuard' parameter to false: runApp(runZoneGuard: false)",
+          ),
+          informationCollector: details.informationCollector,
+        );
+      default:
+      // handled = false;
+    }
+    // Log the error
+    handler.logErrorDetails(details);
+    return handled;
+  }
 }
diff --git a/lib/view/app_object.dart b/lib/view/app_object.dart
@@ -817,4 +817,4 @@ class AppDrawer extends StatelessWidget {
       ),
     );
   }
-}
+}
diff --git a/lib/view/app_statefulwidget.dart b/lib/view/app_statefulwidget.dart
diff --git a/lib/view/app_statex.dart b/lib/view/app_statex.dart
diff --git a/pubspec.lock b/pubspec.lock
diff --git a/pubspec.yaml b/pubspec.yaml

Original file line number	Diff line number	Diff line change
`@@ -29,4 +29,8 @@ class _RandomCatState extends ImageAPIStateX<RandomCat> {`
`29`	`29`	`path: 'api/v2/random/animal/cat',`
`30`	`30`	`),`
`31`	`31`	`);`
	`32`	`+`
	`33`	`+ /// Supply a 'splash screen' while the FutureBuilder is processing.`
	`34`	`+ @override`
	`35`	`+ Widget? onSplashScreen(BuildContext context) => const SplashScreen();`
`32`	`36`	`}`