SpringApplicationWidget
SpringApplicationWidget is the root widget you pass to runApp. It starts the application: it reads the configuration files, creates the beans and runs the application's runners. Meanwhile it shows a splash screen. When the start fails, it shows a failure screen and logs the report. Once the context is ready, it gives it to every widget below.
Why
A Spring application starts asynchronously: files are read, fonts loaded, beans created. A Flutter app must draw something from its first frame. The widget joins the two: one widget in runApp, and the app shows its splash while the context starts, then the app itself. It also does what a Flutter app needs and a server does not: platform profiles, the app's lifecycle, hot reload, the desktop window.
Example
// lib/main.dart
import 'package:flutter/widgets.dart';
import 'package:spring_boot_starter_flutter/spring_boot_starter_flutter.dart';
import 'spring_gen/main.spring.dart';
@SpringBootApplication()
void main() => runApp(
SpringApplicationWidget(
// A function, not the value: after a hot reload the widget calls it
// again to get the new generated code.
application: () => springApplication,
// Optional: the theme's splash is used when there is no builder.
splash: (context) => const ColoredBox(color: Color(0xFFFFFFFF)),
failure: (context, error) => ErrorScreen(error),
home: const BookListPage(),
),
);
Parameters
| Parameter | Default | Meaning |
|---|---|---|
application |
required | Returns the application to run: () => springApplication, the variable the generator writes into main.spring.dart |
home |
none | The first page. The widget builds the app widget around it from spring.flutter.app.* (see The app widget) |
child |
none | Your own app widget (MaterialApp, ...) instead. Give home or child, not both |
splash |
the theme's splash, else an empty box |
What is shown while the application starts. It wins over the theme's splash |
failure |
a plain screen with the error (only a short note in release builds) | What is shown when the start, or a restart after a hot reload, fails. The failure is logged either way |
args |
none | Command-line arguments (--name=value), read as properties; for desktop apps started with some |
rerunRunnersOnReload |
false |
Whether ApplicationRunner and CommandLineRunner beans run again after a hot reload restarts the context |
With neither home nor child, the app widget is built on the application's router: the RouterConfig<Object> bean that spring_boot_starter_flutter_navigation adds. A start without a router then fails with a message saying what to add.
What it does
Besides starting the application, the widget:
- adds the platform's profiles (
androidandmobile,web,macosanddesktop, ...) and the build's (debug,profile,release); see Configuration; - does not read the OS environment variables unless a build defines
spring.flutter.scan-os-environment=true; - loads the font files among the app's assets (see Assets and fonts);
- shows the active theme's splash, which follows the start's progress, and runs the
SplashTaskbeans before the app shows (see The splash and the start); - checks that every bean a Spring widget needs exists, so a missing one fails the start instead of a later build;
- sets the desktop window from
spring.flutter.desktop.window.*before the first frame (see The desktop window); - puts SQLite databases into the app's directory (see SQLite databases);
- publishes the app's lifecycle and pauses the context in the background (see The app lifecycle);
- restarts the context after a hot reload that changed beans (see Hot reload);
- closes the context when it is removed from the tree:
@PreDestroymethods run and lifecycle beans stop.
When the start fails
A bean that throws, a property with an invalid value or a missing bean stops the start. The widget then:
- logs the failure report, as a Spring Boot app does (the cause, the bean, the property, the valid values);
- shows
failure, or its default screen: the error in debug and profile builds, a short note in release builds.
After a hot reload that fixed the problem, the widget starts the application anew.
// A failure screen in the app's style, with the error for developers.
SpringApplicationWidget(
application: () => springApplication,
failure: (context, error) => Directionality(
textDirection: TextDirection.ltr,
child: Center(child: Text(kReleaseMode ? 'Something went wrong.' : '$error')),
),
home: const BookListPage(),
)
The failure screen is shown above any app widget, so it cannot use Theme.of or Localizations; give it what it needs, such as a Directionality.
Your own app widget
With child, you write the app widget yourself and the spring.flutter.app.* keys are not used. The themes still work: read them from the SpringThemes and ThemeSelection beans; a MaterialApp takes Material's ThemeData from the MaterialThemes bean of spring_boot_starter_flutter_material. Put the keyboard shortcuts in its builder (see Keyboard shortcuts):
// A MaterialApp: material_ui and spring_boot_starter_flutter_material.
SpringApplicationWidget(
application: () => springApplication,
child: Builder(
builder: (context) => MaterialApp(
title: 'NEON Books',
theme: context.bean<MaterialThemes>().theme('light'),
builder: (context, child) => KeyboardShortcutsScope(
shortcuts: context.bean<KeyboardShortcuts>(),
child: child!,
),
home: const BookListPage(),
),
),
)
In tests
To test the start itself (the splash, a failed start, the platform profiles), pump SpringApplicationWidget as runApp does. The widget takes no bean overrides; for most widget tests, use springBootTest and a SpringScope instead (see Testing).
In Spring (Java)
Spring has no widget. The nearest thing is the main method of a Spring Boot app, SpringApplication.run(App.class, args). The failure report is the same one a Spring Boot app prints.