
# The app widget

With `home:`, `SpringApplicationWidget` puts a `SpringApp` at the root: a `WidgetsApp`, or with a design starter a `MaterialApp` or `CupertinoApp`, set up by properties instead of code. Its type, title, debug banner and locales come from `spring.flutter.app.*`, its themes from `spring.flutter.theme.*`. The properties can differ per profile, so iPhones can get a `CupertinoApp` while the other platforms get a `MaterialApp`.

## Why

An app widget is mostly settings: a title, the locales, a theme and a dark theme, observers. Written in Dart, they must be kept in step with the message files and the themes by hand. From properties, the locales follow the message files, the theme follows the theme files, and a platform or a build changes them by file name.

## Example

Material on most platforms and Cupertino on iPhones: the app lists both design starters and their libraries. With two design starters it chooses the type, for every platform and again in the iOS profile (see [The type when not set](#the-type-when-not-set)); an app with one design starter leaves `type` out.

```yaml
# pubspec.yaml
dependencies:
  material_ui: ^1.11.0
  cupertino_ui: ^1.1.6
  spring_boot_starter_flutter_material: ^0.9.0
  spring_boot_starter_flutter_cupertino: ^0.9.0
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    app:
      type: material
      title: NEON Books
      description: The bookshop of the NEON district.
      debug-banner: false
      locales: en, ja, pt_BR
```

```yaml
# lib/resources/application-ios.yml: the iOS look on iPhones
spring:
  flutter:
    app:
      type: cupertino
```

```dart
@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    home: const BookListPage(), // a MaterialApp, or a CupertinoApp on iOS
  ),
);
```

## The properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.app.type` | text: `widgets`, `material`, `cupertino`, or the type of an app factory of your own | not set: the one design starter's type (`material`, `cupertino`), else `widgets`; with several, required | The app widget: `WidgetsApp` (this starter's own, no design library), `MaterialApp` (needs `spring_boot_starter_flutter_material`; needed by `Scaffold`, `AppBar` and the other Material widgets) or `CupertinoApp` (needs `spring_boot_starter_flutter_cupertino`). See [App factories](#app-factories) |
| `spring.flutter.app.title` | text | empty | The app's name for the OS: the task switcher, the browser tab. The web build also writes it into `web/index.html` (`<title>`) and `web/manifest.json` (`name`, `short_name`) |
| `spring.flutter.app.description` | text | none | What the app is, in a sentence. Not used at run time: the web build writes it into `web/index.html` (`<meta name="description">`) and `web/manifest.json` |
| `spring.flutter.app.debug-banner` | `true`, `false` | `true` | Flutter's DEBUG banner in debug builds |
| `spring.flutter.app.locales` | comma-separated language tags (`en`, `pt_BR`, `zh_Hant_TW`) | the languages of the message files | The locales the app supports |

Write `locales` as one comma-separated value, also in YAML (`locales: en, ja`). The app widget reads it as a single value, so a YAML list (`[en, ja]`) is not seen; the locales then come from the message files.

## The type when not set

`spring.flutter.app.type` need not be set. As Spring Boot deduces `spring.main.web-application-type` from the class path, the application's starters decide:

| The application has | The app is |
|---|---|
| no design starter | `widgets`, a `WidgetsApp` |
| one design starter: `spring_boot_starter_flutter_material` or `spring_boot_starter_flutter_cupertino` | `material` or `cupertino` |
| one `SpringAppFactory` bean of its own type (`ocean`, see [App factories](#app-factories)) | that type |
| app factories of several types, both design starters for instance | none: the start fails and asks for the property |

With several, the failure report names the property and the types:

```text
Invalid argument(s) (spring.flutter.app.type): not set, and the application has app widgets of several types: cupertino, material. Choose one, for every platform or in a profile of each (spring.flutter.app.type=cupertino in application-ios.properties)
```

Set, the property always wins: `widgets` keeps a `WidgetsApp` although a design starter came in through another package, and an app that sets its type is not changed by a starter it adds.

## Locales

By default the app supports the languages it has texts for: `messages.properties` counts as English, and each `messages_<locale>.properties` adds its locale (`messages_ja` adds `ja`, `messages_pt_BR` adds `pt_BR`). So the app's locales and `context.message` agree. With other files than `messages*.properties`, set `spring.messages.basename` as one comma-separated value with `/` as the separator (`i18n/messages,i18n/errors`), and the starter looks for the locales of those files.

Flutter's own translations for the app type (the texts of its widgets, in every language) are added by the type's app factory (`SpringAppFactory.localizationsDelegates`): `GlobalWidgetsLocalizations` for `widgets`; the Material starter's factory adds Material's (`GlobalMaterialLocalizations`), the Cupertino starter's Cupertino's (`GlobalCupertinoLocalizations`). `flutter_localizations` comes with the starter. See [Messages and languages](messages.md).

## The theme

The theme shown is the one the `ThemeSelection` bean picks. `widgets` gets the theme's text style and color. With the Material starter, `material` gets the Material `ThemeData` of the theme shown (and its dark counterpart for `system`); with the Cupertino starter, `cupertino` gets the `CupertinoThemeData`. A theme picked at run time, or loaded from a server, shows at once. A `SpringTheme` above the app gives the theme to the app's own widgets. See [Themes](themes/index.md).

## Navigator observers

Every `NavigatorObserver` bean becomes an observer of the app's navigator, in `@Order`:

```dart
// Logs every screen the user opens.
@Component()
@Log()
class ScreenLog extends NavigatorObserver {
  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) =>
      log.info('Opened ${route.settings.name}');
}
```

## FlutterAppCustomizer

What no property covers is changed by a `FlutterAppCustomizer` bean: a `builder`, keyboard `shortcuts`, the `scrollBehavior`, the app's own localization delegates. Each one gets the `FlutterAppSettings` once, before the app widget is first built, in `@Order`:

```dart
// The app's own translations, and text that never grows past 130 %.
@Component()
class AppLocalizations implements FlutterAppCustomizer {
  @override
  void customize(FlutterAppSettings app) {
    app.localizationsDelegates.add(LegalTerms.delegate);
    app.builder = (context, child) => MediaQuery.withClampedTextScaling(
      maxScaleFactor: 1.3,
      child: child!,
    );
  }
}
```

The fields of `FlutterAppSettings`:

| Field | From | Meaning |
|---|---|---|
| `type` | `spring.flutter.app.type`, or when not set the type the starters decide on | The type of the app factory that builds the app widget, a `String` (`widgets`, `material`, `cupertino`) |
| `title` | `spring.flutter.app.title` | The app's name for the OS |
| `debugShowCheckedModeBanner` | `spring.flutter.app.debug-banner` | The DEBUG banner |
| `supportedLocales` | `spring.flutter.app.locales` or the message files | The app's locales |
| `localizationsDelegates` | the app factory's (Flutter's for the type) | Add the app's own here |
| `navigatorObservers` | the `NavigatorObserver` beans | The navigator's observers |
| `builder` | `null` | Wraps the navigator, like `MaterialApp.builder` |
| `scrollBehavior` | `null` | The app's scroll behavior (not used by a `WidgetsApp`) |
| `shortcuts` | `null` | The app's keyboard shortcuts in Flutter's form; for actions in the configuration, see [Keyboard shortcuts](shortcuts.md) |

The starter uses customizers itself: the keyboard shortcuts and the debug panel are installed around the navigator that way. Spring Boot (Java) customizes its web server the same way, with a `WebServerFactoryCustomizer` bean.

## Routes

`home` is the first page, and the app navigates with `Navigator`. Without `home`, `SpringApp` builds the router form of the app widget (`WidgetsApp.router`, or `MaterialApp.router` and `CupertinoApp.router` of the design starters) on the application's `RouterConfig<Object>` bean: the one [spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md) adds, or the app's own.

## App factories

`spring.flutter.app.type` is a text: the type of a `SpringAppFactory` bean, which builds the app widget. Types are compared without case.

| Type | App factory | From |
|---|---|---|
| `widgets` | `WidgetsAppFactory` | `spring_boot_starter_flutter` (its own) |
| `material` | `MaterialAppFactory` (bean `materialAppFactory`) | [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) |
| `cupertino` | `CupertinoAppFactory` (bean `cupertinoAppFactory`) | [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md) |

A design of your own is one more bean:

```dart
// An app widget of the company's own design system.
@Component()
class OceanAppFactory implements SpringAppFactory {
  @override
  String get type => 'ocean';

  @override
  List<LocalizationsDelegate<Object?>> get localizationsDelegates =>
      const [GlobalWidgetsLocalizations.delegate];

  @override
  Widget build(BuildContext context, SpringAppRequest app) =>
      OceanApp(title: app.settings.title, home: app.home);
}
```

`spring.flutter.app.type: ocean` then builds an `OceanApp`; without a design starter in the application, the type need not be set, as the one factory of its own decides. The `SpringAppRequest` has the settings, the themes, the theme selection, the theme shown, the `builder` to pass on as it is, and `home` or the `router`. See [Design libraries](design-libraries.md).

## Checked at the start

The settings are made once per context, when the application starts. An invalid value (`debug-banner=maybe`) fails the start with the failure report, naming the property. So does a type no app factory has: `material` or `cupertino` without its starter names the starter to add (`the app widget of type material is built by spring_boot_starter_flutter_material: add it to the dependencies (this application has: widgets)`), any other type lists the known ones (`type=swing`: `one of: widgets`).

## With your own app widget

With `SpringApplicationWidget(child: ...)` you write your own app widget, and these keys are not used. In widget tests, put a `SpringApp` under a `SpringScope` to get the app widget of the properties (see [Testing](testing.md)).

## See also

- [SpringApplicationWidget](application-widget.md)
- [Design libraries](design-libraries.md)
- [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md)
- [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md)
- [Themes](themes/index.md)
- [Messages and languages](messages.md)
- [All properties](properties.md)
