Skip to content

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 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) | Tick
type Model = { clicks: Int }
  • Only view is required. A static UI needs no state and no reactivity.
  • init and update are not allowed without a view.
  • init may exist without update.
  • If there’s no init, the host can build the state itself (for example, an inventory constructed in C++) and pass it to view.

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 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 => UI
session->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 sent
kura_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.
  • Send returns false, and the state and listeners are left alone, if update couldn’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 (handled is false).
  • A Session belongs to one thread: Render and Click go 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.

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 name
type 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 into
session->Resized(width, height, &error); // and how it finds out
session->Focused(true, &error);

A few rules:

  • A built-in message goes through update first and then to the listeners, like every Message. One that isn’t in the program’s Message type is not an error: update can’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 Size or SystemMessage, and can’t give Resized or Focused another payload: the host builds these values, and a program that expected something else would read them wrongly. Any other name, Tick included, is yours.

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.