{"slug": "retro-nim-ui-windows-3-1-style-ui-toolkit", "title": "Retro Nim UI – Windows 3.1 style UI toolkit", "summary": "Sultan Al Isaiee (@foxoman) released retroui, a Windows 3.1-style UI toolkit for the Nim language, installable via `nimble install retroui`, that builds apps for Windows, macOS, Linux, Android 7+, iOS and the web from one code base. A hello-world app compiles to a single 1.9 MB file (about 1 MB of it fonts) that runs in 7 MB of memory on one thread, versus 15-22 MB files and 15-120 MB of memory for the same Hello in egui, iced or Slint, and the toolkit requires no dependencies beyond Nim and a C compiler. The companion `retrokit` tool packages apps for Google Play (APK, App Bundle), the Microsoft Store (MSIX, Authenticode-signed program), the App Store (.ipa) and the web, and a Retro Designer tool edits the same `.nim` file directly.", "body_md": "**Developed by Sultan Al Isaiee [@foxoman](https://github.com/foxoman)** --\n[www.foxoman.net](https://www.foxoman.net) -- [sultan@foxoman.net](mailto:sultan@foxoman.net)\n\nCo-author: Claude (Anthropic)\n\nA **Windows 3.1 style UI toolkit for Nim** that builds business and desktop\napps for **Windows, macOS, Linux, Android, iOS and the web** from one code\nbase, and packs them for the stores itself. The\npackage and its module are called `retroui`: `nimble install retroui`, `import retroui`.\n\n**Learn the syntax: [docs/syntax.md](https://github.com/foxoman/retroui/blob/main/docs/syntax.md)** -- the whole way of\nwriting an app, every form of it as a small program with a picture of what\nit draws: what `row([50, -1])` does with the 50 and the -1, binding, events,\ncontainers, dialogs, how it is built and why it is easy to follow.\n\n**Documentation: [docs/controls.md](https://github.com/foxoman/retroui/blob/main/docs/controls.md)** -- every control with\npictures: getting started, layout, each control's example and API, the looks.\n\n**Design it: [Retro Designer](https://github.com/foxoman/retroui/blob/main/docs/designer.md)** -- `retrokit designer app.nim` shows your file's windows drawn with the real controls: drop\ncontrols, drag them, set their properties, add their events, and every\nchange is written into the same `.nim` file.\n\n- **Small and light.** A \"hello\" app is a single 1.9 MB file (Linux\nx86-64, built with`retrokit small` ; about 1 MB of it the fonts) that\nruns in 7 MB of memory on one thread -- the same Hello in egui, iced or\nSlint is a 15-22 MB file in 15-120 MB (see[Speed and size](#speed-and-size) );\nthe full file manager is 4.3 MB, and the gallery with every control, the\nstreet map, 3D models, the canvas and PDF 5.7 MB. Fonts, icons, the PDF writer, the world map, the 3D view and\nthe decoders are all built in, and only what an app calls is linked.\n- **No dependencies.** You need Nim and a C compiler — nothing else to\ninstall, now or on the user's machine: no GTK, Qt, SDL, Electron, browser\nengine or Java toolchain. On Linux, libX11 is the one library an app\nneeds, loaded when it starts (Xft, XRender, EGL and the rest are used when\nthe system has them), so building needs no`-dev` packages; sound, video\nand printing use whatever the system offers, loaded only when used.\n- **Runs anywhere.** One code base for Windows, macOS, Linux/BSD (X11, and\nWayland with a driver of its own), Termux:X11, Android 7+, iOS, a web page\n(WebAssembly made by clang alone, no Emscripten) and a screen with no\nwindowing system at all (a kiosk, a device: the Linux framebuffer or DRM).\nTouch, mouse and keyboard all work everywhere, and the layout adapts to\nphones, tablets, laptops and 4K screens.\n- **Ships itself.**`retrokit` makes what each store takes, in Nim, on any\nsystem: an APK and an App Bundle for Google Play, an MSIX and an\nAuthenticode-signed program for Windows and the Microsoft Store, a signed\nmacOS app (notarized on a Mac), an .ipa for the App Store, a web page\nthat installs and works offline.\n- **Fast.** Immediate mode with a software renderer that redraws only the\n32-pixel bands that changed: a full 800×600 window takes about 0.25 ms, an\nunchanged frame costs nothing and is not sent to the screen, and the app\nuses no CPU while it waits. A 50,000-file folder or a 100,000-row grid\nscrolls in well under a millisecond per frame.\n- **For everyone.** Screen readers read every control and act through it\non every platform -- Orca, NVDA, JAWS, Narrator, VoiceOver, TalkBack --\nwith nothing for an app to do but put a label before a box; input\nmethods (Chinese, Japanese, Korean) compose in the text box; the window\ntakes the scale of the monitor it is on, 125 % or 175 % alike.\n- **Reaches any OS API.**`retroui/native` calls any Android Java API without\nwriting Java, any macOS/iOS API through the Objective-C runtime, Win32 and\nCOM, and any C library through`dlopen` , with ready-made cross-platform\ncalls (battery, vibrate, dark mode, device name…).\n- **Business ready.** Data grids with check boxes, colour status cells,\ndrop-downs, buttons, per-cell colours and totals; forms with masked\nfields; record navigators; property grids; tree grids; 21 chart types;\nPDF reports from HTML templates, with printing; kanban, Gantt, agenda and\norg charts; maps; MDI windows; wizards.\n- **Looks the part.** The 3.1 look down to the pixel — black outlines, the\ntwo-step bevels, the default button's ring, navy and white title bars,\ndithered scroll tracks, etched group boxes, hard menu shadows — in**FreeSans** (GNU FreeFont's Helvetica-like sans, with its bold, oblique\nand bold oblique), its heights on whole pixels so it is crisp at 100 %,\nat 125 % and 150 %, and on HD, 2K and 4K screens, with Arabic everywhere\n(FreeSerif's).**FreeSerif** ,**FreeMono** or a font file are the other\nchoices (`setUiFont` , or the user in`appearanceSettings` ; see \"The\nfonts\" below). 255 pixel icons in\nthe manner of the period. Lists and pages glide when scrolled, and a\nflicked finger keeps them moving.\n- **Safe.** Every decoder and parser (pictures, zip and ZIP64, CSV,\nMarkdown, HTML, OBJ, STL and glTF models, vector tiles, the map services'\nanswers, certificates, the programs it signs) is fuzzed with hostile\ninput, and the tests also run under AddressSanitizer and as 32-bit\nprograms. See[SECURITY.md](https://github.com/foxoman/retroui/blob/main/SECURITY.md) .\n\n**Every control, its API and how it looks in each state** (normal, keyboard\nfocus, mouse over, pressed, disabled, open, touch screen, dark scheme) is in\n**[docs/controls.md](https://github.com/foxoman/retroui/blob/main/docs/controls.md)**; the generated API reference of\nevery module is in `docs/api/` (open `docs/api/retro.html`).\n\n[The syntax, studied](https://github.com/foxoman/retroui/blob/main/docs/syntax.md) · [Install](#install) · [Your first app](#your-first-app) ·\n[Retro Designer](#retro-designer) · [How it works](#how-it-works) · [Controls](#controls) · [Layout](#layout) ·\n[Text and icons](#text-and-icons) ·\n[Screen readers and input methods](#screen-readers-and-input-methods) · [Business apps](#business-apps) ·\n[Charts](#charts) · [Reports, PDF and printing](#reports-pdf-and-printing) ·\n[Planning views](#planning-views) · [Desktop apps](#desktop-apps) ·\n[Files](#files) · [Maps](#maps) · [3D](#3d-view) · [Canvas](#canvas) · [Whiteboard](#whiteboard) ·\n[What the computer is doing](#what-the-computer-is-doing) ·\n[Image editing](#image-editing) · [Web and HTML](#web-and-html) · [Sound and video](#sound-and-video) ·\n[Camera and microphone](#camera-and-microphone) · [More windows](#more-windows) ·\n[The system's features](#the-systems-features) · [The system's own APIs](#the-systems-own-apis) ·\n[Updates inside the app](#updates-inside-the-app) · [Platform services](#platform-services) · [Android](#android) · [iOS](#ios) ·\n[Apps as web pages](#apps-as-web-pages) · [Screens without a desktop](#screens-without-a-desktop) ·\n[Shipping to the stores](#shipping-to-the-stores) ·\n[Platforms](#platforms) · [Speed and size](#speed-and-size) ·\n[Safety](#safety) · [Tests](#tests) · [Examples](#examples) · [FAQ](#faq) ·\n[Limits](#limits) · [License](#license)\n\nYou need **Nim 2.0 or newer** and **a C compiler**:\n\n| System | Get them | Notes | \n|---|---|---|\n| Windows | `choosenim` (brings MinGW-w64) | GDI, nothing else | \n| macOS | `brew install nim` ,`xcode-select --install` | Cocoa | \n| Linux / BSD | your package manager: `nim` ,`gcc` or`clang` | X11 is loaded at run time, Wayland spoken by the kit itself: no `-dev` packages | \n| Android, on the device | Termux: `pkg install nim clang ndk-sysroot git` | builds APKs right on the phone | \n| Android, from a desktop | a clang with lld (LLVM on Windows, `brew install llvm lld` ,`clang lld` packages) or zig; with neither, the first APK build fetches the NDK into`~/.retro/ndk` | no NDK, no Java, no Gradle, no SDK, no OpenSSL | \n| iOS | a Mac with Xcode | | \n| The web | clang and lld ( `apt install clang lld` , LLVM on Windows,`brew install llvm lld` ) | WebAssembly without Emscripten | \n\nThen:\n\n```\nnimble install retroui # the library and its tools (or the repository's URL)\nretrokit doctor # checks what this machine has\nretrokit new myapp --kind:business # a ready app: hello, form, business, files, charts\ncd myapp && nimble run\n```\n\n`retrokit` is the helper that comes with the package:\n\n| Command | What it does | \n|---|---|\n| `retrokit new NAME --kind:K` | a folder with `NAME.nim` ,`NAME.nimble` (tasks run, small, apk) and an icon | \n| `retrokit doctor` | checks Nim, the C compiler, the screen libraries, the Android tools, what Retro Designer needs, and says how to fix what is missing | \n| `retrokit run app.nim` | builds in release mode and runs it | \n| `retrokit small app.nim` | the smallest build (optimized for size, stripped), and its size | \n| `retrokit apk app.nim` | an Android APK (the `retroapk` tool, below) | \n| `retrokit aab app.nim` | an Android App Bundle for Google Play, signed with your upload key | \n| `retrokit web app.nim` | the app as a web page: installable, offline ( [Apps as web pages](#apps-as-web-pages) );`retrokit run --web --watch` serves it and reloads on every save | \n| `retrokit sign app.exe` | Windows' Authenticode signature, made here, with a time stamp | \n| `retrokit msix app.exe` | an MSIX for the Microsoft Store and Windows' installer, signed | \n| `retrokit mac app` | a macOS `.app` , signed ad hoc here or with your Developer ID, notarized and stapled on a Mac | \n| `retrokit ipa App.app` | an iOS app as the `.ipa` TestFlight and the App Store take | \n| `retrokit model car.blend` | a 3D model (Blender's, glTF, OBJ, STL) as the `.glb` an app carries, its parts and clips named | \n| `retrokit designer app.nim` | [Retro Designer](#retro-designer) : the file's windows to design, every change written into the file (built once for this computer) | \n\nFrom a clone of this repository (the examples are built only when you ask,\none at a time; `nimble install retroui` installs only the toolkit and its\ntools):\n\n```\nnimble gallery # every control in one window\nnimble files # Retro Files, the file manager (a folder after it: opens there)\nnimble ledger # a small business app: invoices, customers, reports\nnimble invoice # an invoice from an HTML template: preview, PDF, printing\nnimble charts # Chart Viewer: a CSV file as charts, saved as PNG\nnimble photo # Retro Photo, the image editor\nnimble board # Retro Board, the whiteboard\nnimble taskman # Retro Task Manager: the programs, the processor, the memory, the network\nnimble mail # Retro Mail: Microsoft 365, Outlook.com, Gmail, any IMAP (mailexe, mailapk)\nnimble hrbook # HR Book: employee records of several hotels, sealed with a PIN\nnimble apk # Retro Files as an Android APK (build/RetroFiles.apk)\nnimble photoapk # Retro Photo as an APK (photoinstall: build and adb install)\nnimble galleryapk # the gallery as an APK\nnimble boardapk # Retro Board as an APK (boardinstall: build and adb install)\nnimble taskmanapk # Retro Task Manager as an APK (taskmanexe: for Windows)\nnimble photoexe # Retro Photo for Windows, with its icon (from Linux or macOS: MinGW; build/win/)\nnimble filesexe # Retro Files for Windows (galleryexe, boardexe: the others)\nnimble photoappimage # Retro Photo as a Linux AppImage, with its icon and menu entry (one file, runs anywhere:\nnimble filesappimage # Retro Files as an AppImage built against glibc 2.31 with zig when it is there)\nRETRO_APP=hrbook nimble exe # any one app of the table in retroui.nimble: exe, appapk,\nRETRO_APP=hrbook nimble appapk # appimage, macapp\nnimble apks # every app as an APK (the apps: the table in retroui.nimble)\nnimble exes # every app for Windows\nnimble appimages # every app as an AppImage\nnimble macapps # every app for macOS, zipped .app (on a Mac: build/mac/)\nnimble apps # every example for this computer, into build/\nnimble dist # the apps and all the APKs, into build/\nnimble test # the headless tests\nnimble fuzz # the fuzzers\nnimble docs # the API reference (docs/api) and docs/controls.md\n```\n\n**Step by step** -- an APK from Windows, macOS, Linux or a BSD without\nthe Android SDK, an iOS app on a Mac, signing and installing: see\n[BUILDING.md](https://github.com/foxoman/retroui/blob/main/BUILDING.md).\n\nEvery task builds with what `nimble install` brought: the APK tasks need\nno Android NDK -- `retroapk` carries Android's headers and libraries (1.2 MB,\nunpacked once into `~/.retro/android-sysroot`) and builds with a clang that\nhas lld, or zig; with neither they fetch the NDK once (about 700 MB, into\n`~/.retro/ndk`; `nimble ndk` does it now, `ANDROID_NDK_HOME` uses yours), sign with a key made for you in\n`~/.retro/android` (`RETRO_KEYS` another folder), and need no Java, Gradle, SDK, OpenSSL or apksigner. In\nTermux the compiler is installed with `pkg` the first time.\n\nGitHub builds them too: **CI** runs the tests on each push and compiles\nthe tools on Linux, Windows and macOS (the examples when run by hand);\n**Release** -- a `v...` tag pushed, or by hand -- makes the apps I use\nevery day, Retro Gallery, Retro Files, Retro Photo, Retro Board and Retro\nMail, as an AppImage, a Windows .exe, an APK and a macOS .app, and puts\nthem on the GitHub release of that tag. Its APKs are signed with the key in\nthe secrets `ANDROID_KEY_PEM` and `ANDROID_CERT_DER` (base64 of the files in\n`~/.retro/android`), so a new one installs over the one before.\n\nA desktop app has the system's own frame, or the one Windows 3.1 had: the\ngray sizing border with dark lines at its corners, the navy title bar (white\nwhile another window is in front) with the control-menu box at its left and\nthe minimize and maximize buttons at its right. The app draws that one\nitself, in a window without the system's frame, and the system still does\nthe rest: drag the title bar to move the window (Aero Snap on Windows), the\nborder or a corner to size it; a double click or the maximize button\nmaximizes it, down to the taskbar; Alt+Space opens the control menu\n(Restore, Move, Size, Minimize, Maximize, Close, the UI's size). The menu bar,\ntool bars and the content move down under it as under a phone's title bar,\nso an app needs no change. A **size grip** sits in the bottom right corner\ninside the frame (in the status bar's end when there is one; the bottom\nleft, right to left): drag it to size the window, with the mouse or a\nfinger, on every platform the 3.1 frame is drawn. The frame takes the\ntheme's colors, and follows when the user picks another theme.\n\n**A window that keeps its size:** `app \"Calculator\", 260, 320, resizable = false:`\n(or `setResizable(false)`). The 3.1 frame then has no sizing border to drag,\nno maximize button and no grip (its border is the plain band 3.1's dialogs\nhad), and the system's frame is told the same: Windows drops the sizing\nborder and the maximize box, macOS the resize edges and the zoom button,\nX11 window managers get the same least and largest size, GTK 4 and SDL\nmake the window fixed.\n\n```\nRETRO_FRAME=classic nimble mailexe # Retro Mail for Windows with the 3.1 frame\nRETRO_FRAME=classic nimble apps # every example (exes and appimages the same way)\nnim c -d:retroFrame=classic app.nim # by hand (system: the default)\nRETRO_FRAME=system ./app # when it starts: the system's frame after all\n```\n\n**The user can always switch.** In every app, with nothing to write: the\n3.1 frame's control menu has **Windows' Own Frame** (elsewhere **Desktop's\nOwn Frame**); on Windows the system's frame gets **Windows 3.1 Frame** in\nits system menu (the title bar's icon, Alt+Space), and on macOS the menu\nbar gets it in a **Window** menu (checked while that frame is on). The\nchoice is kept for the app (`window.ini` in its data folder) and wins over\nthe frame it was built with at the next start; `appearanceSettings` offers\nit too, as **Window**. On X11 and Wayland the window manager keeps its menu\n(Alt+Space, a right click on the title bar) to itself: there\n`appearanceSettings` is the way back to the 3.1 frame, so offer it.\n\n**Where:** every desktop. Windows; macOS; Linux and the BSDs on X11, with\nany window manager (EWMH: GNOME, KDE, Xfce, openbox... -- snapping and\ntiling as for other windows) or none (an X server that shows one app: the\napp's window is then moved, sized and maximized by the driver); Wayland\ndesktops with the kit's own Wayland driver (the default build takes it when\nthere is no X11, `RETRO_DRIVER=wayland` asks for it: the system's frame\nwhere the compositor draws one, else the 3.1 frame by itself), through\nXWayland, or with `-d:gtk4` or `-d:sdl3`. The other drivers have it too: GTK 4, SDL 3\nand SDL 2 (where a double click on the title bar maximizes on Windows only,\nand the control menu's Move and Size do nothing), Siwin (not on macOS; on\nWindows the frame chosen is the next window's). Only the phones keep their\nown.\n\n**For the developer:** `app`'s `frame` (`wfAsBuilt`, `wfSystem`,\n`wfClassic`) is the frame the window opens with, `userFrame = false` takes\nthe user's choice away; `setClassicFrame(on)` changes it while the app runs,\n`chooseClassicFrame(on)` changes it as the user would (and keeps it),\n`classicFrame()` says which one is on. A window manager's own keys stay its\nown: openbox, say, opens its window menu for Alt+Space before the app sees\nit (the control-menu box still opens the app's).\n\n``` python\nimport retroui\n\nvar name = \"World\"\nvar greeting = \"\"\n\napp \"Hello\", 320, 120:\n row([50, -1]):\n label \"&Name:\"\n edit name\n row:\n if button(\"&Greet\", isDefault = true):\n greeting = \"Hello, \" & name & \"!\"\n if button(\"E&xit\"): quitApp()\n label greeting\nnim c -r -d:release -d:useMalloc hello.nim # or: retrokit run hello.nim\nretrokit small hello.nim # optimized for size, LTO, stripped: about 1.9 MB, one file\nretroapk hello.nim --install # on a phone in Termux\n```\n\nIn Termux the same `nim c -r` runs it in a window on Termux:X11 (see\nBUILDING.md, \"A desktop app in Termux\").\n\n**Working on an app in Termux.** Without a window manager, Termux:X11 gives\nan app the whole screen, as Android does. To see it as a desktop window\nwhile you work on it:\n\n```\nretrokit run --window app.nim # its own size, in its 3.1 frame, in the middle\nretrokit run --live app.nim # the same, built again and shown again on every save\nretrokit run --window --scale:125 app.nim # everything (and the window) a quarter larger\nretrokit run --window --theme:Dark --size:420x840 app.nim\n```\n\nThe toolkit draws a desktop (the 3.1 teal) over the screen and puts the\nwindow on it at the size the app asked for, grown by the screen's own scale\n(its density, so a 2K tablet shows it at its real size), with the title bar\nto move it, the border and the grip to size it, the maximize button and the\ncontrol menu. Keys go to the window, also after a tap on the desktop. When\nthe screen changes size (the tablet turns, Termux:X11's window is made\nfloating or sized) the desktop follows, and the window stays in view: made\nsmaller while the screen is, its size again when there is room. The\nline it prints says what it came to (`RETRO_WINDOW: 660 x 304 pixels on a 2560 x 1600 screen; the screen's scale 200 %`); `--scale:N` makes it\nlarger or smaller. `retrokit run` passes anything else to the compiler.\n\n**Live: see each change as you save**, on any desktop. `retrokit run --watch app.nim` builds the app again whenever a `.nim` file in its folder (or two\nlevels below) is saved, starts the new one where the window was -- the place\nand the size you gave it -- and then closes the one before, so the window\nnever goes blank. It is the same on Windows, macOS, Linux (any window\nmanager, or none) and Termux, where `--live` is `--watch` with `--window`.\nOnly what changed is compiled again: a few seconds, most of it Nim reading\nthe kit. Code that does not build leaves the window running what it had,\nwith the compiler's message in the terminal; an app that crashes starts\nagain with the next save. The app starts fresh each time (its variables are\nnew); closing its window, or Ctrl+C, ends it. The window's place is kept by\nthe X11, Windows, macOS, SDL 2 and SDL 3 drivers (`RETRO_WINDOW_STATE`,\n`keptWindowPlace`); GTK 4 and Siwin cannot place a window, so theirs opens\nwhere the system puts it.\n\n```\nretrokit run --watch app.nim # Windows, macOS, a Linux desktop\nretrokit run --live app.nim # Termux:X11: --window and --watch\n```\n\nOn Windows from Linux: `nim c -d:release -d:useMalloc -d:lto --opt:size --passL:-s -d:mingw --cpu:amd64 --app:gui hello.nim`.\n\nBuild with `-d:useMalloc` (or put `switch(\"define\", \"useMalloc\")` in your\n`config.nims`; `retroapk` adds it by itself): with Nim's own allocator a\nprogram never gives memory back to the system, and one that shows many\npictures only grows. The toolkit warns at compile time without it, and\n`retroui/memwatch` gives back what the program lets go of\n(`trimHeap`, by itself when it rests and when it goes to the background).\n\n`app` opens the window and runs its body once per frame. Each widget\ndraws itself and returns what happened: `button` is `true` when it is\nclicked, and `edit name` edits `name` in place and returns `true` when it\nchanges.\n\n`app` takes options by name after the size, all optional:\n\n``` js\nconst ledgerIcon = staticRead(\"ledger.png\")\n\napp \"Ledger\", 900, 600,\n theme = Dark, # the colors (builtinThemes, or your own Theme)\n frame = wfClassic, # wfAsBuilt (default), wfSystem, wfClassic\n userFrame = true, # the user may switch it (kept per app)\n gpu = gmAuto, # gmAuto, gmGpu, gmCpu\n scale = 125, # the size of everything, in percent\n font = ufSans, # the UI's font (ufSerif, ufMono)\n zoom = 0, # whole-pixel magnification (0: the display's)\n id = \"ledger\", # the app's name for what the toolkit keeps\n icon = ledgerIcon, # the window's picture (a PNG's bytes)\n resizable = true, # false: the window keeps its size\n look = \"ledger\": # keep the look the user picks (appearanceSettings)\n label \"Hello\"\n```\n\nA misspelled option is a compile error that lists them all. $RETRO_FRAME, $RETRO_GPU, $RETRO_SCALE, $RETRO_THEME, $RETRO_SIZE and $RETRO_ZOOM win over the options when the app starts (tests, screenshots); $RETRO_SCALE makes the window larger with everything in it. $RETRO_WINDOW=1 opens the app as a window in its 3.1 frame, in the middle of a desktop the toolkit draws, where the screen has no window manager (see \"Working on an app in Termux\" below).\n\n`retrokit designer app.nim` opens your `.nim` file in **Retro Designer**, the\nkit's visual designer, in the manner of Qt Designer: its windows drawn with\nthe real controls, the Widget Box with every control of the kit, the Object\nTree, the properties, events and variables of what you choose. Drop and drag\ncontrols, put them in rows and groups, set their properties, add their\nevents -- each change is written into the same file as Nim, touching only\nthe lines that changed: no form file, no generated code. It is purely a\ndesigner: **Edit Code** opens your editor at the control's code, and while\none of them has the file the other leaves it alone (a lock beside it, the\nfile read-only for the others). Dialogs and menus open over their window\nwhen you choose something in them; F5 shows the window working, in each\nlook.\n\nIt comes with the package and builds itself the first time you run it, for\nyour computer and your Nim: Windows, macOS, Linux and BSD, and Termux on\nAndroid (Termux:X11). The whole guide: **[docs/designer.md](https://github.com/foxoman/retroui/blob/main/docs/designer.md)**.\n\n```\nretrokit designer app.nim # app.nim's windows (a new file when there is none)\n```\n\n- **Immediate mode.** The UI is plain code that runs every frame, and\nwidgets are procs bound to your own variables. There are no callbacks\nand no widget objects to create, keep or free; whatever your code draws\nis what the screen shows. A widget is known by the variable it is bound\nto or by its label, so you never manage ids (use`pushId` /`withId` for\nrows of the same widgets).\n- **Frames only when needed.** A frame runs when input arrives, when a\ntimer asked for one (`wakeIn(ms)` ) or when work on a background thread\nfinished. Between frames the app sleeps. Drawing commands carry hashes:\nan unchanged frame is skipped, and a changed one redraws only the bands\nthat changed. A minimized window draws nothing at all (`ui.hidden` :\nits frames and timers go on, so it can read less often).\n- **Input, the same everywhere.** Mouse: click, double-click, the wheel\n(Shift for sideways, Ctrl to zoom where it makes sense), drag, the right\nbutton for menus, the middle and side buttons. Keyboard: Tab and\nShift+Tab move the focus (shown as the dotted 3.1 rectangle), Space and\nEnter activate, arrows/Home/End/PageUp/PageDown move, Esc closes,\nAlt+letter for`&` mnemonics, the menu key or Shift+F10 for context\nmenus. Fingers: a tap activates (a drag cancels it), dragging scrolls\nlists and pages, a long press is the right click, and a held-then-moved\nfinger drags items. Hover effects appear only for a real mouse.\n- **Looks.** The 3.1 look (bevels, X check boxes, navy selections, group\nboxes, bold menus) in eight colour schemes (`builtinThemes` : Classic,\nGray, Dark, Ocean, Desert, Plum, Hot Dog, Paper), or your own`Theme` (`ui.theme = Dark` ).\nText is FreeSans (the default), FreeSerif or FreeMono -- GNU FreeFont,\nbuilt in, each in its four styles, Arabic everywhere -- or a font file\n(`setUiFont` ,`loadUiFontFile` ); icons are\nthe 3.1-style pixel icons or the Nerd Fonts symbols.\n- **Sizes.** Layout uses design pixels that follow the screen's density\n(Xft.dpi, GDK_SCALE, the monitor's real size, Android's density, Windows\nper-monitor DPI), in whole pixels so lines stay sharp. Users can make\neverything larger (Ctrl + / − / 0,`setUiScale` ) or just the text\n(`setTextScale` ). Touch screens get finger-sized metrics.\n- **Content larger than its place scrolls** , always with the standard 3.1\nscroll bar (on touch screens too, where a finger can also drag the\ncontent): the window's page (both ways), dialogs, panes, lists, grids,\nMDI windows, the details pane.\n\nThe full catalogue, with every signature, a usage example and pictures of\neach state, is **[docs/controls.md](https://github.com/foxoman/retroui/blob/main/docs/controls.md)**. In short:\n\n| Group | Controls | \n|---|---|\n| Text | `label` ,`paragraph` ,`heading` ,`styledText` ,`link` ,`badge` ,`icon` ,`iconLabel` ,`tooltip` | \n| Buttons | `button` (also with a picture: icon only, text only, text below or beside the icon --`ButtonLook` ),`barButton` (tool bars;`setToolbarLook` ),`buttonAt` ,`toolButton` ,`menuButton` ,`splitButton` ,`segmented` ,`buttonRow` | \n| Choices | `checkbox` ,`radio` ,`toggle` (3.1 slide switch),`chips` ,`tagInput` ,`rating` ,`knob` | \n| Text input | `edit` ,`editArea` ,`searchBox` ,`autocomplete` ,`maskedEdit` ,`comboEdit` ,`hotkeyEdit` | \n| Numbers, dates, colours | `spin` ,`intEdit` ,`numberEdit` ,`slider` ,`rangeSlider` ,`progress` ,`datePicker` ,`calendar` ,`dateRange` ,`timePicker` ,`colorPicker` | \n| Lists | `listbox` ,`combo` ,`checkList` ,`grid` (with cell kinds),`tree` ,`treeGrid` ,`iconView` ,`lineView` ,`dualList` ,`propertyGrid` | \n| Status | `progressRing` ,`spinner` ,`sparkline` ,`usageBar` ,`banner` ,`toast` ,`led` ,`pill` ,`timeline` ,`emptyState` ,`busyState` ,`statusbar` | \n| Containers | `group` ,`card` ,`tabs` ,`tabStrip` ,`expander` ,`accordionHeader` ,`form` /`field` ,`split` ,`vsplit` ,`sidePane` ,`scrollPanel` ,`adaptive` ,`row` ,`col` | \n| Menus and bars | `menubar` ,`menu` ,`menuItem` ,`submenu` ,`contextMenu` ,`popupMenu` ,`toolbar` ,`statusbar` ,`breadcrumb` ,`pathBar` ,`driveBar` ,`pager` ,`stepper` ,`recordNav` ,`findBar` | \n| Dialogs | `dialog` ,`msgBox` ,`inputBox` ,`progressBox` ,`wizard` ,`aboutBox` ,`fileDialog` (3.1),`filePicker` (modern),`propertiesDialog` | \n| Desktop | `mdiArea` /`mdiWindow` ,`mdiWindowMenu` ,`hotkeyPressed` ,`findIn` ,`replaceAllIn` | \n| App parts | `settingToggle` ,`settingChoice` ,`settingSlider` ,`settingButtons` ,`settingCombo` ,`settingLink` ,`appearanceSettings` ,`avatar` ,`factList` ,`bottomNav` ,`fab` ,`captionBar` | \n| Business views | `chart` (21 kinds),`gauge` ,`kanbanBoard` ,`ganttView` ,`agendaView` ,`kpiTile` ,`statCard` ,`orgChart` ,`reportView` | \n| Files | `fileList` ,`filePreview` ,`folderTree` ,`placesView` ,`trashList` ,`driveBar` ,`pathBar` ,`textFileView` ,`hexFileView` ,`runJobDialog` | \n| Media and more | `mapView` ,`view3d` ,`canvas2d` ,`htmlView` ,`webView` ,`markdownView` ,`imageView` ,`animation` ,`videoView` | \n\nButtons with a picture show it four ways -- icon only (the label becomes the\ntooltip), text only, the text below the icon, or beside it -- and a tool bar\nshows all of its `barButton` s one way, which the app can offer as a setting\n(Explorer 98's \"Text Labels\"):\n\n```\nsetToolbarLook(blTextBelow) # labels under the icons; the bar grows\ntoolbar:\n if barButton(pxBack, \"Back\"): goBack()\n if barButton(pxCopy, \"Copy\", tip = \"Copy (Ctrl+C)\"): copy()\nif button(\"Open\", pxOpen, blTextBeside): openIt()\nif button(\"Save\", glyphPic(nfSave), blIconOnly): saveIt()\n```\n\nDrawing your own: `canvas(w, h)` gives a rectangle to draw into with\n`fill`, `box`, `hline`, `vline`, `line`, `text`, `image`, `drawBitmap`\nand the smooth shapes `disc`, `ring`, `roundRect`, `polygon`,\n`thickLine`, `pieSlice`; `canvas2d` adds the whole HTML5 Canvas API.\n\n```\nrow([120, -1, -2]): # fixed, one share, two shares\n label \"Name:\"\n edit name\n edit notes\nrow:\n label \"Total: 120\"\n spring() # the buttons go to the right end\n button \"OK\"\n button \"Cancel\"\nadaptive(260): # 1 column on a phone, 3 on a desktop\n card \"Sales\": ...\n card \"Stock\": ...\n card \"Orders\": ...\nif isCompact(): ... # sizeClass(): scCompact, scMedium, scExpanded\nlet cols = responsive(1, 2, 3)\n```\n\nWidths in rows, `col(w)`, dialogs and grid columns are design pixels:\nthey grow with the screen and the user's size. `dp(13)` scales your own.\nContent larger than the window scrolls both ways under the fixed menu,\ntool and status bars, always with the standard scroll bars (on touch\nscreens too): the wheel (Shift + the wheel goes sideways), a finger,\nPageUp / PageDown, Ctrl+Home / End, and Tab brings the focused control\ninto view. A dialog taller than the screen scrolls inside; `scrollPanel`\nscrolls a part of a page (`scrollPanel -1:` down to the bottom).\n\n**Smooth scrolling.** Lists, grids, trees, text areas and pages glide a\nshort way per wheel notch or key, follow a finger pixel for pixel and fly\non when it is flicked; a finger landing on a flying list stops it without\npicking an item. `setSmoothScrolling(false)` (or the user, in\n`appearanceSettings`) makes every scroll jump at once. Views of your own\nget the same with `scrollWheel`, `scrollPan`, `scrollTo` / `scrollBy` /\n`scrollShow` and one `scrollTick` a frame.\n\n**Sizes.** The UI follows the display's density: whole pixels keep lines\nsharp (2x, 3x) and the text and controls make up the rest (a 1.33x tablet\ngets 1x lines and 1.33x text). `setUiScale(125)` (and Ctrl + / - / 0, and\nthe phone title bar's menu) scales everything; `setTextScale(120)` only\nthe text (controls grow with it); `setBaseTextSize(14)` changes the 100%\nsize (12 pixels per em on desktops and tablets, 15 on phones).\n[docs/syntax.md](https://github.com/foxoman/retroui/blob/main/docs/syntax.md#widths-in-a-row) shows each kind of width\nwith the pixels it came to. Try layouts on a desktop with `RETRO_SIZE=420x840`, `RETRO_TOUCH=1`,\n`RETRO_CAPTION=1` (the phone title bar), `RETRO_SCALE=150`, `RETRO_ZOOM=2`.\n\n**Controls for a mouse or for fingers.** `setControlSizes` chooses:\n`csAuto` (finger-sized on a phone, desktop-sized on a tablet and a desktop,\nwhose screens hold a desktop layout), `csDesktop` or `csTouch` (finger-sized\neverywhere). The user chooses in Appearance (`appearanceSettings`, Controls),\nkept with the look. `RETRO_TOUCH=1` is a finger on any screen: finger-sized\ncontrols, no hover, tooltips above the finger; `RETRO_CONTROLS=touch`,\n`desktop` or `auto` sets the sizes alone (`retrokit run --touch`,\n`--controls:touch`). Both win over what the user kept.\n\n```\ntext(x, y, \"Plain\", c)\ntext(x, y, \"Big bold\", c, style(bold = true, size = 2.0))\ntext(x, y, \"مرحبا بالعالم\", c) # joined, right to left\nlabel nfFolderOpen & \" Documents\" # an icon inside text\ntoolButton(nfCopy, \"Copy\", size = 1.3)\nimage(x, y, glyphIcon(nfFolder, color(222, 170, 40), 24)) # as an Icon\n```\n\n`TextStyle` has `bold`, `italic` (the font's own italic: FreeSans Oblique,\nnot a slanted copy), `mono` (FreeMono), `serif` (FreeSerif), `underline`,\n`strike`, `size` (times the UI's text size) and `rtl`. `textWidth`, `lineHeight` and\n`FontH` measure. The icon constants (`nfFolder`, `nfCog`, `nfGithub`...,\n`nerdIconNames` lists them all) come from Font Awesome, Material Design,\nSeti and Devicons via Nerd Fonts. Characters in no built-in font (CJK,\nemoji) are drawn by the platform.\n\n**Drawing.** Apps draw into one software framebuffer cut in tiles: only\nthe tiles whose commands changed are drawn (on all cores) and sent, and a\npicture changed in part (`changed(bitmap, rect)`) only there; nothing at\nall when nothing changed. The framebuffer is the window's own memory where\nthe system lends it -- shared with the X server (MIT-SHM) on X11, a DIB\nsection on Windows -- so a frame is never copied on its way to the screen\n(`RETRO_SURFACE=0` copies it, as before 0.26). Where the platform has OpenGL ES 2 / OpenGL 2.1\n(EGL on Linux and Android, WGL on Windows -- loaded at run time, nothing\nto link) the frames are drawn by the GPU instead: the same commands as\nrectangles from textures the CPU makes once (text, icons, shapes),\npictures as textures sent only where they changed. A start-up self-test,\na fall back to the CPU and a guard against a crash at start keep a bad\ndriver from hurting; `setGpuMode(gmAuto/gmGpu/gmCpu)` or \"Drawing\" in\n`appearanceSettings` chooses. The text is drawn at the screen's own\nresolution on every screen; on HD and 4K screens pixel icons are scaled\nwith Scale2x and Scale3x, and small marks are drawn at the screen's\nresolution (`setHdText(false)`: the pixels of 1998, magnified). There is a true-black OLED theme; in it (and in Dark) the pixel icons are\ndrawn as their line twins -- Nerd Fonts symbols in the text's color, crisp\nat any size (`setIconStyle`).\n\n**Big images.** The photo engine (`retroui/photo`) shows a change being made\nwith the mouse -- a layer moved, transformed, adjusted -- before it is done\n(`LivePart`): the view's pixels are composited straight from the layers at\nthe view's size, and the full-size pixels change once, when it is put down\n(`touchWhole` hands the old ones to the undo step without a copy). On a\n70-megapixel photo, dragging a layer costs about 8 ms a frame and Free\nTransform 25 ms.\n\n**The fonts.** Every app's text is **FreeSans** unless it chooses\notherwise: GNU FreeFont's sans (in the manner of Helvetica and Arial),\nbuilt into the app in its regular, bold, oblique and bold oblique.\n`setUiFont(ufSerif)` gives **FreeSerif** (in the manner of Times),\n`setUiFont(ufMono)` **FreeMono** (in the manner of Courier); monospaced\ntext (code blocks, editors, hex) is FreeMono whatever the UI's font, and\nserif families in HTML, on the canvas and in documents are FreeSerif.\nItalic and bold italic are the fonts' own italics, not slanted copies.\n**Arabic is everywhere:** FreeSans has none of its own, so its Arabic --\nin every style -- is FreeSerif's (FreeSerif Bold's in bold text), joined,\nlam-alef as one letter, right to left among Latin text, mirrored brackets;\nFreeMono draws its own in its regular and FreeSerif's in its other styles;\na font of the user's without Arabic gets FreeSerif's the same way. The\nsame holds in text boxes, the rich editor, `htmlView`, the canvas, PDF\nfiles and reports, and in documents (`retroui/textengine`: FreeSerif's\nOpenType tables set the Arabic, as Amiri did before). Characters no\nbuilt-in font has (CJK, emoji) are drawn by the platform.\n\n**Right to left** is the whole Unicode bidirectional algorithm (UAX #9):\nnumbers and brackets, the direction marks, and the explicit embeddings,\noverrides and isolates (U+202A..202E, U+2066..2069) -- every case of\nUnicode's conformance tests passes. The zero width non-joiner and joiner\nsteer the joining (Persian میخواهم) and never cut a word in two; text is\nkept in its letters (joined shapes pasted in, or read from an old PDF,\ncome back as letters: `plainLetters`). In text boxes and the rich editor\nthe caret goes through a line as it reads -- Left goes on in an Arabic\nline, a letter and its vowels are one step, Backspace takes a vowel off\nand Delete a letter with its vowels -- and stands where the next letter\ntyped goes when Latin and Arabic meet; a selection of both is drawn where\nits parts are. PDF files carry Arabic as it is written (`/ActualText`,\nthe letters themselves) and say their language (`lang`); an Arabic\nsheet written to Excel opens right to left (`XlsxSheet.direction`). The\nArabic interface (`setUiLanguage(\"ar\", @toolkitArabic)`) mirrors the\nframe, menus, lists, scroll bars and back and forward arrows; text\nboxes, documents and Markdown keep their own direction, and charts,\nmaps, the media controls (play, the time bar) and pictures their sides.\n\nThe fonts are subsets of GNU FreeFont 0412 made by `tools/genfreefont.py`\nfrom the fonts GNU publishes: Latin (with Latin-1, Extended-A and -B,\nIPA), Greek, Cyrillic, Hebrew, Arabic (FreeSerif, FreeMono), punctuation,\ncurrency, arrows, mathematical operators, box drawing, geometric shapes\nand the symbols the kit's own text uses -- the bold and italic styles the\nletters, their symbols coming from the regular -- with their OpenType\nkerning, marks, ligatures and Arabic forms, without the TrueType hinting.\nThe twelve files take 0.94 MB in every app (compressed, unpacked when a\nface is first used; the fonts before them took 0.96 MB, and apps with\n`retroui/textengine` carried Amiri's 0.21 MB more).\n\n**Crisp at every scale.** Glyphs are drawn by the kit's own TrueType\nengine (`retroui/ttf`), at the screen's own resolution, on the CPU and the\nsame masks on the GPU: the coverage of each pixel computed exactly, in\ngray, the baseline, x-height, cap height and ascender set on whole pixels\nat small sizes (below 26 pixels to the em), the strokes as the font draws\nthem (FreeSans' stems, a little over a pixel at 12, keep their weight),\nletters placed at quarter pixels without drift; FreeMono's thin strokes\n(half a pixel at 12) are darkened to a whole pixel there; small text is\ndrawn with a light gamma (1.2). Lines take the font's own line gap.\n\n**Sharp text** (`setSubpixelText(true)`, or \"Text edges: Sharp\" in\n`appearanceSettings`; `RETRO_TEXT=sharp`) draws the letters in the\nscreen's red, green and blue strips, three times as fine across, as\nWindows' ClearType does, the stems then fitted to the pixels: off by\ndefault on every platform, used on screens of one device pixel per pixel\n(it follows Windows' strip order, RGB or BGR).\n\n`loadUiFontFile(path)` gives a font of the user's (a .ttf, or the first\nface of a .ttc; its bold, italic and bold italic beside it when they are,\n\"X-Bold.ttf\", \"X-Italic.ttf\"...); an app built with\n`-d:retroAppFont=path/X-Regular.ttf` carries its own and starts with it\n(`useAppFont`). Choose before `app` for one app's default, or at any\ntime; `uiFont()` tells which is on; `appearanceSettings` puts the choice\nin an app's Settings -- FreeSans, FreeSerif, FreeMono, a font file -- and\n`storeAppearance` / `restoreAppearance` keep it (a choice stored before\nFreeFont is FreeSans now, a font file stays one). `builtinUiFonts` lists\nthe built-in fonts for a menu of an app's own, `uiFontKey` / `uiFontOfKey`\nname them in its settings (\"sans\", \"serif\", \"mono\"; the words\nof before -- \"w98\", \"kawkab\"... -- still read). The fonts' names of before\ncompile for one release as deprecated aliases: `ufW98`, `ufRetro`,\n`ufSmooth`, `ufOpenSans` are `ufSans`, `ufKawkab`, `ufFixedsys` `ufMono`.\n\n**Licences.** GNU FreeFont is under the GNU GPL v3 or later with the\nfont exception (\"if you create a document which uses this font, and embed\nthis font or unaltered portions of this font into the document, this font\ndoes not by itself cause the resulting document to be covered by the GNU\nGPL\"), `src/retroui/fonts/LICENSE-FreeFont.txt`; the subsets keep that\ntext, and the files GNU publishes (and their FontForge sources) are where\nthe licence says. The rest of the kit is MIT; the icon font is the Nerd\nFonts symbols (MIT and SIL OFL, `src/retroui/fonts/LICENSE-NerdFonts.txt`).\nAn app that hands out its binaries hands out the fonts in it: keep the\nlicence text with it (the About box's credit is `RetroFontCredit`).\n\n**Pixel icons** (`retroui/pixelicons`) are used the same way, as text:\n\n```\ntoolButton(pxCopy, \"Copy\", size = 1.3) # a 3.1-style tool bar icon\niconLabel(pxFolder, \"Documents\")\nimage(x, y, glyphIcon(pxComputer, black, 32)) # the 32x32 art at 32\nlabel retroOr(pxSave, nfSave) & \" Save\" # pixel icon, or the Nerd one\n```\n\nThere are 255 (`pixelIconNames` lists them): folders and places, drives,\nfile kinds, the tool bar's actions, the message box signs, the\nhourglass, charts, maps, mail, calendar, clock, media keys, an image\neditor's tools and panels, and more. Each has 16x16 and 32x32 art and is drawn at a whole number\nof screen pixels per art pixel; disabled ones look embossed. Set\n`retroIcons = false` to have `retroOr` (and the toolkit's own parts) use\nthe Nerd icons. The art is original, drawn in the manner of 3.1, made by\n`tools/genicons.py`.\n\nEvery control tells screen readers what it is, its name, its value and its state as it is drawn: Orca on Linux and BSD (AT-SPI, over D-Bus, which the kit speaks itself), NVDA, JAWS and Narrator on Windows (UI Automation), VoiceOver on macOS and iOS, TalkBack on Android. A label names the control after it, so a form needs nothing more:\n\n```\nrow([70, -1]):\n label \"&Name:\" # read as the text box's name\n edit name\nif button(\"&Save\"): save()\n```\n\nThe screen reader moves the focus, presses buttons and menu items, checks\nboxes, picks list and grid items, tree nodes and calendar days, puts text\nin a box and moves sliders and spin boxes: each comes into the next frame\nas the click or the typing would. The grid is read as a table (its\nheaders, the rows in view, their cells), the tree with each item's depth\nand whether it is open, a chart by its title, kind and series and the\npoint the keys are on. The tree is made only while a screen reader\nlistens; `RETRO_ACCESS=1` makes it without one, to try it.\n\nWhat an app draws itself is not read until it says what it is:\n\n``` js\nlet r = canvas(dp(300), dp(200))\ndrawSales(r)\naccessNode(arImage, \"Sales by month\", id = 0, r = r) # a picture, read by its name\naccessName(\"Delete\") # an icon-only button's name\nif toolButton(nfTrash): deleteIt()\n```\n\n`accessBegin` / `accessEnd` group nodes (a list of your own, its items\n`accessNode(arListItem, ...)` with `accessItem`), `accessRange` gives a\nvalue a range, `accessible()` says whether a screen reader listens. A\ncustom control takes a screen reader's press through `interact`, as a\nclick.\n\n**Input methods.** What the system's input method is composing (pinyin,\nkana, hangul, a phone keyboard's word) is drawn underlined in the text box\nat the caret, and typed when it is settled: XIM on X11, IMM on Windows,\nmarked text on macOS, GTK 4's preedit, the kit's own input connection on\nAndroid. `ui.composing` holds it for a text box of your own.\n\n**Scaling.** The window takes the scale of the screen it is on -- on X11\nthe monitor's DPI (RandR), on Windows and macOS the system's -- and again\nwhen it moves to another monitor; at 125 %, 150 % or 175 % controls and\ntext are the size asked for, and lines stay on whole pixels.\n\n`grid` shows rows that come from a proc, so 100,000 rows cost only what\nthe visible ones cost. Click a header to sort, drag its edge to resize;\narrows, Home, End, PageUp/PageDown; F2, a double click or typing edits an\n`editable` cell, Enter commits, Esc cancels. Pass `marked` for multi-select\n(Ctrl/Shift click, Ctrl+A, a rectangle, check boxes on phones).\n\nColumns can hold more than text — the controls of a business screen:\n\n| Column | Cells show | Interaction | \n|---|---|---|\n| `column` ,`numberColumn` | text, numbers (right aligned) | edited in place when `editable` | \n| `checkColumn` | a check box (\"1\", \"yes\", \"x\"…) | a click or Space flips it: `ev.toggled` | \n| `colorColumn` | a block of colour (\"#RRGGBB\", \"green\", \"orange\"…) | status lights | \n| `progressColumn` | a bar (\"0.62\" or \"62%\") | | \n| `choiceColumn` | text picked from a list | F4 or a click drops the list: `ev.edited` | \n| `buttonColumn` ,`linkColumn` | a push button, a link | `ev.clicked` | \n| `iconColumn` | a pixel icon or icon-font glyph | | \n| `customColumn` | anything you draw in `paint(row, rect, selected)` | | \n\n`style(row, col)` gives any cell its own text and background colours and\nbold text; `rowHeaders` adds the record indicator column (an arrow at the\ncurrent row, a star while it is edited); `footer(col)` adds a totals row.\n\n``` js\nvar cols = @[column(\"Order\", 160), numberColumn(\"Amount\", 90),\n colorColumn(\"Status\"), checkColumn(\"Paid\"),\n choiceColumn(\"Store\", [\"Kitchen\", \"Engineering\"], 110), buttonColumn(\"\", 60)]\nlet ev = grid(cols, orders.len, proc (r, c: int): string = orders[r][c], sel,\n height = -1, rowHeaders = true,\n style = proc (r, c: int): CellStyle =\n if c == 1 and isLate(r): cellStyle(fg = color(200, 0, 0), bold = true)\n else: CellStyle(),\n footer = proc (c: int): string = (if c == 1: total() else: \"\"))\nif ev.edited: orders[ev.row][ev.col] = ev.text # typed, picked or a check box flipped\nif ev.clicked: openOrder(ev.row) # its button\nform 0:\n field \"&Customer:\": comboEdit draft.customer, customers # suggests as you type\n field \"&Phone:\": maskedEdit(draft.phone, \"+### #### ####\")\n field \"&Date:\": datePicker draft.date # Alt+Down or F4 drops it\n field \"&Amount:\": numberEdit draft.amount, lo = 0\n field \"&Period:\": dateRange(fromDay, toDay) # with This month, Last year...\n field \"Status:\": checkbox \"&Paid\", draft.paid\ncase recordNav(pos, customers.len, dirty) # |< < 3 of 20 > >| New Delete Save\nof raNew: addCustomer()\nof raSave: saveCustomer()\nelse: discard\n```\n\n- `maskedEdit` types into a mask (`#` digit,`A` letter,`U` upper case,`X` letter or digit,`*` anything; Arabic-Indic digits count as digits);`maskFormat` ,`maskFull` ,`maskRaw` read the value.\n- `dualList(available, chosen)` moves items between two lists (buttons,\ndouble click, Enter, up/down order).\n- `propertyGrid(props, sel)` edits properties by category: text, numbers,\nyes/no, choices, colours and dates, with a help line.\n- `treeGrid(cols, rows, sel)` is a tree with columns (a chart of accounts).\n- `wizard(open, title, step, steps, width): body` is a dialog of steps\nwith Back / Next / Finish;`stepDone(false)` keeps Next disabled.\n\n`Date` is a plain `(year, month, day)` with `today()`, `addDays`,\n`addMonths`, `weekday`, `parseDate`, `$` in `dateStyle`, `presetRange`.\n`formatNumber` / `parseNumber` read and write \"1,234.50\".\n\n`examples/ledger.nim` puts it together: a tree, a splitter, a sortable,\neditable grid, an invoice form, CSV import and export, reports, settings.\n\n`chart` draws 21 kinds of business chart from the same few lines:\n\n| Kind | | Kind | | \n|---|---|---|---|\n| `chBar` ,`chBarH` | bars, up or sideways | `chScatter` ,`chBubble` | points, sized points | \n| `chStacked` ,`chStacked100` | stacked, as shares | `chWaterfall` | changes adding up to a total | \n| `chLine` ,`chArea` ,`chStackedArea` | lines and areas ( `smooth` ) | `chFunnel` | the stages of a pipeline | \n| `chCombo` | bars with a line on a second axis | `chGauge` (`gauge` ) | one value on a dial, a target, bands | \n| `chPie` ,`chDonut` | shares (the total in the hole) | `chCandle` | open, high, low, close | \n| `chHistogram` | how values spread | `chHeatmap` | a table as colours | \n| `chRadar` | series around the labels | `chTreemap` | shares as rectangles | \n| `chBullet` | values against targets | | | \n\n``` js\nlet months = [\"Jan\", \"Feb\", \"Mar\", \"Apr\"]\nchart(\"Sales\", chBar, months, [series(\"2025\", [12.0, 15, 9, 20]),\n series(\"2026\", [14.0, 18, 11, 24])])\nchart(\"Revenue and margin\", chCombo, months,\n [series(\"Revenue\", rev), lineSeries(\"Margin %\", margin)],\n opts = ChartOpts(format: NumFormat(prefix: \"$\", short: true),\n format2: NumFormat(percent: true)))\ngauge(\"Target\", 0.82, lo = 0, hi = 1, target = 0.9, format = NumFormat(percent: true))\n\n# Straight from a CSV file (comma, semicolon or tab; quotes; a BOM):\nlet t = readCsv(\"sales.csv\")\nlet ev = chart(\"By region\", chDonut, t, \"Region\", [\"Amount\"], height = -1)\nif ev.clicked: showRegion(ev.index) # a bar, point or slice (or Enter)\nexportPng(ui.lastRect, \"chart.png\") # the chart as a picture\ndiscard writeCsv(\"sales-copy.csv\", t) # and a table back to CSV (quoted where needed)\n```\n\nEvery chart has round axis numbers, a legend (click an entry to hide that\nseries), a tooltip (the mouse, a tap, or the arrow keys once it has the\nfocus) and numbers written as money, shares, or 1.2K / 3.4M (`NumFormat`).\n`ChartOpts` sets the titles, axis names, legend place, data labels, axis\nrange, bands and palette. Empty, missing (NaN), negative and huge values\nare drawn as well as they can be, never a crash.\n\n**A chart app in a minute.** `examples/charts.nim` is a ready Chart\nViewer: open a CSV, pick the kind, the label column and the value columns,\nand save the PNG. `retrokit new sales --kind:charts` starts your own.\n\nInvoices, quotes, statements and lists are laid out on pages and come out as PDF files, PNG pictures, an on-screen preview, or paper — all in Nim, with nothing to install, and linked only into apps that use them (PDF alone adds about 45 KB). The fonts are embedded, the text in the PDF can be selected and searched, and Arabic is joined, runs right to left and is copied out of the file as it reads.\n\n**From an HTML template and data** — the way most business apps do it.\nTemplates are Mustache style: `{{name}}` (escaped), `{{{raw}}}`,\n`{{#items}}…{{/items}}` repeats, `{{^items}}` for \"none\", `{{a.b}}`,\n`{{price|n2}}` formats a number:\n\n``` python\nimport retroui, std/json\n\nconst tpl = \"\"\"\nAcme TradingInvoice {{number}}\n\n
Invoice {{number}}
\n
Bill to: {{customer}}
\n
\n
Item
Price
\n{{#items}}
{{name}}
{{price|n2}}
{{/items}}\n
Total
{{total|n2}}
\n
\"\"\"\n\nlet doc = reportFromHtml(renderTemplate(tpl, %*{\"number\": 42, \"date\": $today(),\n \"customer\": \"Sohar Steel\", \"items\": [{\"name\": \"Paper\", \"price\": 45}], \"total\": 45}))\ndoc.savePdf(\"invoice.pdf\") # or: reportView(doc) / printReport(doc) / savePng(doc, 0, \"p1.png\")\n```\n\nThe HTML it reads: `h1`–` h4`, `p`, `div`, `br`, `hr`, `pre`, lists, `b`,\n`i`, `u`, `code`, `small`, links, `span` / `font` with colour, weight,\nstyle and size, tables (`thead`, `tfoot` for totals, `th`, `td`,\n`colspan`, `width`, `align`, `bgcolor`; `border=\"1\"` for a grid,\n`class=\"plain\"` for layout), local pictures, `text-align`, `dir=\"rtl\"`,\n`page-break-before`, and `` / `