library;

import 'dart:async';

import 'dart:collection';

import 'dart:convert';

import 'dart:developer' as developer;

import 'dart:ui' as ui;

import 'package:flutter/foundation.dart';

import 'package:flutter/rendering.dart';

import 'package:flutter/scheduler.dart';

import 'package:flutter/services.dart';

import 'basic.dart';

import 'binding.dart';

import 'focus_manager.dart';

import 'focus_scope.dart';

import 'focus_traversal.dart';

import 'framework.dart';

import 'heroes.dart';

import 'notification_listener.dart';

import 'overlay.dart';

import 'restoration.dart';

import 'restoration_properties.dart';

import 'routes.dart';

import 'ticker_provider.dart';

const Duration _kAndroidRefocusingDelayDuration = Duration(milliseconds: 300);

typedef RouteFactory = Route<dynamic>? Function(RouteSettings settings);

typedef RouteListFactory =

List<Route<dynamic>> Function(NavigatorState navigator, String initialRoute);

typedef RestorableRouteBuilder<T> = Route<T> Function(BuildContext context, Object? arguments);

typedef RoutePredicate = bool Function(Route<dynamic> route);

@Deprecated(

'Use PopInvokedCallback instead. '

'This feature was deprecated after v3.12.0-1.0.pre.',

)

typedef WillPopCallback = Future<bool> Function();

typedef PopPageCallback = bool Function(Route<dynamic> route, dynamic result);

typedef DidRemovePageCallback = void Function(Page<Object?> page);

enum RoutePopDisposition {

/// Pop the route.

pop,

/// Do not pop the route.

doNotPop,

/// Delegate this to the next level of navigation.

bubble,

}

abstract class Route<T> extends _RoutePlaceholder {

/// Initialize the [Route].

Route({RouteSettings? settings, bool? requestFocus})

: _settings = settings ?? const RouteSettings(),

_requestFocus = requestFocus {

assert(debugMaybeDispatchCreated('widgets', 'Route<T>', this));

}

/// When the route state is updated, request focus if the current route is at the top.

bool get requestFocus => _requestFocus ?? navigator?.widget.requestFocus ?? false;

final bool? _requestFocus;

/// The navigator that the route is in, if any.

NavigatorState? get navigator => _navigator;

NavigatorState? _navigator;

bool get _installed => _navigator != null;

bool _isInstalledIn(NavigatorState state) => _navigator == state;

/// The settings for this route.

RouteSettings get settings => _settings;

RouteSettings _settings;

bool get _isPageBased => settings is Page<Object?>;

/// The restoration scope ID to be used for the [RestorationScope] surrounding

ValueListenable<String?> get restorationScopeId => _restorationScopeId;

final ValueNotifier<String?> _restorationScopeId = ValueNotifier<String?>(null);

void _updateSettings(RouteSettings newSettings) {

if (_settings != newSettings) {

_settings = newSettings;

if (_installed) {

changedInternalState();

}

}

}

// ignore: use_setters_to_change_properties, (setters can't be private)

void _updateRestorationId(String? restorationId) {

_restorationScopeId.value = restorationId;

}

/// The overlay entries of this route.

List<OverlayEntry> get overlayEntries => const <OverlayEntry>[];

/// Called when the route is inserted into the navigator.

@protected

@mustCallSuper

void install() {}

/// Called after [install] when the route is pushed onto the navigator.

@protected

@mustCallSuper

TickerFuture didPush() {

return TickerFuture.complete()..then<void>((void _) {

if (requestFocus) {

navigator!.focusNode.enclosingScope?.requestFocus();

}

});

}

/// Called after [install] when the route is added to the navigator.

@protected

@mustCallSuper

void didAdd() {

if (requestFocus) {

// This TickerFuture serves two purposes. First, we want to make sure that

// animations triggered by other operations will finish before focusing

// the navigator. Second, navigator.focusNode might acquire more focused

// children in Route.install asynchronously. This TickerFuture will wait

// for it to finish first.

//

// The later case can be found when subclasses manage their own focus scopes.

// For example, ModalRoute creates a focus scope in its overlay entries. The

// focused child can only be attached to navigator after initState which

// will be guarded by the asynchronous gap.

TickerFuture.complete().then<void>((void _) {

// The route can be disposed before the ticker future completes. This can

// happen when the navigator is under a TabView that warps from one tab to

// another, non-adjacent tab, with an animation. The TabView reorders its

// children before and after the warping completes, and that causes its

// children to be built and disposed within the same frame. If one of its

// children contains a navigator, the routes in that navigator are also

// added and disposed within that frame.

//

// Since the reference to the navigator will be set to null after it is

// disposed, we have to do a null-safe operation in case that happens

// within the same frame when it is added.

navigator?.focusNode.enclosingScope?.requestFocus();

});

}

}

/// Called after [install] when the route replaced another in the navigator.

@protected

@mustCallSuper

void didReplace(Route<dynamic>? oldRoute) {}

/// Returns whether calling [Navigator.maybePop] when this [Route] is current

@Deprecated(

'Use popDisposition instead. '

'This feature was deprecated after v3.12.0-1.0.pre.',

)

Future<RoutePopDisposition> willPop() async {

return isFirst ? RoutePopDisposition.bubble : RoutePopDisposition.pop;

}

/// Returns whether calling [Navigator.maybePop] when this [Route] is current

RoutePopDisposition get popDisposition {

if (_isPageBased) {

final page = settings as Page<Object?>;

if (!page.canPop) {

return RoutePopDisposition.doNotPop;

}

}

return isFirst ? RoutePopDisposition.bubble : RoutePopDisposition.pop;

}

/// Called after a route pop was handled.

@Deprecated(

'Override onPopInvokedWithResult instead. '

'This feature was deprecated after v3.22.0-12.0.pre.',

)

void onPopInvoked(bool didPop) {}

/// {@template flutter.widgets.navigator.onPopInvokedWithResult}

@mustCallSuper

void onPopInvokedWithResult(bool didPop, T? result) {

if (_isPageBased) {

final page = settings as Page<T>;

page.onPopInvoked(didPop, result);

}

}

/// Whether calling [didPop] would return false.

bool get willHandlePopInternally => false;

/// When this route is popped (see [Navigator.pop]) if the result isn't

T? get currentResult => null;

/// A future that completes when this route is popped off the navigator.

Future<T?> get popped => _popCompleter.future;

final Completer<T?> _popCompleter = Completer<T?>();

final Completer<T?> _disposeCompleter = Completer<T?>();

/// A request was made to pop this route. If the route can handle it

@mustCallSuper

bool didPop(T? result) {

didComplete(result);

return true;

}

/// The route was popped or is otherwise being removed somewhat gracefully.

@protected

@mustCallSuper

void didComplete(T? result) {

_popCompleter.complete(result ?? currentResult);

}

/// The given route, which was above this one, has been popped off the

@protected

@mustCallSuper

void didPopNext(Route<dynamic> nextRoute) {}

/// This route's next route has changed to the given new route.

@protected

@mustCallSuper

void didChangeNext(Route<dynamic>? nextRoute) {}

/// This route's previous route has changed to the given new route.

@protected

@mustCallSuper

void didChangePrevious(Route<dynamic>? previousRoute) {}

/// Called whenever the internal state of the route has changed.

@protected

@mustCallSuper

void changedInternalState() {}

/// Called whenever the [Navigator] has updated in some manner that might

@protected

@mustCallSuper

void changedExternalState() {}

/// Discards any resources used by the object.

@mustCallSuper

@protected

void dispose() {

_navigator = null;

_restorationScopeId.dispose();

_disposeCompleter.complete();

assert(debugMaybeDispatchDisposed(this));

}

/// Whether this route is the top-most route on the navigator.

bool get isCurrent {

if (!_installed) {

return false;

}

final _RouteEntry? currentRouteEntry = _navigator!._lastRouteEntryWhereOrNull(

_RouteEntry.isPresentPredicate,

);

if (currentRouteEntry == null) {

return false;

}

return currentRouteEntry.route == this;

}

/// Whether this route is the bottom-most active route on the navigator.

bool get isFirst {

if (!_installed) {

return false;

}

final _RouteEntry? currentRouteEntry = _navigator!._firstRouteEntryWhereOrNull(

_RouteEntry.isPresentPredicate,

);

if (currentRouteEntry == null) {

return false;

}

return currentRouteEntry.route == this;

}

/// Whether there is at least one active route underneath this route.

@protected

bool get hasActiveRouteBelow {

if (!_installed) {

return false;

}

for (final _RouteEntry entry in _navigator!._history) {

if (entry.route == this) {

return false;

}

if (_RouteEntry.isPresentPredicate(entry)) {

return true;

}

}

return false;

}

/// Whether this route is on the navigator.

bool get isActive {

return _navigator?._firstRouteEntryWhereOrNull(_RouteEntry.isRoutePredicate(this))?.isPresent ??

false;

}

}

class RouteSettings {

/// Creates data used to construct routes.

const RouteSettings({this.name, this.arguments});

/// The name of the route (e.g., "/settings").

final String? name;

/// The arguments passed to this route.

final Object? arguments;

@override

String toString() =>

'${objectRuntimeType(this, 'RouteSettings')}(${name == null ? 'none' : '"$name"'}, $arguments)';

}

abstract class Page<T> extends RouteSettings {

/// Creates a page and initializes [key] for subclasses.

const Page({

this.key,

super.name,

super.arguments,

this.restorationId,

this.canPop = true,

this.onPopInvoked = _defaultPopInvokedHandler,

});

static void _defaultPopInvokedHandler(bool didPop, Object? result) {}

/// The key associated with this page.

final LocalKey? key;

/// Restoration ID to save and restore the state of the [Route] configured by

final String? restorationId;

/// Called after a pop on the associated route was handled.

final PopInvokedWithResultCallback<T> onPopInvoked;

/// When false, blocks the associated route from being popped.

final bool canPop;

/// Whether this page can be updated with the [other] page.

bool canUpdate(Page<dynamic> other) {

return other.runtimeType == runtimeType && other.key == key;

}

/// Creates the [Route] that corresponds to this page.

@factory

Route<T> createRoute(BuildContext context);

@override

String toString() => '${objectRuntimeType(this, 'Page')}("$name", $key, $arguments)';

}

class NavigatorObserver {

/// The navigator that the observer is observing, if any.

NavigatorState? get navigator => _navigators[this];

// Expando mapping instances of NavigatorObserver to their associated

// NavigatorState (or `null`, if there is no associated NavigatorState). The

// reason we don't use a private instance field of type

// `NavigatorState?` is because as part of implementing

// https://github.com/dart-lang/language/issues/2020, it will soon become a

// runtime error to invoke a private member that is mocked in another

// library. By using an expando rather than an instance field, we ensure

// that a mocked NavigatorObserver can still properly keep track of its

// associated NavigatorState.

static final Expando<NavigatorState> _navigators = Expando<NavigatorState>();

/// The [Navigator] pushed `route`.

void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {}

/// The [Navigator] popped `route`.

void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) {}

/// The [Navigator] removed `route`.

void didRemove(Route<dynamic> route, Route<dynamic>? previousRoute) {}

/// The [Navigator] replaced `oldRoute` with `newRoute`.

void didReplace({Route<dynamic>? newRoute, Route<dynamic>? oldRoute}) {}

/// The top most route has changed.

void didChangeTop(Route<dynamic> topRoute, Route<dynamic>? previousTopRoute) {}

/// The [Navigator]'s routes are being moved by a user gesture.

void didStartUserGesture(Route<dynamic> route, Route<dynamic>? previousRoute) {}

/// User gesture is no longer controlling the [Navigator].

void didStopUserGesture() {}

}

class HeroControllerScope extends InheritedWidget {

/// Creates a widget to host the input [controller].

const HeroControllerScope({

super.key,

required HeroController this.controller,

required super.child,

});

/// Creates a widget to prevent the subtree from receiving the hero controller

const HeroControllerScope.none({super.key, required super.child}) : controller = null;

/// The hero controller that is hosted inside this widget.

final HeroController? controller;

/// Retrieves the [HeroController] from the closest [HeroControllerScope]

static HeroController? maybeOf(BuildContext context) {

final HeroControllerScope? host = context

.dependOnInheritedWidgetOfExactType<HeroControllerScope>();

return host?.controller;

}

/// Retrieves the [HeroController] from the closest [HeroControllerScope]

static HeroController of(BuildContext context) {

final HeroController? controller = maybeOf(context);

assert(() {

if (controller == null) {

throw FlutterError(

'HeroControllerScope.of() was called with a context that does not contain a '

'HeroControllerScope widget.\n'

'No HeroControllerScope widget ancestor could be found starting from the '

'context that was passed to HeroControllerScope.of(). This can happen '

'because you are using a widget that looks for a HeroControllerScope '

'ancestor, but no such ancestor exists.\n'

'The context used was:\n'

' $context',

);

}

return true;

}());

return controller!;

}

@override

bool updateShouldNotify(HeroControllerScope oldWidget) {

return oldWidget.controller != controller;

}

}

abstract class RouteTransitionRecord {

/// Retrieves the wrapped [Route].

Route<dynamic> get route;

/// Whether this route is waiting for the decision on how to enter the screen.

bool get isWaitingForEnteringDecision;

/// Whether this route is waiting for the decision on how to exit the screen.

bool get isWaitingForExitingDecision;

/// Marks the [route] to be pushed with transition.

void markForPush();

/// Marks the [route] to be added without transition.

void markForAdd();

/// Marks the [route] to be popped with transition.

void markForPop([dynamic result]);

/// Marks the [route] to be completed without transition.

void markForComplete([dynamic result]);

/// Marks the [route] to be removed without transition.

@Deprecated(

'Call markForComplete instead. '

'This will let route associated future to complete when route is removed. '

'This feature was deprecated after v3.27.0-1.0.pre.',

)

void markForRemove() => markForComplete();

}