Navigation

kadokit supports multi-screen apps with a navigation stack, transitions, and lazy screen building. Widgets for a screen are only created when it is first visited, keeping startup fast.

Defining screens

screen "home" {
    transition "fade" duration=200
    bg-color "#1A1A2E"
    vbox {
        fill #true; padding 16
        label "Home Screen"
        button {
            label "Settings"
            on-click { nav "settings" }
        }
    }
}

screen "settings" {
    transition "slide-left" duration=300
    // ...
}

The first screen defined in the file is displayed on load.

Transitions

Type	Effect
`none`	Instant switch
`fade`	Crossfade
`slide-left` / `slide-right`	New screen slides in horizontally
`slide-up` / `slide-down`	New screen slides in vertically

Going back automatically reverses the transition (slide-left forward becomes slide-right back). A nav action can override the target’s default:

on-click { nav "settings" transition="fade" duration=100 }

Screen parameters

Screens can declare typed parameters, making them self-contained and reusable. The same detail screen serves every room:

screen "room_detail" {
    param "id" type="string"
    param "mode" type="string" default="view"

    label { text bind="'Room: ' + prop.id" }
    label { text bind="'Mode: ' + prop.mode" }
}

Parameters without a default are required. Pass them as block children of nav, as literals or expressions:

on-click {
    nav "room_detail" {
        id "bedroom"
        mode "edit"
    }
}

// Inside a for-loop. bind evaluates at navigation time
on-click {
    nav "room_detail" {
        id bind="item.id"
    }
}

Navigating to the same screen with different parameters clears and rebuilds it; with the same parameters, the built screen is reused. Back navigation restores the previous parameters (rebuilding if they differ).

Lifecycle hooks

screen "dashboard" {
    on-enter  { set "visits" expr="app.visits + 1" }
    on-exit   { cmd "pause_polling" }
    on-resume { cmd "refresh_data" }

    label "Dashboard"
}

Hook	Fires when
`on-enter`	Every time the screen becomes active: first visit, forward nav, and back
`on-exit`	When navigating away, before the new screen loads
`on-resume`	Only when returning to an already-built screen reused without rebuild

Hook bodies support the same actions as event blocks.

History stack

nav pushes the current screen onto a history stack; nav-back pops it:

nav "settings"  →  history: [home]
nav "about"     →  history: [home, settings]
nav-back        →  history: [home]         (shows settings)
nav-back        →  history: []             (shows home)

For tab-style navigation that replaces the current screen without pushing history, firmware code can call the replace-navigation API.

Navigation is also available from script expressions:

on-click { eval "nav('settings')" }
on-click { eval "nav.back()" }

Layout & Styling Animations