Screen tracking

m.global.everframe.callFunc("setScreen", "Details")

Every report sent after that carries the screen as context.route, and each change leaves a navigation breadcrumb screen: <name> with data: { from, to } (from is left out for the first screen).

setScreen returns true when the screen changed. The name is trimmed and cut to 128 characters; numbers and booleans become strings. Blank, invalid or non-scalar names, and a repeat of the current screen, are ignored. getScreen(invalid) returns the current screen, or invalid before the first call.

Calling it from a component

m.global.everframe is set by start(); before that it is invalid:

' components/DetailsScreen.brs
sub init()
    ef = m.global.everframe
    if ef <> invalid then ef.callFunc("setScreen", "Details")
end sub

Automatic screens

With build-step instrumentation you usually do not need to call it. The init() of every component whose name — or any ancestor’s name through extends — matches --screens sets the screen to the component’s concrete type. The default patterns are *Screen, *View and *Page, matched case-insensitively against the whole name.

So creating a DetailsScreen makes DetailsScreen the current screen. If your screens share a base component, matching the base covers all of them.

This tracks when a screen component is created, not when it is shown or hidden. If your channel creates screens ahead of time, keeps them in a stack, or returns to a screen without creating it again, call setScreen yourself where the screen becomes visible. A manual call always overrides the automatic one. --screens none turns automatic screens off.

Across a crash

The current screen is written to the registry on every change. A crash that only the next launch can detect carries the screen from the session that exited; a crash caught in-process carries the screen current at the time.