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

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

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.