suspend<T> method

Future<T> suspend<T>(
  1. Future<T> run()
)

Hands the terminal to another program while run runs, one that reads it itself (sudo asking for a password, a package manager, a pager, an editor, started with ProcessStartMode.inheritStdio), and takes it back after.

With the inline session open (or opening), its region stays on the screen with the cursor on the line below it, where the other program writes; raw mode is off and the session's input paused, so the other program reads what is typed; a progress stops being drawn until run completes, and the session is drawn again below what was printed. Without one, run just runs. Returns what run returns, or throws what it throws, once the terminal is back.

This is also how a twk app of its own runs in the middle of a program that has used the console: a process has one terminal, so runApp(...) while the session has it throws a TerminalException (the session is open as long as it has been used and not closed). Run it inside run, or close the console first when nothing needs it after:

await cli.suspend(() => runApp(const Text('hi')));
final progress = cli.progress('Installing');
final code = await cli.suspend(() async {
  final sudo = await Process.start(
    'sudo',
    ['true'],
    mode: ProcessStartMode.inheritStdio,
  );
  return sudo.exitCode;
});
progress.complete(code == 0 ? 'Installed' : null);

Implementation

Future<T> suspend<T>(Future<T> Function() run) async {
  var session = _liveSession;
  if (session == null) {
    final opening = _openingSession;
    if (opening != null) {
      try {
        session = await opening;
      } on Object {
        session = null;
      }
    }
  }
  return session != null && session.isOpen ? session.suspend(run) : run();
}