The MVU Model
Every Kura UI follows the Model-View-Update (MVU) architecture, the same shape as Elm.
| Function | Signature (shape) | Purpose |
|---|---|---|
init |
fn init(): Model |
Produce the starting state |
update |
fn update(msg: Message, model: Model): Model |
Produce the next state from a Message |
view |
fn view(model: Model): Node |
Describe the UI for a given state |
Model and Message are plain data
Section titled “Model and Message are plain data”Model and Message are PODs: records, or
variants of records. They can’t hold
functions. Their shapes are fixed by the types in your function definitions.
type Position = { x: Int, y: Int }type Message = Click(Position) | Ticktype Model = { clicks: Int }Which functions are required?
Section titled “Which functions are required?”- Only
viewis required. A static UI needs no state and no reactivity. initandupdateare not allowed without aview.initmay exist withoutupdate.- If there’s no
init, the host can build the state itself (for example, an inventory constructed in C++) and pass it toview.
view is pure
Section titled “view is pure”view can only reach pure functions. It can’t call impure C functions, and it can’t
change state. init and update may call C, as long as they end by producing the model.
See Effects.
view must return a Node in the source. After compilation, though, view returns
nothing: the render instructions are emitted in place. The UI tree is a compile-time
concept and doesn’t exist at run time.
Messages go both ways
Section titled “Messages go both ways”Messages travel in both directions, and both go through the same path:
- host => UI. Your application builds a Message and sends it. That is how ticks and
anything else the host knows about reach
update. - UI => host. An element can say what a click on it means:
#button(on-click: Increment). When the host reports a click, the runtime finds the element it landed on and sends that Message, as if the host had sent it.
A Message, from either side, is given to update first. After update has made the next
state, the Message goes to the host’s own message listeners, in the order they were added.
A listener is secondary to update: it hears the Message after the state has changed, and sees
both the state before and the state after. That is how a host reacts to what the UI did (a
button that means “Quit”, say) without the UI knowing about the host.
type Message = Increment | Decrement | Reset | Set(Int)
type State = { value: Int,}
fn init(): State => { value: 1 }
fn update(msg: Message, state: State): State => match msg { Increment => { value: state.value + 1 } Decrement => { value: state.value - 1 } Reset => { value: 0 } Set(n) => { value: n } _ => state }In C++, the host uses a Session:
auto program = kura::Program::Load("counter.kui", {}, &error);auto session = kura::Session::Create(program.get(), &error); // runs `init`
// A listener hears every Message, from either side, after `update`.session->AddListener([](const kura::Session::Event& event) { std::println("{} => {}", kura::rt::Format(event.message), kura::rt::Format(event.state));});
// host => UIsession->Send(kura::rt::MakeVariant("Reset"), &error);const kura::rt::KuraValue five{kura::rt::kTagInt, 5};session->Send(kura::rt::MakeVariant("Set", &five), &error);
// draw a frame, then UI => host: the click lands on a button, and its Message is sentkura_rt_set_viewport(width, height);session->Render(&error);bool handled = false;session->Click(mouse_x, mouse_y, &handled, &error);A few rules:
- Messages are delivered one at a time, in the order they were sent. A Message sent from inside a listener waits until the one being delivered is done.
Sendreturns false, and the state and listeners are left alone, ifupdatecouldn’t run (for instance, the Message isn’t one of the program’s).- With no
update, there is no state to change, and a Message goes straight to the listeners. - A click goes to the topmost element under it that has an
on-click. A click on nothing is not an error (handledis false). - A
Sessionbelongs to one thread:RenderandClickgo on the thread that draws.
There are no subscriptions, and your own Messages are yours: the runtime never invents one for you.
The fixed exception is the set of built-in event payloads that elements can carry
(on-click, on-input, on-scroll). They are predefined so the runtime and the host
agree on how user input gets back into your UI as Messages. Only on-click, on blocks and
buttons, is routed so far.
Built-in messages
Section titled “Built-in messages”Some things a UI needs to know come from the world around it, not from anything in the UI. The host tells it with built-in messages: Messages and types that every program has without declaring them, until a standard library exists to hold them.
type Size = { width: Float, height: Float }
type SystemMessage = Resized(Size) | Focused(Bool)| Message | Sent when |
|---|---|
Resized(Size) |
The viewport changed size, in the pixels the UI is drawn in. |
Focused(Bool) |
The UI gained (true) or lost (false) the host’s input focus. |
That is how your UI reacts to a resize without a “get viewport size” API. A program gets the ones it
asks for by listing them in its Message type, by name or all at once with SystemMessage:
type Message = Increment | Resized(Size) // by nametype Message = Increment | SystemMessage // all of them
type State = { value: Int, width: Float, height: Float }
fn update(msg: Message, state: State): State => match msg { Increment => { value: state.value + 1, width: state.width, height: state.height } Resized(size) => { value: state.value, width: size.width, height: size.height } _ => state }
fn view(state: State): Node => { // wide windows lay out in a row, narrow ones in a column #block(direction: if state.width > 700.0 { "row" } else { "column" }, width: 1fr, height: 1fr) { #text("Hello") }}The host sends them like any other Message, or with the Session’s Resized and Focused:
kura_rt_set_viewport(width, height); // what the view draws intosession->Resized(width, height, &error); // and how it finds outsession->Focused(true, &error);A few rules:
- A built-in message goes through
updatefirst and then to the listeners, like every Message. One that isn’t in the program’s Message type is not an error:updatecan’t take it and never sees it, and the listeners still hear it. - Tell the UI its size before it first draws, and again whenever it changes. The GL demo does, and
resizing its window re-lays-out
examples/counter.kui. - A program can’t declare a type named
SizeorSystemMessage, and can’t giveResizedorFocusedanother payload: the host builds these values, and a program that expected something else would read them wrongly. Any other name,Tickincluded, is yours.
Reactivity
Section titled “Reactivity”You never write change-tracking code. The compiler works out which parts of the UI depend
on which parts of the Model, and emits the invalidation and layout work at the end of
update. When update changes something that affects geometry, the UI reflows; otherwise
the work is skipped.
Layout state lives in a compiler-generated hidden state that is only reachable from the runtime and generated code. It is not part of your Model.