public final class Navigation

  1. Object
  2. Navigation

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.

Methods

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

Inherited methods

From Object

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

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 List<String>
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.