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

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

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