Class Navigation

java.lang.Object
com.codename1.router.Navigation
public final class Navigation extends Object

In-app navigation API on top of the declarative @Route table.

Navigation is the imperative counterpart to the Route annotation: declare your forms with @Route("/users/:id") once, then trigger navigation from anywhere with Navigation.navigate("/users/42"). The same route table that handles deep links is reused, so there is exactly one place that knows how /users/:id maps to a form.

The class also exposes the navigation stack so applications can render breadcrumb UIs without maintaining a parallel history:

Container breadcrumbs = new Container(BoxLayout.x());
for (final NavigationEntry e : Navigation.getStack()) {
    Button crumb = new Button(e.getTitle());
    crumb.addActionListener(evt -> Navigation.popTo(e));
    breadcrumbs.add(crumb);
}

The surface is intentionally tiny -- five static methods and one value type. Applications that prefer raw Form#show / Form#showBack keep working unchanged; the Navigation stack only records URL-driven navigations.

All methods must be called on the EDT.

  • Method Details

    • setDispatcher

      public static void setDispatcher(RouteDispatcher d)
      Installs the build-time-generated route dispatcher. Invoked once by com.codename1.router.generated.Routes#bootstrap during framework initialization. Application code should not call this.

    • back

      public static boolean back()
      Pop the top entry off the navigation stack and return to the previous one. Uses Form#showBack so the transition runs in reverse. Returns true when a frame was popped, false when the stack had at most one entry (already at the root, nothing to go back to).

    • getCurrent

      public static NavigationEntry getCurrent()
      The current entry (top of stack), or null when the stack is empty.

    • getStack

      public static List<NavigationEntry> getStack()
      Unmodifiable snapshot of the navigation stack, oldest entry first (breadcrumb order). The list is a copy: mutating navigations after the call do not affect it.

    • clearStack

      public static void clearStack()

      Forgets the navigation history, leaving nothing to go back to.

      For a logout, which is the case that needs it: Continuity.clear() calls this, because a route stack is the previous account's work as surely as a stored checkpoint is. Left in place it kept two promises broken -- Navigation#back() reopened the signed-out account's forms, and the next navigation checkpointed and republished a stack that still began with their routes.

      The forms themselves are not touched: whatever is on screen stays there, and the caller navigates wherever it means to go next.

      Continuity IS notified, because for every caller except a logout this is a real change to where the user has been. It used to stay silent so that Continuity.clear() could call it without checkpointing the emptied stack back over what it was deleting -- but that made every other caller silent too: an application forgetting its back history and then not navigating left the previous routes in the stored checkpoint, so a process death restored exactly what it had just cleared. The logout path suppresses this at its own end, where the reason to suppress it lives.

    • popTo

      public static boolean popTo(NavigationEntry entry)
      Pop entries until entry is on top, then show its form via Form#showBack. Returns true when the entry was on the stack and we navigated back to it, false when the entry is not on the stack. Calling with the current entry is a no-op that returns true.

    • restoreStack

      public static boolean restoreStack(List<String> paths)

      Rebuilds the stack from a list of paths, showing only the last one.

      This is how com.codename1.continuity.Continuity puts the user back where they were: the saved state is a list of paths, and every one of them has to become a stack frame or back() would land on a screen that was never built. Replaying them with navigate would work and would also flash every intermediate screen past the user with a transition each, so the frames are built silently and only the top one is shown.

      Paths that no longer match a route are skipped rather than failing the restore. A rebuilt app legitimately drops routes, and refusing to restore anything because one deep frame went away would lose the whole session over a screen the user was not on.

      Replaces whatever was on the stack. Must be called on the EDT.

      Parameters
      • paths: the paths, oldest first
      Returns

      true when at least one frame was rebuilt and shown A route factory that THROWS propagates, rather than being skipped: it is a failure the caller can retry, not a route this build has stopped registering. A factory that answers null is still skipped.

    • dispatchExternalUrl

      public static boolean dispatchExternalUrl(String url)
      Dispatch a URL delivered by the platform. Invoked by com.codename1.ui.Display#setProperty(String, String) for URL-shaped AppArg values; applications should call #navigate(String) instead.