import setup "gt:setup" (the package is named tk_setup). A program downloaded as one file installs itself for the
user from a dialog of its own: Install, Repair, Upgrade, Update the shortcuts, Uninstall, Open the installed copy. It is
the layer over desktop.md: the state of the install, what Install and Uninstall do, and the dialog.
cfg := setup.Setup_Options{
identity = identity(), // desktop.Identity: names, marks, manifest, uninstall_arguments ("--setup")
version = APP_VERSION,
install_folder = "papier", // beside the default parent ("": the desktop package's default)
prepare = proc(o: ^desktop.Integration_Options, user: rawptr) { // the program's own parts of an install
o.autostart, o.autostart_arguments = true, "--hidden"
o.add_to_path = true
},
}
d: setup.Dialog
// at a start, in a build: the dialog when there is something to do, unless the user answered already
if setup.wanted(setup.facts(cfg), APP_VERSION, saved_choice) { setup.open(&d, cfg, logo) }
// a logo made later (from a task's answer): set_logo, never Dialog.logo itself; shown from the next frame
setup.set_logo(&d, logo)
// the vendor signs the header: "By <mark> <identity.vendor>", the name a link to cfg.vendor_url ("": the name alone).
// logo_make makes a mark (or the logo) from a PNG's bytes; logo_destroy frees it before the renderer goes.
mark, _ := setup.logo_make(&renderer, #load("../assets/froment-software-64.png"), {16, 16})
setup.set_vendor_mark(&d, mark) // or setup.open(&d, cfg, logo, mark); prefs_page.Install.vendor_mark for the page too
// each frame
switch setup.update(&d, cfg) {
case .Installed: saved_choice = setup.CHOICE_INSTALLED
case .Kept_Standalone: saved_choice = setup.CHOICE_STANDALONE
case .Dismissed: saved_choice = setup.choice_dismissed(APP_VERSION)
case .Launched: quit() // then setup.launch(d.installed) once the window and the instance are gone
case .Uninstalled, .None:
}
// at the end of the process
setup.finish(&d, cfg)
setup.destroy(&d)The dialog says where everything is: the installed program, the menu's entry, the system's record, this copy. A path that does not fit is cut; the pointer over it shows it whole, and a click on it or on the copy button after it puts it on the clipboard.
The dialog is the view setup.VIEW ("setup", home Dialog, views): its header (" Setup", the close
cross) is the toolkit's. It opens at 46 by 34 em; its edges and its corner resize it, and the views remember its size.
What it says scrolls when it is made small; its buttons stay under it. Escape, the close cross or a press outside give
Dismissed through update, unless there is nothing to ask.
A program does not drive the dialog by hand: prefs_page.Install (prefs_page.md, "The installation")
holds it, opens it at a start, keeps the answer and shows the Installation page of the settings. The calls below are
what that object makes.
page(d, o, em) -> Event draws the same Dialog in the flow of a page (the settings' Installation page): the program and
its state as a badge, the state in a sentence, a well that says where everything is (the installed program, the version
installed, this copy and whether it is the installed one, the menu's entry, Settings > Apps on Windows, the start with the
session, the PATH with its console launcher on Windows), before an install its folder and options, what the last action
said, then Install (Repair, Upgrade…), Open the installed copy and Uninstall (a second click does it). The first build
of the page opens the Dialog (its facts read on its thread, the places watched); update closes it again, with no
event, after a build that did not draw it (Dialog.in_page, page_build): leaving a page answers nothing.
Facts.autostart and Facts.on_path say whether the start with the session and the PATH are in place (what
Setup_Options.prepare asked). Facts.parts has every part of the integration that is there and runs the installed
copy.
Setup_Options.choices are the program's own options of an install, a box each; prepare receives their values in
their order. A Choice tied to parts (parts = {.File_Manager}) stands for what the system has: when the install's
facts first come and a program is installed, its box starts on when those parts are all in Facts.parts, off
otherwise, whatever its on says (choices_from_facts). Before an install, the box starts from on. A file manager
offers "open folders with it" this way, and the box never claims a part that someone took away.
A PDF reader offers its documents the same way (desktop.md). It gives the types whatever the boxes say, so that removal takes them away. The default's box exists only where the system has the part:
PDF := [?]desktop.Document_Type{{".pdf", "application/pdf", "PDF Document"}}
choices = {
{label = i18n.later("Open PDF files with Feuille"), on = true, parts = {.Documents}},
{label = i18n.later("Make Feuille the default PDF reader"), on = false, parts = {.Default_Documents}},
},
prepare = proc(o: ^desktop.Integration_Options, choices: []bool, user: rawptr) {
o.document_types = PDF[:]
o.open_documents, o.default_documents = choices[0], choices[1]
},On Windows the second box has no part (supported_parts() lacks Default_Documents): give it parts = {} there. Its
Install then opens Settings at the program's page, where the person makes it the default.
choices = {
{label = i18n.later("Put the program on the PATH"), on = true, parts = {.Path}},
{label = i18n.later("Open folders with the program"), on = false, parts = {.File_Manager}},
},
prepare = proc(o: ^desktop.Integration_Options, choices: []bool, user: rawptr) {
o.add_to_path, o.default_file_manager = choices[0], choices[1]
},The same options in every program, listed in its table of options (setup.COMMAND_OPTIONS for cli.md):
| Option | What it does |
|---|---|
--install |
installs this copy for the user, as the Install button does (install): no window |
--uninstall |
removes the installed copy (uninstall, then remove_later for what the running copy holds); the user's settings and data stay: no window |
--status |
says the state in a word, then a fact a line (the program, its version, this copy, the menu entry, the start with the session, the PATH, running: true when a copy runs: Setup_Options.running, the program's single-instance check; quit: yes when --quit can end it: Setup_Options.quit); exit code 0 installed whole (a Nix package too), 1 not installed or to repair (status_exit; the words say which): no window |
--quit |
asks the copy that runs to end (Setup_Options.quit, its single instance: instance.MESSAGE_QUIT), then waits until its instance is gone and no process runs the installed copy's file, at most QUIT_WAIT (10 s); exit code 0 ended or not running, 1 still running or cannot be asked: no window |
--setup |
starts the program with the install shown (prefs_page.install_open); Settings > Apps' Uninstall runs it (Identity.uninstall_arguments = "--setup") |
A program gives running and quit from its single instance (instance.md, "The messages every program
understands"): quit sends instance.MESSAGE_QUIT, and the handler of the copy that runs closes its window. A program
without quit answers quit: no, and --quit fails at once when it runs: an installer then ends its process by other
means (process.processes_of, process.signal_process).
cmd, rest := setup.command_of(os.args[1:])
if setup.command_alone(cmd) { cli.exit(setup.command_run(cmd, setup_options(), process.console_write)) } // install, uninstall, status, quit
// ... the window; then for .Setup: prefs_page.install_open(&app.install)command_run says what happened on one line, in English (a script reads it): <name>: installed: <exe>, <name>: uninstalled (your settings and data stay), or why it failed; it ends with a cli.Exit, .Done or .Failed.
--status is status_text and status_exit: .Done for an install there whole, .Failed for none or one to repair
(its words say which). It reads and writes the disk: call it before the window, never from a frame. These are the
program's one install command line.
A program that wants another layout keeps the Dialog and its machinery and draws the rest in a view of its own: it
calls start in place of open, update each frame, and the actions from its own buttons. The state, what is offered
and the work (on the dialog's thread, the install watched) are the same as in the toolkit's view, which calls the same
procedures.
setup.start(&d, cfg); ui.view_open(ui.views(), "my_setup", &d) // opening, in a build
ev := setup.update(&d, cfg) // each frame, open or not: the work that ended, the install read again
my_setup_view :: proc(v: ^ui.View, d: ^setup.Dialog) { // registered with ui.view_register
title, badge := setup.headline(d.facts, cfg) // "Install Classeur", "Not installed"
words, tone := setup.state_words(d.facts, cfg) // the state in a sentence, its tone
ui.checkbox("###shortcut", "Shortcut on the Desktop", &d.shortcut) // d.choices[i]: Setup_Options.choices (set from the facts)
if setup.can_uninstall(&d) && my_button("Uninstall") && !setup.busy(&d) { setup.start_uninstall(&d, cfg) }
how := setup.closing(&d, cfg) // Close, Not_Now or Keep_Standalone
if my_button(...) { ev = setup.close(&d, how) }
if d.installed != "" && my_button("Open the installed copy") { ev = setup.open_installed(&d) }
if label := setup.install_label(&d, cfg); label != "" && my_button(label) && !setup.busy(&d) { setup.start_install(&d, cfg) }
}
// Escape or a click outside ended the view (ui.view_ended): setup.close(&d, .Close) gives the event to keepupdate(d, o) -> Event |
each frame: collects the work that ended, reads the install again when it changed, stops watching once closed |
headline(f, o), state_words(f, o) |
what the screen offers and the state in a word; the state in a sentence and its tone |
install_label(d, o) |
Install, Repair, Upgrade to …, Go back to …, Replace the installed copy, Update the shortcuts; "": none |
can_uninstall(d), busy(d) |
something of an install is there; Install, Uninstall or the picker is at work |
closing(d, o) -> Closing |
Close, Not_Now (an upgrade) or Keep_Standalone (no install, another copy) |
start_install, start_uninstall, pick_folder |
the work, on the dialog's thread (nothing while work is out) |
open_installed(d) |
Launched when there is a Dialog.installed: the program ends, then starts it with launch once its window is closed and its single instance released (prefs_page.install_launch does) |
close(d, how) |
closes it: Kept_Standalone, Dismissed (Not now, or no answer), or None (nothing to remember) |
Dialog.facts, known (read once), shortcut, choices, folder, note / note_good, installed and confirm
are what such a screen shows and sets.
The dialog is drawn with the theme's widgets. A program with a look of its own gives Setup_Options two procedures (each may be
nil, and Setup_Options.user is passed to them). The header and its close cross are the views' (views):
backdrop(v, user) |
drawn first in the view, under its header: what lies behind it (a blur of the window, a dim of its own); nil: the theme's scrim. v.presentation says where it is: paint a scrim only as .Dialog (floating, docked or in a window of its own, it has none) |
button(id, label, glyph, intent, em, user) -> bool |
each button: its words, a Lucide glyph and a ui.Intent (Success: what installs or opens, Danger: Uninstall, Cancel: what closes, Primary: Choose); clicked: true |
| State | When | The dialog offers |
|---|---|---|
Not_Installed |
nothing of an install | Install, Do not install |
This_Copy |
the running program is the installed copy, every piece there | Update the shortcuts, Uninstall, Close |
Repair |
a launcher, the record, the manifest or a file is missing | Repair, Uninstall |
Other_Copy |
a copy is installed elsewhere (is_upgrade: an older one) |
Replace (Upgrade to …), Uninstall, Do not install (Not now) |
Removal_Scheduled |
uninstalled while it runs | Close: the file goes when the process ends |
Nix_Package |
the copy runs from the Nix store | nothing: Nix installs it |
wanted(facts, version, choice) opens the dialog at a start for an upgrade (unless closed for this version), for no
install or one to repair (unless the user chose standalone, or closed it for this version); never for a copy of the
Nix store. The program keeps the choice between starts: CHOICE_INSTALLED, CHOICE_STANDALONE,
choice_dismissed(version).
install(o, desktop_shortcut) copies the running program into the install folder (desktop.files_install; on NixOS
it is made to run by itself), writes its launchers and Setup_Options.prepare's parts (desktop.install) and the system's
record (desktop.record_install: on Windows, Settings > Apps, whose Uninstall runs <exe> <uninstall_arguments>).
uninstall(o) takes it all away; what the running copy holds (Windows) is in its leftovers, which finish hands to
desktop.cleanup_later at the end of the process. After an install from another copy, the dialog offers to open the
installed one (Launched): the program ends, then starts it (prefs_page.install_launch).
When update.Updater has put a new program in place of the installed copy (docs/update.md), updated(o, version)
makes the install say it: the install manifest names the new version, and so does the system's record (Settings > Apps on
Windows). For a program that is not the installed copy (a build, an unzipped folder), it does nothing and returns ok.
launch(exe, args) starts a copy of the program (the installed one after an install, the new one after an update or on
Restart), in its folder. Call it once the window is closed and the single instance released, as the process ends. On Windows
it allows the new process the foreground (AllowSetForegroundWindow): the click on Restart was this process's input, but its
window is gone, and without that grant the new window would open behind the others with its taskbar button flashing.