# 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 Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `back()`
  Pop the top entry off the navigation stack and return to the previous one.
  `static void`
  `clearStack()`
  Forgets the navigation history, leaving nothing to go back to.
  `static boolean`
  `dispatchExternalUrl(String url)`
  Dispatch a URL delivered by the platform.
  `static NavigationEntry`
  `getCurrent()`
  The current entry (top of stack), or null when the stack is empty.
  `static List<NavigationEntry>`
  `getStack()`
  Unmodifiable snapshot of the navigation stack, oldest entry first (breadcrumb order).
  `static boolean`
  `navigate(String path)`
  Navigate to a path.
  `static boolean`
  `popTo(NavigationEntry entry)`
  Pop entries until `entry` is on top, then show its form via `Form#showBack`.
  `static boolean`
  `restoreStack(List<String> paths)`
  Rebuilds the stack from a list of paths, showing only the last one.
  `static void`
  `setDispatcher(RouteDispatcher d)`
  Installs the build-time-generated route dispatcher.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## 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.

  - ### navigate

    public static boolean navigate(String path)

    Navigate to a path. Looks the URL up in the route table generated from `@Route` annotations, builds the matching `Form`, pushes it onto the navigation stack, and shows it.

    Accepts either a bare path (`/users/42`), a full URL with scheme + host (`https://example.com/users/42`), or a custom-scheme URL. Scheme and host are ignored -- only the path + query are matched.

    Returns `true` when a route matched and the form was shown, `false` when no route matched.

  - ### 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.