InlayNavigator class

Framework-level navigator for cross-boundary navigation in inlay.

Overview

InlayNavigator handles navigation across the Flutter/native boundary. It coordinates with the native side to start new Activities (Android) or ViewControllers (iOS).

Important: This is NOT in-Flutter Navigation

For navigation within Flutter, use Flutter's built-in Navigator:

// Within Flutter - use standard Flutter navigation
Navigator.of(context).push(MaterialPageRoute(
  builder: (_) => MyOtherScreen(),
));

Use InlayNavigator only when:

  • Navigating from Flutter to native screens
  • Navigating from native to Flutter screens
  • (Rare) Navigating from Flutter to Flutter in a new engine (see below)

Flutter → Flutter via InlayNavigator (New Engine)

When you call InlayNavigator.instance.push(SomeFlutterRoute(...)) from Flutter code, this creates a new native Activity/ViewController with a fresh Flutter engine. This is fundamentally different from in-Flutter navigation:

Aspect In-Flutter Navigation InlayNavigator Flutter→Flutter
Engine Same engine New engine instance
Memory Shared widget tree Separate memory space
State Shared app state Isolated state
Startup Instant Engine initialization delay
Use case Normal navigation Cross-module isolation

When to use Flutter→Flutter via InlayNavigator:

  • When you need complete isolation between Flutter modules
  • When different parts of the app have incompatible dependencies
  • When navigating from native code that doesn't have access to the current Flutter engine's navigator

Prefer in-Flutter navigation when:

  • Navigating between screens within the same Flutter module
  • You need shared state or want instant transitions
  • Memory efficiency is important

Usage Examples

Native → Flutter (common)

From Android:

InlayNavigator.push(context, PageSettings("soundsNotifications", mapOf("contactId" to "42")))

From iOS:

InlayNavigator.shared.push(PageSettings(routeId: "soundsNotifications", params: ["contactId": "42"]))

Flutter → Native (common)

InlayNavigator.instance.push(
  NativeEditProfilePage(contactId: '42').toNativeRoute(),
);

Flutter → Flutter via new engine (rare)

// Creates a NEW Activity/ViewController with a NEW Flutter engine!
// Only use when you specifically need engine isolation.
InlayNavigator.instance.push(SoundsNotificationsPage(contactId: '42'));
Implementers

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

maybePop(BuildContext context) → Future<void>
Pops the topmost Flutter route if the navigator can pop, otherwise closes the native container (Activity/ViewController).
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pop([Object? result]) → Future<void>
Pop (finish) the current Flutter Activity/ViewController.
presentFlutterDialog(PageSettings page) → Future<void>
Present a Flutter dialog in a transparent native container.
presentFlutterDialogForResult(PageSettings page) → Future<Object?>
Like presentFlutterDialog, but completes with the result the dialog pops with (null when dismissed without one).
push(InlayRoute route) → Future<void>
Pushes a route, creating a new native Activity/ViewController.
pushFlutterRoute(PageSettings page) → Future<void>
Starts a new Activity/ViewController with a new Flutter engine.
pushFlutterRouteForResult(PageSettings page) → Future<Object?>
Like pushFlutterRoute, but completes with the result the pushed screen pops with (null when dismissed without one).
pushNativeRoute(PageSettings page) → Future<void>
Internal method: open a native Activity/ViewController route.
pushNativeRouteForResult(PageSettings page) → Future<Object?>
Like pushNativeRoute, but completes with the result the native screen passes to its handler completion (null when it finishes without one).
setNativePopGestureEnabled(bool enabled) → Future<void>
Enable/disable native iOS swipe-back gesture for this container.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

initialPath → String
URL path from the platform's defaultRouteName (e.g. /sounds-notifications/42).
no setter
instance ↔ InlayNavigator
Replaces the singleton with a test double, e.g. FakeInlayNavigator from package:inlay/testing.dart.
getter/setter pair

Static Methods

decodeInitialRoute(String initialRoute) → PageSettings
Decode the initialRoute string (set by the platform) back into PageSettings. Format: routeId?key=val&key=val
fetchInitialRoute<T extends InlayRoute>(T? decoder(PageSettings?)) → Future<T?>
Fetch the initial route data from the native host and decode it.
initialPageFromPlatform() → PageSettings
Reads platform defaultRouteName and decodes it into PageSettings.