# Preferences and settings

With a module that provides the preferences role, such as [`shared_preferences`](https://doc.saymyframe.com/modules/shared-preferences.md), a generated app remembers its settings between its launches. An app with [`material_theme`](https://doc.saymyframe.com/modules/material-theme.md), [`gen_l10n`](https://doc.saymyframe.com/modules/gen-l10n.md), [`onboarding`](https://doc.saymyframe.com/modules/onboarding.md) or [`local_notifications`](https://doc.saymyframe.com/modules/local-notifications.md) always has such a module, since it remembers the theme mode, the language, whether the onboarding is finished, and whether the app asked for the permission to show notifications. With [`settings`](https://doc.saymyframe.com/modules/settings.md), the app has a screen that shows its settings. This page shows how the code you write uses both, and [How settings work](https://doc.saymyframe.com/concepts/settings.md) explains the roles behind them.

:::warning
The preferences are for settings, such as the theme mode or whether the user has dismissed a hint, and not for secrets. Nothing in them is encrypted, and a backup of the device carries them. Never store a token, a password, an API key or an encryption key there. A secret belongs in the secure storage of the platform, the Keychain on iOS and the Keystore on Android.
:::

## The preferences of the app

The preferences role generates `lib/core/preferences/app_preferences.dart`, whichever module provides it:

| | |
| --- | --- |
| `AppPreferences` | The interface of the preferences: `getString`, `getBool`, `getInt`, `getDouble` and `getStringList`, a `set…` for each of them, and `remove`. |
| `initPreferences()` | Opens the preferences and gives them to the restorers, described below. `bootstrap()` awaits it in its platform phase, before the services of the app and before the first frame. |
| `createAppPreferences()` | Returns the preferences that `initPreferences()` opened. |

A read is synchronous, from memory, and never throws. It returns `null` when its key has no value of the type it asks for, so `getString` of a key with a `bool` is `null`. Whether a number saved as an `int` is read as a `double`, or the other way round, depends on the module. With `shared_preferences` it is not, so read a setting as the type you saved it as.

Once the future of a write completes, reads return what it saved, in this run of the app and after its next launch. A key has one value: a write replaces what the key had, a value of another type too. `remove` puts a setting back to its default, and the reads of its key return `null` again.

If the preferences cannot be opened, `initPreferences()` fails, and `bootstrap()` with it.

## Remember a setting

Code that remembers a setting has three parts: the state that the widgets listen to, a function that changes the state and saves it, and a restorer, which reads what is saved when the app starts. This one remembers that the user has dismissed a hint of the home screen:

```dart title="lib/features/home/hint.dart"
import 'package:flutter/foundation.dart';

import '../../core/preferences/app_preferences.dart';

/// The key of the setting in the preferences of the app.
const _key = 'home.hint_dismissed';

/// Whether the user dismissed the hint of the home screen.
final ValueNotifier<bool> hintDismissed = ValueNotifier(false);

AppPreferences? _preferences;

/// Dismisses the hint, or shows it again, and saves the choice.
Future<void> chooseHint({required bool dismissed}) async {
  hintDismissed.value = dismissed;
  await _preferences?.setBool(_key, dismissed);
}

/// Takes the choice that is saved, or keeps the current one, and keeps
/// [preferences] for the choice to come.
void restoreHint(AppPreferences preferences) {
  _preferences = preferences;
  hintDismissed.value = preferences.getBool(_key) ?? hintDismissed.value;
}
```

A restorer is a function that takes the `AppPreferences`. Add it to the list of restorers in the file of the role, with the import of its file:

```dart title="lib/core/preferences/app_preferences.dart"
final List<void Function(AppPreferences preferences)> _restorers = [
  restoreHint,
];
```

`initPreferences()` calls each restorer with the preferences once they are open, so the setting has its saved value before the first frame. The widgets listen to `hintDismissed` and call `chooseHint()`, and never touch the preferences themselves. The roles and the modules of the app keep their settings the same way: `smf create` puts their restorers into the same list, such as `restoreAppThemeMode` of the theme and `restoreOnboarding` of the onboarding.

A restorer is synchronous, keeps the current value when nothing is saved under its key, as `?? hintDismissed.value` does above, and may run more than once. [How settings work](https://doc.saymyframe.com/concepts/settings.md#preferences) has its rules in full.

In the code of the app, only `bootstrap()` calls `initPreferences()`, and nothing but the DI container calls `createAppPreferences()`. Code gets the preferences as the argument of its restorer, and the guide for coding agents of the app tells agents to do the same. A test is another matter: it calls `createAppPreferences()` to read and write a key, and `initPreferences()` to open the preferences again, as [the test below](#in-tests) does.

## Keys

Name a key `<owner>.<setting>`, such as `home.hint_dismissed`, where the owner is the feature or the concern whose code keeps the setting. The modules name theirs after their ids, so the keys of different owners do not collide. Nothing checks the form: two owners that save under one key overwrite each other's setting.

## With a DI container

With a module of dependency injection, such as [`get_it`](https://doc.saymyframe.com/modules/get-it.md), the preferences role also registers the preferences in the container as a lazy singleton. A service takes them as a dependency of its factory, and the composition file of a feature takes them with `resolve<AppPreferences>()` and hands them to the state of the feature, such as a Cubit. See [Services and state](https://doc.saymyframe.com/guides/services.md#with-a-di-container).

## The settings screen

With `settings`, the app has `SettingsScreen` at `/settings`. Below its title, it shows the settings that the roles and the modules of the app have, such as the theme mode and the language, in one group on a card. With a layout, such as [`bottom_tabs`](https://doc.saymyframe.com/modules/bottom-tabs.md), the screen is a destination of the main navigation. Without one, open it from your own code:

```dart
context.nav.settings.settings().push<void>()
```

An entry for a setting of your own is a widget that reads and changes the setting through its state, as the other entries do:

```dart title="lib/features/home/hint_setting.dart"
import 'package:flutter/material.dart';

import 'hint.dart';

/// The row of the settings screen that hides the hint of the home screen,
/// or shows it again.
class HintSetting extends StatelessWidget {
  /// Creates the row.
  const HintSetting({super.key});

  @override
  Widget build(BuildContext context) => ValueListenableBuilder<bool>(
    valueListenable: hintDismissed,
    builder: (context, dismissed, _) => SwitchListTile(
      secondary: const Icon(Icons.lightbulb_outline),
      title: const Text('Hide the hint of the home screen'),
      value: dismissed,
      onChanged: (value) => chooseHint(dismissed: value),
    ),
  );
}
```

The screen is in `lib/features/settings/settings_screen.dart`. Import the file of the entry there with a prefix that no other import of the screen has, as the screen imports the entries of the modules, since two entries may have the same class name. The screen creates its entries as constants, so the entry has a `const` constructor.

### In an app without settings

While no module of the app has a setting, the screen shows a note for you in place of the group; see [`settings`](https://doc.saymyframe.com/modules/settings.md#an-app-without-settings). The first entry takes the place of the note. Replace the `SliverFillRemaining` with the note by the entry on a `Card`:

```dart title="lib/features/settings/settings_screen.dart"
import '../home/hint_setting.dart' as hint;

// ...
          child: CustomScrollView(
            slivers: [
              SliverPadding(
                padding: const EdgeInsets.fromLTRB(16, 20, 16, 0),
                sliver: SliverToBoxAdapter(child: title),
              ),
              const SliverPadding(
                padding: EdgeInsets.fromLTRB(16, 20, 16, 32),
                sliver: SliverToBoxAdapter(
                  child: Card(
                    clipBehavior: Clip.antiAlias,
                    child: hint.HintSetting(),
                  ),
                ),
              ),
            ],
          ),
```

Then delete the class `_NoSettings` and the constant `_file` from the file, which nothing uses after that.

### In an app with settings

In an app with a module that brings a setting, such as [`material_theme`](https://doc.saymyframe.com/modules/material-theme.md), the screen has the group. Add the entry to its children, here after the entry of the theme mode:

```dart title="lib/features/settings/settings_screen.dart"
import '../home/hint_setting.dart' as hint;

// ...
              const _Group(
                children: [entry0.ThemeModeSetting(), hint.HintSetting()],
              ),
```

The group draws a line between its entries.

## In tests

A test shows that a setting is saved by reading its key after a choice. It shows that a setting is remembered by writing the key through `AppPreferences`, running `initPreferences()` again, as the next launch does, and reading the state:

```dart title="test/features/home/hint_test.dart"
import 'package:flutter_test/flutter_test.dart';
import 'package:my_app/bootstrap.dart';
import 'package:my_app/core/preferences/app_preferences.dart';
import 'package:my_app/features/home/hint.dart';
import 'package:shared_preferences_platform_interface/in_memory_shared_preferences_async.dart';
import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';

void main() {
  test('the choice is saved, and the next start reads it', () async {
    SharedPreferencesAsyncPlatform.instance =
        InMemorySharedPreferencesAsync.empty();
    await bootstrap();
    expect(hintDismissed.value, isFalse);

    // Saved: the key has the choice once the write completes.
    await chooseHint(dismissed: true);
    expect(createAppPreferences().getBool('home.hint_dismissed'), isTrue);

    // Remembered: write the key, open the preferences again as the next
    // launch does, and read the state.
    await createAppPreferences().setBool('home.hint_dismissed', false);
    await initPreferences();
    expect(hintDismissed.value, isFalse);
  });
}
```

Running `initPreferences()` again right after a choice proves nothing, since memory has the value already. Nor does it stand for the next launch once a key was removed: the restorer finds nothing saved and keeps the value that the state has, where a new launch starts with the default.

The first statement of the test puts the preferences of `shared_preferences` into memory. Without it, opening the preferences throws. Its two names come from the package `shared_preferences_platform_interface`, which the test needs as a dev dependency; see [`shared_preferences`](https://doc.saymyframe.com/modules/shared-preferences.md#in-tests).

A DI container that created the preferences before keeps the object of the earlier open. So a test of code that takes them from the container also runs `resetDependencies()` and `registerDependencies()` once `initPreferences()` ran again.
