Build a checklist app
Create an interactive terminal checklist with term/tui: model state, keyboard input, rendering, asynchronous commands, and clean shutdown.
What you will build#
Build a small terminal app with three checklist items. A > marker shows the current row, [ ] means unchecked, and [x] means checked. Move the selection, toggle an item, and watch the completed count update. Each toggle briefly shows a status message. When you quit, the app restores the previous screen and prints a final count.
This tutorial assumes you can read basic Ocean structs, functions, and loops. You will learn how a concrete type implements tui.Model, how keyboard messages change state, how View produces the display, and how a tui.Cmd sends a message back asynchronously. There are no third-party packages to install.
The checklist lives in memory. It starts fresh each time you run it; this example does not save a file. Start with a terminal around 80 columns wide and 16 rows high so the entire view fits.
| Control | Action |
|---|---|
| Up / k | Move up one item. |
| Down / j | Move down one item. |
| Space / Enter | Toggle the selected item. |
| q / Ctrl+C | Quit and print the final count. |
1. Create a project#
Use a current Ocean compiler and matching standard-library sources with term/tui, time, native threads, and interface method dispatch. If you have not installed Ocean, follow Get started first. The library is compiled from source with your app; you do not build it separately.
Create a directory containing only this program. Run the commands below, then create a file named main.oc inside checklist. The complete source appears later on this page; the intervening steps explain each piece that goes in that file.
# Shell
mkdir checklist
cd checklist
ocean mod init example.com/checklist
Keep the package declaration and imports at the top of main.oc. All snippets in this tutorial belong to that one file unless described as a replacement. The complete program later combines them without duplication.
2. Understand the application loop#
A terminal app describes state and responds to events. The runner calls Init once, renders the current View, then delivers messages to Update. Update returns the next model and an optional command. The runner calls View again when the model changes and redraws changed output.
These three methods form tui.Model. You implement them on your own struct; Ocean checks that the methods satisfy the interface. You do not need to declare that the struct implements it. Our Checklist uses value receivers, so Update changes its local copy and returns it as the next model. Returning model is what makes those changes visible on the next iteration.
Model methods run serially on the thread calling Run. Commands run on worker threads, and their results rejoin the same message loop. This means your model can stay single-threaded as long as commands use captured inputs and return messages rather than mutating the model directly.
// Already defined by term/tui; do not redeclare it in main.oc.
interface Model {
Init() Cmd;
Update(message Msg) (Model, Cmd);
View() string;
}
Within the library, Msg is an alias for any and Cmd is an alias for func() Msg. A message can be a library event or a struct you define. A command is a function value that the runner executes for you.
3. Define the checklist state#
Start main.oc with these imports and declarations. Item contains a label and a checked flag. Checklist owns a dynamic array of items, a zero-based cursor, and the transient notice. revision identifies the newest notice so an old timer cannot clear a newer one.
clearNoticeMsg is an application-defined message containing the revision to clear. It is a plain struct; because tui.Msg is any, it can travel through the same queue as keyboard and resize events.
package main;
import "io";
import "term/tui";
import "time";
struct Item { Label string; Done bool; }
struct Checklist {
items Item[];
cursor int;
notice string;
revision int;
}
struct clearNoticeMsg { revision int; }
The fields not explicitly initialized below receive zero values: Done is false, cursor and revision are 0, and notice is empty. We keep the items in the model rather than in global variables so View and Update describe the same application state.
4. Create the initial model and Init#
initialModel constructs three unchecked items. The typed Item[] literal creates a dynamic array. Each Item literal sets Label and lets Done default to false.
Init returns tui.NoCmd because the first screen needs no background work. The runner can render the items immediately. Return the function value tui.NoCmd, without parentheses: Init must return a command, whereas tui.NoCmd() would produce a message.
func initialModel() Checklist {
return Checklist{items: Item[]{
Item{Label: "Learn the model/update/view loop"},
Item{Label: "Toggle a checklist item"},
Item{Label: "Write a terminal app in Ocean"}
}};
}
func (model Checklist) Init() tui.Cmd { return tui.NoCmd; }
The same distinction matters when quitting: tui.Quit is a command function value. It eventually returns QuitMsg, which the runner handles as a request to stop.
5. Handle keyboard messages in Update#
Update accepts a tui.Msg and returns (tui.Model, tui.Cmd). A type switch separates keyboard input from our timer message and EOF. Unknown messages fall through to the final return, which keeps the model and schedules no effect. That includes WindowSizeMsg: the runner still clips the display to the viewport, even though this small app does not calculate a custom layout.
For a key event, ignore Alt-modified input, then handle q and Ctrl+C before checking whether the list is empty. An empty checklist must still be able to quit. Navigation checks both ends of the array before moving the cursor, so repeatedly pressing Up or Down stays on the first or last item.
Space and Enter toggle the selected Done field, set the notice, and increment its revision. The returned Tick command will clear that notice later; the next section explains that part. EOF also requests a normal quit.
func (model Checklist) Update(message tui.Msg) (tui.Model, tui.Cmd) {
switch (event := message.(type)) {
case tui.KeyMsg:
if (event.Alt) return model, tui.NoCmd;
if (event.Key == "ctrl+c" || event.Text == "q") return model, tui.Quit;
if (len(model.items) == 0) return model, tui.NoCmd;
if (event.Key == "up" || event.Text == "k") {
if (model.cursor > 0) model.cursor--;
} else if (event.Key == "down" || event.Text == "j") {
if (model.cursor + 1 < len(model.items)) model.cursor++;
} else if (event.Key == "space" || event.Key == "enter") {
index := model.cursor;
model.items[index].Done = !model.items[index].Done;
model.notice = model.items[index].Done ? "Item checked." : "Item unchecked.";
model.revision++;
return model, tui.Tick(900 * time.Millisecond, clearNoticeMsg{model.revision});
}
case clearNoticeMsg:
if (event.revision == model.revision) model.notice = "";
case tui.EOFMsg:
return model, tui.Quit;
}
return model, tui.NoCmd;
}
The Key field names special keys such as up, down, space, enter, and ctrl+c. Text contains printable input, so q, j, and k are compared with event.Text. The initial cursor is valid and the navigation guards keep it valid. If you later add deletion, also clamp the cursor after removing an item.
6. Clear feedback with an asynchronous command#
The toggle branch returns tui.Tick(900 * time.Millisecond, clearNoticeMsg{model.revision}). Tick waits on a worker, then returns clearNoticeMsg to the application loop. You can keep moving and toggling items while that worker sleeps. Do not call time.Sleep inside Update: that would block input and rendering on the application thread.
Each toggle starts a new timer. Suppose you check one item and toggle another half a second later. The first timer must not erase the second notice early. Each message carries the revision from the toggle that created it; Update clears notice only when the message still matches the model’s current revision.
No locks or calls to threads.Spawn are needed here. The command receives a snapshot of the revision, and only Update mutates Checklist. The framework starts, tracks, and cleans up the command workers.
// The toggle branch returns this command.
return model, tui.Tick(900 * time.Millisecond, clearNoticeMsg{model.revision});
time.Millisecond is the number of nanoseconds in a millisecond. Tick accepts a nanosecond duration, as does time.Sleep. Timers are approximate and subject to operating-system scheduling; the app should not depend on an exact delivery instant.
7. Turn the model into a View#
completed counts checked items without changing the model. View builds a string from that state: a title, one row per item, the progress count, the temporary notice, and the controls. The cursor and checkbox markers are separate, so the selection can move without changing a checkmark.
Use a newline between logical rows. The runner handles terminal newline translation and clears content left over from the previous view. An empty notice still occupies its own line, which keeps the help text in the same place while notices appear and disappear.
func (model Checklist) completed() int {
count := 0;
for (i := 0; i < len(model.items); i++) {
if (model.items[i].Done) count++;
}
return count;
}
func (model Checklist) View() string {
text := "Ocean checklist\n\n";
for (i := 0; i < len(model.items); i++) {
cursor := i == model.cursor ? "> " : " ";
checkbox := model.items[i].Done ? "[x] " : "[ ] ";
text += cursor + checkbox + model.items[i].Label + "\n";
}
if (len(model.items) == 0) text += "No items yet.\n";
text += "\nCompleted: " + io.Sprint(model.completed()) + "/" + io.Sprint(len(model.items));
text += "\n" + model.notice;
text += "\n\nUp/Down or j/k: move | Space/Enter: toggle | q: quit";
return text;
}
View returns text; it does not print it. Calling io.Print or io.Println during Run would compete with the renderer. io.Sprint is safe here because it formats an integer into a string without writing to the terminal. The renderer clips lines and columns that do not fit, so a very small terminal may hide some controls.
8. Start the program and read the final model#
NewProgram receives the initial Checklist through its Model interface. AltScreen: true puts the app on the terminal’s alternate screen, preserving the shell screen for when the app exits. Keep the Program in one variable; do not copy it after it starts, because it contains synchronization state.
Run blocks until the application quits or encounters an error. Its Result contains the final model interface. unwrap reports an error as a panic; for an app with custom error handling, match the Result instead. The concrete model throughout our app is Checklist, so final.(Checklist) retrieves that final value.
Printing is safe after Run returns: the runner has restored the terminal and joined its command workers. The summary therefore appears on your normal shell screen rather than disappearing with the alternate screen.
func main() {
program := tui.NewProgram(initialModel(), tui.Options{AltScreen: true});
final := program.Run().unwrap();
checklist := final.(Checklist);
io.Printfln("Checked {} of {} items.", checklist.completed(), len(checklist.items)).unwrap();
}
Quit uses the framework’s normal shutdown path. Outstanding notice timers are cancelled and joined, and their remaining results do not need to be delivered. In a real I/O command, use bounded operations: arbitrary blocking native I/O can delay worker shutdown.
9. Copy the complete program#
Here is the complete main.oc. If you assembled the earlier snippets, use this to compare your file; otherwise copy this whole block into main.oc. Keep only one copy of each declaration. No additional source files or dependencies are required.
package main;
import "io";
import "term/tui";
import "time";
struct Item { Label string; Done bool; }
struct Checklist {
items Item[];
cursor int;
notice string;
revision int;
}
struct clearNoticeMsg { revision int; }
func initialModel() Checklist {
return Checklist{items: Item[]{
Item{Label: "Learn the model/update/view loop"},
Item{Label: "Toggle a checklist item"},
Item{Label: "Write a terminal app in Ocean"}
}};
}
func (model Checklist) Init() tui.Cmd { return tui.NoCmd; }
func (model Checklist) Update(message tui.Msg) (tui.Model, tui.Cmd) {
switch (event := message.(type)) {
case tui.KeyMsg:
if (event.Alt) return model, tui.NoCmd;
if (event.Key == "ctrl+c" || event.Text == "q") return model, tui.Quit;
if (len(model.items) == 0) return model, tui.NoCmd;
if (event.Key == "up" || event.Text == "k") {
if (model.cursor > 0) model.cursor--;
} else if (event.Key == "down" || event.Text == "j") {
if (model.cursor + 1 < len(model.items)) model.cursor++;
} else if (event.Key == "space" || event.Key == "enter") {
index := model.cursor;
model.items[index].Done = !model.items[index].Done;
model.notice = model.items[index].Done ? "Item checked." : "Item unchecked.";
model.revision++;
return model, tui.Tick(900 * time.Millisecond, clearNoticeMsg{model.revision});
}
case clearNoticeMsg:
if (event.revision == model.revision) model.notice = "";
case tui.EOFMsg:
return model, tui.Quit;
}
return model, tui.NoCmd;
}
func (model Checklist) completed() int {
count := 0;
for (i := 0; i < len(model.items); i++) {
if (model.items[i].Done) count++;
}
return count;
}
func (model Checklist) View() string {
text := "Ocean checklist\n\n";
for (i := 0; i < len(model.items); i++) {
cursor := i == model.cursor ? "> " : " ";
checkbox := model.items[i].Done ? "[x] " : "[ ] ";
text += cursor + checkbox + model.items[i].Label + "\n";
}
if (len(model.items) == 0) text += "No items yet.\n";
text += "\nCompleted: " + io.Sprint(model.completed()) + "/" + io.Sprint(len(model.items));
text += "\n" + model.notice;
text += "\n\nUp/Down or j/k: move | Space/Enter: toggle | q: quit";
return text;
}
func main() {
program := tui.NewProgram(initialModel(), tui.Options{AltScreen: true});
final := program.Run().unwrap();
checklist := final.(Checklist);
io.Printfln("Checked {} of {} items.", checklist.completed(), len(checklist.items)).unwrap();
}
10. Check, run, and try the controls#
From the checklist directory, check the program, then run it in your terminal. The first command validates the package, imports, and native linking. The second command opens the checklist. To keep an executable, build it after leaving the running app.
# Shell
ocean check .
ocean run .
# After quitting the app:
ocean build . -o checklist
The cursor starts on the first row and Completed reads 0/3. Press Space to check it: the first row becomes [x], progress becomes 1/3, and Item checked. appears briefly. Press Down, then Enter to check the second row. Press k to move back up and Space to uncheck the first row. Progress should be 1/3. Press q; the app restores the shell screen and prints Checked 1 of 3 items. Repeating Up or Down at the ends should never move outside the list.
Where to go next#
To change the checklist, edit the labels in initialModel. To add a shortcut, add a branch to Update and keep View free of side effects. To add insertion or deletion, update the array and preserve the invariant that cursor points to an existing item whenever the list is nonempty.
For a responsive layout, handle WindowSizeMsg and store its Width and Height in the model. For file loading or saving, return a command and handle its result message in Update. Preopen independent streams before Run and close them after Run returns; the existing os registry is not internally synchronized for concurrent stream registration. Do not use command I/O on the terminal’s own stdin or stdout.
If term/tui cannot be resolved, use matching current compiler and library installations, or point OCEAN_SRC at your library checkout. If Run reports that output is not a terminal, launch it directly in an interactive terminal rather than redirecting stdout. Headless mode is available for model/command tests, but intentionally produces no terminal interface.