From 56b0a8e66d4e4915cf5bbbca0ffe9843c824baf5 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:06:15 +0100 Subject: [PATCH 1/8] docs(design): the rest of the design brief, and the design tokens PR #5 was merged before its last commits were pushed, so main has only the brief's first draft. This brings the whole brief (sections 3b to 4f: every board, the code editor, Start, Verify, the common frame, the signature moments, the tokens, the three languages and Settings) with section 4g from PR #6 kept in place, and docs/design/tokens.json, which the Qt frame reads. Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- docs/design/brief.md | 216 ++++++++++++++++- docs/design/tokens.json | 506 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 715 insertions(+), 7 deletions(-) create mode 100644 docs/design/tokens.json diff --git a/docs/design/brief.md b/docs/design/brief.md index fb5f2e7..eba9288 100644 --- a/docs/design/brief.md +++ b/docs/design/brief.md @@ -53,10 +53,18 @@ The owner's reference is Microchip's MPLAB Code Configurator (MCC), its device r - Every change still goes through the core into `board.yaml` and `system.yaml`, shown as a diff before anything is written (specification §5, §6). -**From MCC, still to bring in** (its Pin Manager and Pins view): per-pin *start high*, analog, direction, weak -pull-up, open-drain and interrupt-on-change; and its **pin grid**, functions in rows and pins in columns, each cell a -lock that is free, taken or locked. The first draft's pin and peripheral options are too few: the next round widens -both (owner, 2026-11-12). +**Widened on 2026-11-12, after the owner's feedback on the first draft:** + +- **Pin manager:** every I/O pin with its mode (input, output, analog, alternate), pull, output type, speed, start + level and interrupt edge, each active only where the mode allows it; filters for pins in use, free pins and all + 50; board-wired pins (the LED, the button, the ST-LINK) fixed by the board description. +- **Pin grid,** as in MCC: functions down, the 50 I/O pins across grouped by port, each cell free, assigned, in + conflict, or fixed and locked. A click moves a function to another pin that can carry it; for the ADC it picks + channels. +- **Peripheral forms in sections** (basic, advanced, interrupts and DMA, driver): flow control, filters, triggers, + prescalers, the DMA stream and channel each request uses, interrupt priorities, the EmbLinkRTOS driver class, the + device name and the devices on a bus. Checks such as an ADC clock above 36 MHz, or a button pull-down fighting the + board's pull-up. ## 3a. Configuring the RTOS @@ -84,6 +92,24 @@ both (owner, 2026-11-12). threads at one priority, a timer period that is not a whole number of ticks, no debug descriptor. - In the Debug stage the same graph comes alive: threads light up as they run, queues fill and drain. +## 3b. Every board, every chip + +EmbLink Studio supports every board EmbLinkRTOS describes: 12 boards of 7 families today, from an 8-bit AVR to +simulated boards with no pins. **No screen is designed for one chip.** The mockups show the NUCLEO-F446RE only as an +example; every screen draws from the board's resolved model (`hw.json`), as the specification requires (§4, §6). + +| What changes per chip | How the screens adapt | +| --- | --- | +| The package (`lqfp64`, `lqfp144`, `qfn60`, `pdip28`, none) | The chip is drawn from it: four sides for QFP and QFN (QFN with its pad), two rows for DIP, a ball grid for BGA. A simulated board (MPS2, QEMU) shows its memory map and peripherals instead | +| How a pin gets its function: an AF number per pin (STM32), a function slot per GPIO (RP2350), or fixed by the peripheral (AVR) | The pin grid shows `AF7`, `F3`, or a fixed cell that cannot be chosen. Conflicts and moves work the same way for all three | +| The peripherals and what they offer (DMA, PIO, FPU, MPU) | The catalogue is the chip's; forms show only the sections the chip has, so no DMA section on an ATmega | +| The clock tree | Every readout (baud error, SCL, ADC rate) is computed by the core from the chip's clocks, never in the GUI | +| What the kernel supports on the chip | The Kernel page follows the port's `Kconfig` defaults and limits: `tiny` on AVR, reboot on fault, no debug descriptor | + +A board is chosen when a project is created (the Start screen), and the board pill in the toolbar shows and changes +it for an open project. A board the views do not cover fully still opens: what they cannot show is listed read-only +with its source (specification §1). + ## 4. A complete debugger Everything a professional embedded developer expects, plus what only an RTOS-aware tool can show: @@ -98,6 +124,180 @@ Everything a professional embedded developer expects, plus what only an RTOS-awa | RTOS | Threads and their states, objects, stacks and high-water marks, the timeline | | Trouble | Fault analyzer, crash-record decoding, SWO/ITM console and trace | +**First draft, 2026-11-12** (artboard "Direction B + C · Debug"), halted at a breakpoint on the NUCLEO-F446RE: + +- the controls in the toolbar (continue, pause, step over, into, out, by instruction, reset, stop) and a status pill + that says why the target stopped: a breakpoint, a step, a watchpoint, a pause; +- the RTOS threads from the debug descriptor, each with its state and stack high-water mark, and the call stack of + the selected one, from its live registers or from the context the kernel saved; +- breakpoints and watchpoints, with the hardware they use (Cortex-M4: 6 FPB comparators, 4 DWT comparators); +- the source with the Thumb-2 disassembly interleaved, the current line and instruction, values shown inline; +- variables: locals, a watch list, and live expressions read over SWD while the target runs; +- core and FPU registers, the ones the last step changed in amber; peripheral registers decoded from the SVD, with + their fields, writable while halted; +- a bottom panel: the console (UART, ITM over SWO, GDB), the RTOS timeline from the trace ring, the kernel objects + live, and the last crash record decoded, linked back to Configure › RTOS; +- a **memory viewer** as an editor tab, like VS Code's hex editor: go to an address or a symbol, the chip's regions + (from the board) and a clickable map of the build's sections and thread stacks, a 16-byte grid as bytes, 16-bit, + 32-bit or float values with ASCII, symbols coloured in place, changed bytes marked, a data inspector that decodes a + pointer to the symbol it points at, writes while halted, and a warning where a read has side effects. + +**Code text uses VS Code's metrics on macOS:** a 12 px monospace font on 18 px lines (owner, 2026-11-12). + +## 4a. The code editor + +First draft, 2026-11-12 (artboard "Direction B + C · Code"). The best of the editors people like, plus what only an +RTOS-aware editor can show: + +| From | What | +| --- | --- | +| VS Code | tabs, breadcrumbs, the minimap with problem marks, peek definition, Problems, Terminal, split editor, its line metrics | +| CLion | inlay hints with parameter names, code lenses above functions, quick fixes | +| Xcode | issues shown at the end of their line, each with its fixes | +| Sublime | one box to go to anything: files, symbols, pins, threads, settings, commands | +| GitLens | change bars in the gutter, blame on the current line | + +Only EmbLink Studio: + +- **Lenses with RTOS facts:** the thread a function runs as, its priority, stack and last high-water mark, its flash + size from the build; an interrupt handler's IRQ, class and priority. +- **Hardware names explained:** `pin_led`, `dev_bme280`, `log_q` or `EXTI15_10_IRQn` open a card with the pin, the bus, + the queue or the IRQ they stand for, where they are defined, and their state on the last run. +- **RTOS checks with fixes:** a blocking call in an interrupt handler (an error, with "use EMB_NO_WAIT"); a call chain + deeper than its thread's stack, from `-fstack-usage` (with "raise the stack in system.yaml"). +- **Completion that knows contexts:** each function says whether it is safe in an interrupt. +- **Generated code read-only,** with a banner pointing to Configure; renaming a generated name sends you to its source. + +### Every part is a panel (owner, 2026-11-12) + +As in VS Code, and further: Explorer, Outline, Source Control, Commits, Problems, Build, Terminal, Serial and +Extensions are each a panel of their own, with their own scroll. Any panel can be dragged by its title, or moved from +its menu, to the left or right side bar, the panel area below, the editor area as a tab, or a floating window. Side +bars stack panels and fold them; the panel area shows them as tabs and can be maximized. The editor splits into +groups, and tabs move between them. Splitters resize everything. Layouts can be saved, with presets (Default, Focus, +Review, Terminal), per project (§3, specification §6). + +**Polish, 2026-11-12 (owner: "elegant, still pro").** Every area is a card with rounded corners on a darker ground, +6 px apart. Panel titles in normal case, actions that brighten on hover, a slim indicator in the activity bar, and a +quiet status bar. Panels, tabs and floating windows are moved by dragging, with docking guides as in Visual Studio: +release on a guide to dock (left, right, panel area, editor tab, split), anywhere else to float. The Explorer has +type icons, folders that fold, indent guides, git colours on names and folders, ignored and generated folders +marked, and a filter. + +### Extensions, Git first + +Features that not every user needs are **extensions**, as in VS Code, so they can be turned off: Git, the language +server, the serial monitor, the trace timeline, the EmbSIM runner. **Git** is built in: stage, unstage, commit with +the DCO sign-off on by default, push, branches, the commit graph, diffs in the editor, change bars and blame. Turning +an extension off removes its panels and its decorations in the editor. + +## 4b. Start + +First draft, 2026-11-12 (artboard "Direction B + C · Start"): + +- **The welcome window:** the app's mark and version, four actions (new project, open, clone from Git, run an + example), the board **connected now** (its probe found on USB) with "new project for this board", recent + projects with their board and last build, and the examples EmbLinkRTOS ships. +- **New project in three steps,** each one shown in a stepper that keeps the choices made: + 1. **Board:** every board EmbLinkRTOS describes, filtered (connected, hardware, simulated) and searched, each + drawn from its package and marked connected, draft (not yet curated), simulated, or not available yet (an + ESP32 whose SoC is not described). + 2. **Template:** empty, blinky, console shell, sensor and logger, SPI device. A template that needs hardware the + board does not describe is shown with what is missing ("this board has no LED the RTOS can drive"). + 3. **Details:** name, location, the EmbLinkRTOS release pinned, the profile from the board's defaults, the + toolchain found or downloaded, git with a signed-off first commit, build right away. +- **Creating** shows each step as the core runs it: the manifests, the pinned RTOS, generation, CMake, git, the + first build and its sizes. Then: open in Configure or Code, or flash and run. +- **A cloned project opens untrusted** (specification §9): its files are shown, nothing in it runs until trusted. + +**Second draft (owner, 2026-11-12: "good ideas, implementation far below the other screens").** Rebuilt to the +standard of Code: each board drawn as it looks (the NUCLEO's white board with its ST-LINK part and blinking LD2, the +Pico 2 W's slim green board, the Uno's teal board, the micro:bit's LED matrix, the ESP32 modules, simulated boards as +blueprints); the connected board as the hero of the welcome window; recent projects grouped by date with their board; +new project as a sheet over the window, with a vendor sidebar, template cards that preview their threads and queues, +a System Settings form beside a live `emb-project.yaml`, and creation shown on the board, whose LED lights when done. + +## 4c. Verify + +First draft, 2026-11-12 (artboard "Direction B + C · Verify"). Verify is where a project gets its evidence, under the +rules EmbLinkRTOS already keeps (`docs/engineering/timing-and-evidence.md`, the support matrix, the HIL records). The +screen never claims more than the evidence supports. + +- **Run on** the board (through its probe) or its emulator (EmbSIM, QEMU), in the checked or release build. **Run + suite** flashes each test image, checks that the flashed image is the one built (`image_sha256` against + `flashed_sha256`), and streams results in as they arrive. +- **Two suites:** EmbLinkRTOS on this board (for the NUCLEO-F446RE: 41 images, 254 cases, grouped as kernel, + interrupts and the port, devices and drivers, faults and crash records, benchmarks) and the project's own tests. +- **Each image** shows its cases with the real outcomes: passed, failed, expected failure, skipped with a reason, + disabled, not run. A failed case shows its message and **Debug this case**, which opens Debug on that image, + stopped where it failed. +- **The support tier** of the board (1 hardware, 2 emulated, 3 described), from the generated matrix, never declared + by the board; the history of archived runs; the other boards in the matrix. +- **Console, Run record and Benchmarks** below: the `hil:` console, the `emb-hil-archive v1` record (board, preset, + build, configuration, git commit, port, flash command, hashes), and benchmarks against FreeRTOS built the same way. +- **What this evidence supports:** each claim marked as supported, qualified or not supported, with its basis. A + benchmark is a measured mean, not a maximum and not a bound; an emulator run is functional evidence only + (SIM-003); worst-case latency needs an established bound before it can be claimed. +- **Archive as evidence** is offered only for a hardware run where everything passed. It files the records + (`tools/hil/archive.py`) and shows the entry added to `hardware-runs.json`. A failing or partial run is kept, + never archived as support. + +## 4d. One frame for every screen + +The polish pass, 2026-11-12. Configure (Hardware, RTOS, Kernel), Code, Debug, Start and Verify now share one frame: + +- **The title bar:** the window controls, the project, the four stages as one segmented control (each a link to + its screen), then what belongs to the stage: the board and Generate and Build on Configure, the debug controls and + the halt state on Debug, the run target on Verify. +- **Cards on a dark ground:** each panel is a rounded card (12 px) on a near-black ground, 6 px apart, as in Code. + Inside a card, groups are a faint fill with hairline separators, the way System Settings groups its rows. +- **The same controls everywhere:** segmented controls, switches with a shadowed knob, status dots, a toast at the + bottom, and one palette for state (cyan for the selection and actions, green passed, amber warning, red error). +- **Configure › Hardware** gains a finer chip, peripheral cards with a colour edge, a legend that selects, a + floating zoom control, peripherals listed with their own tiles, and memory shown as capacity bars. The behaviour + is unchanged: live readouts, conflicts and the fix, the pin manager and the pin grid. +- **Configure › Kernel** moves its search and the Hardware | RTOS | Kernel switch into the header of its centre card. +- **Debug** splits threads, the call stack and breakpoints into cards, puts the editor and the panel in two cards, + and uses segmented tabs for the inspector. + +## 4e. Signature moments + +Owner, 2026-11-12: build all five (artboard "Signature moments"). Motion everywhere lasts 200 to 400 ms, eases +out, and starts where the cause is. + +1. **Hello, board** (Start). Plugging in a board names it and draws it as it looks, before anything is asked. + Identity comes from the probe and the chip's ID code, never a guess. The drawing shows the real board: LD2 in it + follows GPIOA ODR read over SWD. The greeting ends in one next step, "New project for this board". +2. **One click from conflict to fixed** (Configure › Hardware). The conflict glows on the pin and the fix sits + beside it, offered only when valid. The route leaves PA5 and draws itself to PB3; amber turns green only when the + generator accepts the board. +3. **Priority is a place** (Configure › RTOS). Dragging a thread snaps it to real levels (never 0, the idle + level). The ceiling follows its highest user, and checks appear while dragging, each citing its rule. +4. **From a crash to the fix** (Debug, Configure › RTOS, Run). The crash record survives the reset. Every claim + comes from it (CFSR, BFAR, the stack at the fault). The fix links to the exact field, prefilled, never applied + silently, and the next run shows the new high-water mark. +5. **The hardware seal** (Verify). The seal appears only when every test passed on the board and the run is + archived, never from emulation or a partial run. It names the board, the date and the record behind it, and the + matrix is regenerated from the archive. + +Every pin on the chip in Configure › Hardware now carries its name, and clicking a pin or its name opens its row +in the pin table. + +## 4f. Design tokens, languages and Settings + +The visual language is written down as tokens in [`tokens.json`](tokens.json) (artboard "Design tokens", built from +the same file): colour, type, space, radius, size, elevation and motion. The Qt frame reads them; nothing else +defines a colour, a size, a timing or how text is laid out. + +**Three languages (owner, 2026-11-12):** English (the source), French and Simplified Chinese. Chinese text uses +PingFang SC on macOS and a bundled Noto Sans SC on Windows and Linux, after Inter; it breaks between characters and +is never set below 12 px, so the 11 px caption becomes 12 px without capitals. No layout is mirrored. Every visible string comes from a Qt translation file, layouts leave room for text 35% longer than +English, and labels never get a fixed width. Option keys, register, pin and file names, spec references and code are +never translated. Numbers and dates follow the chosen language; hex values never do. + +**Settings is built directly in Qt (owner, 2026-11-12),** from these tokens, without a mockup. The language is one of +its first settings, applied without a restart. + ## 4g. How you move around Artboard "How you move around", 2026-11-12. @@ -133,16 +333,18 @@ walk the selection history; with nothing selected it shows the project. specification chose Widgets for the frame (§11 q2), and the docking library (Qt Advanced Docking System) is Widgets-only. Before deciding, build the same small screen both ways and compare. 2. **Light appearance.** Dark is designed first; a light appearance, as macOS offers, follows the same tokens. -3. **The other screens:** Start, Code, Debug, Verify. +3. **The other screens:** every screen has a draft in the common frame (§4d); the signature moments are drafted (§4e). 4. **Drawing a connection:** dragging from a thread to an object to say who uses it. +5. **The word for IDE plug-ins.** "Module" already means a firmware code package (EmbLinkRTOS-parts, specification §5, + §8). The mockups say **extension** for IDE plug-ins such as Git, to keep the two apart; the owner decides. ## 6. How the design proceeds One step at a time, each decision written here before anything is built: 1. The feeling (§1): done. -2. The signature moments: the 3 to 5 interactions people remember. +2. The signature moments: drafted, five (§4e). 3. How you move around: stages, the command palette, the inspector, the keyboard: drafted (§4g). -4. The visual language, as design tokens (colour, type, spacing, radii, motion) that Qt uses everywhere. +4. The visual language, as design tokens (colour, type, spacing, radii, motion) that Qt uses everywhere: drafted (§4f). 5. The screens, each mocked up and iterated: Configure › Hardware and Configure › RTOS (first drafts done; the layout is liked, the options need widening), then Start, Code, Debug, Verify. diff --git a/docs/design/tokens.json b/docs/design/tokens.json new file mode 100644 index 0000000..d1cbb73 --- /dev/null +++ b/docs/design/tokens.json @@ -0,0 +1,506 @@ +{ + "name": "EmbLink Studio · dark", + "version": 1, + "about": "Design tokens for EmbLink Studio, taken from the mockups in docs/design/brief.md. The Qt frame reads these; nothing else defines a colour, a size, a timing or how text is laid out. Colours are sRGB hex, or rgba() for translucent layers drawn over the ground.", + "color": { + "surface": { + "ground": { + "value": "#111214", + "use": "The window behind every card" + }, + "titlebar": { + "value": "#17181b", + "use": "The title bar" + }, + "card": { + "value": "#1b1c20", + "use": "Side panels, the inspector, the bottom panel" + }, + "work": { + "value": "#18191d", + "use": "The centre card: editor, chip canvas, the run" + }, + "canvas": { + "value": "#15161a", + "use": "Canvases, under a dot grid" + }, + "deep": { + "value": "#111214", + "use": "Code, diffs and records inside a card" + }, + "floating": { + "value": "rgba(40,42,47,.97)", + "use": "Toasts, menus, the command palette" + } + }, + "fill": { + "group": { + "value": "rgba(255,255,255,.035)", + "use": "A group of settings rows inside a card" + }, + "well": { + "value": "rgba(0,0,0,.35)", + "use": "Segmented-control tracks, search fields, inputs" + }, + "readout": { + "value": "rgba(0,0,0,.25)", + "use": "Computed values and their tiles" + }, + "control": { + "value": "rgba(255,255,255,.08)", + "use": "Secondary buttons" + }, + "hover": { + "value": "rgba(255,255,255,.045)", + "use": "A row under the pointer" + }, + "selected": { + "value": "rgba(255,255,255,.075)", + "use": "The selected row" + }, + "segment": { + "value": "#3d3f45", + "use": "The chosen segment of a segmented control" + }, + "segmentInGroup": { + "value": "#4a4c53", + "use": "The chosen segment inside a settings group" + }, + "switchOff": { + "value": "rgba(255,255,255,.14)", + "use": "A switch that is off" + }, + "grid": { + "value": "rgba(255,255,255,.045)", + "use": "Canvas dots, 1 px every 20 px" + } + }, + "line": { + "hairline": { + "value": "rgba(255,255,255,.05)", + "use": "Separators inside a card" + }, + "card": { + "value": "rgba(255,255,255,.06)", + "use": "The edge of a card" + }, + "control": { + "value": "rgba(255,255,255,.07)", + "use": "The edge of an input" + }, + "strong": { + "value": "rgba(255,255,255,.1)", + "use": "Floating surfaces" + } + }, + "text": { + "strong": { + "value": "#ffffff", + "use": "Titles, the chosen segment" + }, + "primary": { + "value": "#e6e7ea", + "use": "Body text" + }, + "body": { + "value": "#d6d8dc", + "use": "Labels in settings rows" + }, + "secondary": { + "value": "#9a9ea7", + "use": "Descriptions, unchosen segments" + }, + "tertiary": { + "value": "#80858e", + "use": "Section captions, metadata" + }, + "quiet": { + "value": "#6f747d", + "use": "Hints, footnotes" + }, + "disabled": { + "value": "#4d5058", + "use": "Disabled text, power pins" + }, + "onAccent": { + "value": "#062430", + "use": "Text on a cyan button" + } + }, + "accent": { + "base": { + "value": "#64d2ff", + "use": "The one action colour: primary buttons, selection, focus" + }, + "link": { + "value": "#7cc4ff", + "use": "Links and quiet actions" + }, + "text": { + "value": "#a8e4fb", + "use": "Text on an accent tint" + }, + "tint": { + "value": "rgba(100,210,255,.14)", + "use": "Accent backgrounds" + } + }, + "state": { + "success": { + "base": "#34c759", + "text": "#7fe3a0", + "tint": "rgba(52,199,89,.14)", + "edge": "rgba(52,199,89,.35)", + "use": "Passed, valid, connected, running" + }, + "warning": { + "base": "#e2b34f", + "text": "#ecc985", + "tint": "rgba(226,179,79,.1)", + "edge": "rgba(226,179,79,.4)", + "use": "A conflict, halted, a check to read" + }, + "danger": { + "base": "#f0736b", + "text": "#f6b4ae", + "tint": "rgba(240,115,107,.1)", + "edge": "rgba(240,115,107,.35)", + "use": "Failed, a fault, a rule broken" + }, + "kernel": { + "base": "#ffd60a", + "text": "#ffe27a", + "tint": "rgba(255,214,10,.14)", + "edge": "rgba(255,214,10,.4)", + "use": "Kernel-owned things: the tick, ceilings, the current line" + } + }, + "peripheral": { + "uart": { + "value": "#64d2ff", + "use": "USART and UART" + }, + "i2c": { + "value": "#bf8cff", + "use": "I2C" + }, + "spi": { + "value": "#ff6482", + "use": "SPI" + }, + "gpioOut": { + "value": "#34c759", + "use": "GPIO outputs, LEDs" + }, + "gpioIn": { + "value": "#66d4cf", + "use": "GPIO inputs, buttons" + }, + "adc": { + "value": "#5e9cff", + "use": "ADC and DAC" + }, + "timer": { + "value": "#ffd60a", + "use": "Timers" + }, + "debug": { + "value": "#98989f", + "use": "SWD, JTAG, trace" + } + }, + "syntax": { + "text": { + "value": "#d9dde3" + }, + "keyword": { + "value": "#c792ea" + }, + "function": { + "value": "#f5c97a" + }, + "type": { + "value": "#8cb4ff" + }, + "macro": { + "value": "#7fd3e8", + "use": "EMB_ names and register fields" + }, + "string": { + "value": "#b5d98c" + }, + "number": { + "value": "#f2a36b" + }, + "comment": { + "value": "#646b77" + } + } + }, + "type": { + "family": { + "ui": { + "value": "Inter", + "fallback": [ + "SF Pro Text", + "system-ui" + ] + }, + "mono": { + "value": "JetBrains Mono", + "fallback": [ + "SF Mono", + "Menlo" + ] + }, + "cjk": { + "value": "PingFang SC", + "fallback": [ + "Noto Sans SC", + "Microsoft YaHei" + ], + "use": "Chinese text, after Inter: PingFang SC on macOS, Noto Sans SC bundled for Windows and Linux. Latin text in a Chinese interface stays in Inter." + } + }, + "scale": { + "display": { + "size": 24, + "line": 30, + "weight": 800, + "tracking": "-0.01em", + "use": "A board's name on Start" + }, + "title1": { + "size": 22, + "line": 28, + "weight": 700, + "tracking": "-0.01em", + "use": "A settings page" + }, + "title2": { + "size": 18, + "line": 24, + "weight": 700, + "tracking": "-0.01em", + "use": "The inspector's subject, a run" + }, + "title3": { + "size": 15, + "line": 21, + "weight": 700, + "use": "A card's title" + }, + "body": { + "size": 13, + "line": 19, + "weight": 400, + "use": "Everything by default" + }, + "bodySmall": { + "size": 12.5, + "line": 18, + "weight": 400, + "use": "Settings labels, banners" + }, + "small": { + "size": 12, + "line": 17, + "weight": 400, + "use": "Descriptions, status bars" + }, + "meta": { + "size": 11.5, + "line": 16, + "weight": 400, + "use": "Second lines in lists" + }, + "caption": { + "size": 11, + "line": 14, + "weight": 600, + "tracking": "0.05em", + "case": "upper", + "use": "Section captions" + }, + "code": { + "size": 12, + "line": 18, + "weight": 400, + "family": "mono", + "use": "Source, disassembly, memory: VS Code's metrics on macOS" + }, + "codeMeta": { + "size": 10.5, + "line": 14, + "weight": 400, + "family": "mono", + "use": "Keys, addresses, pin lines on cards" + }, + "pin": { + "size": 8.5, + "line": 12, + "weight": 400, + "family": "mono", + "use": "Pin names on the chip; 600 when the pin is in use" + } + } + }, + "space": { + "unit": 2, + "scale": [ + 2, + 4, + 6, + 8, + 10, + 12, + 14, + 16, + 20, + 24, + 28 + ], + "gutter": 6, + "cardPadding": [ + 12, + 16 + ], + "use": "Cards sit 6 px apart and 6 px from the window edge" + }, + "radius": { + "segment": 5, + "control": 7, + "button": 8, + "track": 9, + "group": 10, + "card": 12, + "window": 14, + "pill": 999 + }, + "size": { + "titlebar": 50, + "cardHeader": 46, + "editorHeader": 42, + "statusbar": 32, + "row": 32, + "rowCompact": 24, + "control": 26, + "button": 30, + "buttonLarge": 36, + "switch": [ + 36, + 21 + ], + "dot": 7, + "activityBar": 48, + "codeLine": 18 + }, + "elevation": { + "flat": { + "value": "none", + "use": "Cards: an edge, no shadow" + }, + "raised": { + "value": "0 8px 20px rgba(0,0,0,.38)", + "use": "Cards on a canvas" + }, + "selected": { + "value": "0 0 0 4px , 0 14px 30px rgba(0,0,0,.5)", + "use": "The selected card on a canvas" + }, + "floating": { + "value": "0 14px 34px rgba(0,0,0,.5)", + "use": "Toasts, menus" + }, + "window": { + "value": "0 30px 80px rgba(0,0,0,.55)", + "use": "Sheets and windows" + }, + "knob": { + "value": "0 1px 2px rgba(0,0,0,.4)", + "use": "The chosen segment, a switch's knob" + } + }, + "motion": { + "rule": "Motion lasts 200 to 400 ms, eases out, and starts where the cause is. Nothing loops unless it shows something live.", + "hover": { + "duration": 120, + "easing": "linear", + "use": "Row and button hover" + }, + "state": { + "duration": 200, + "easing": "ease-out", + "use": "Colours and fills changing: a switch, a segment, a status" + }, + "enter": { + "duration": 280, + "easing": "ease-out", + "offset": 5, + "use": "Something new appears: it rises 5 px and fades in" + }, + "move": { + "duration": 350, + "easing": "cubic-bezier(.2,.8,.2,1)", + "use": "Something changes place: a thread to a new priority, a zoom" + }, + "draw": { + "duration": 300, + "easing": "ease-out", + "stagger": 280, + "use": "A route draws itself, segment after segment" + }, + "fill": { + "duration": 400, + "easing": "cubic-bezier(.2,.8,.2,1)", + "use": "A bar or ring fills to a new value" + }, + "stamp": { + "duration": 550, + "easing": "cubic-bezier(.2,.8,.2,1)", + "use": "The hardware seal, and nothing else" + }, + "live": { + "duration": 2200, + "easing": "ease-out", + "loop": true, + "use": "A connected board's pulse, a running target" + } + }, + "locale": { + "rule": "The app ships in English, French and Simplified Chinese. Every visible string comes from a Qt translation file (.ts, built with Qt Linguist); none is written into a layout. The language is chosen in Settings and applies without a restart.", + "languages": { + "value": [ + "en", + "fr", + "zh-Hans" + ], + "source": "en", + "use": "English is the source language; French and Simplified Chinese are translations of it." + }, + "expansion": { + "value": 1.35, + "use": "Layouts leave room for text 35% longer than English (French runs longest). Labels never get a fixed width; they wrap or elide, with the full text in a tooltip." + }, + "neverTranslated": { + "value": [ + "option keys (CONFIG_EMB_*)", + "register and field names", + "pin names", + "file names and paths", + "spec references (KRN-SCH-036)", + "code" + ], + "use": "These stay as they are in every language, in the mono family." + }, + "numbers": { + "use": "Numbers, dates and units follow the chosen language (QLocale): 115,200 or 115 200. Hex values and addresses never change." + }, + "chinese": { + "lineBreak": "Chinese breaks between characters, not at spaces; Qt's text layout does this when the locale is zh-Hans.", + "size": "Chinese text uses the same sizes as Latin text, never smaller than 12 px: the 11 px caption becomes 12 px, without capitals or letter spacing.", + "punctuation": "Full-width punctuation (,。:) inside Chinese sentences; technical names inside them keep their own form.", + "use": "Chinese labels are usually shorter than English, so the room left for French covers them. Chinese reads left to right: no layout is mirrored." + } + } +} From 0546fa2045e598f042a1878891d3d7b62c6e1890 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:09:33 +0100 Subject: [PATCH 2/8] The frame: design tokens, the stage switch, three languages, Settings The application now wears the frame of the design brief (sections 4d, 4f, 4g). - Theme reads docs/design/tokens.json, built in as :/design/tokens.json, and gives the palette, the fonts, the motions and the style sheets, the docking library's included: every view is a card on the dark ground, 6 px apart. - SegmentedControl, drawn from the tokens, is the stage switch in the stage bar (merged with the title bar on macOS): Configure, Code, Debug, Verify, with Cmd+1 to Cmd+4. The chosen segment slides with the move motion. - The Workbench keeps one layout per stage, across a restart too. - The interface speaks English, French and Simplified Chinese (app/i18n), switched live from Settings without a restart; numbers follow the language. A Chinese interface sets no text below 12 px. - Settings (Cmd+, on macOS, Ctrl+, elsewhere) is built directly in Qt; its first section, General, holds the language. - --language, --stage and --screenshot help take progress pictures. New tests: tst_theme, tst_segmentedcontrol, tst_language, and stage layouts in tst_workbench. Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- CMakeLists.txt | 2 +- app/CMakeLists.txt | 39 ++- app/i18n/emblinkstudio_fr.ts | 158 +++++++++++ app/i18n/emblinkstudio_zh_CN.ts | 158 +++++++++++ app/src/language.cpp | 144 ++++++++++ app/src/language.h | 78 ++++++ app/src/main.cpp | 62 ++++- app/src/mainwindow.cpp | 275 +++++++++++++++---- app/src/mainwindow.h | 68 ++++- app/src/segmentedcontrol.cpp | 240 +++++++++++++++++ app/src/segmentedcontrol.h | 88 ++++++ app/src/settingsdialog.cpp | 129 +++++++++ app/src/settingsdialog.h | 66 +++++ app/src/theme.cpp | 420 +++++++++++++++++++++++++++++ app/src/theme.h | 96 +++++++ app/src/workbench.cpp | 32 +++ app/src/workbench.h | 18 +- app/tests/tst_language.cpp | 160 +++++++++++ app/tests/tst_segmentedcontrol.cpp | 110 ++++++++ app/tests/tst_theme.cpp | 139 ++++++++++ app/tests/tst_workbench.cpp | 47 +++- docs/development.md | 25 +- 22 files changed, 2487 insertions(+), 67 deletions(-) create mode 100644 app/i18n/emblinkstudio_fr.ts create mode 100644 app/i18n/emblinkstudio_zh_CN.ts create mode 100644 app/src/language.cpp create mode 100644 app/src/language.h create mode 100644 app/src/segmentedcontrol.cpp create mode 100644 app/src/segmentedcontrol.h create mode 100644 app/src/settingsdialog.cpp create mode 100644 app/src/settingsdialog.h create mode 100644 app/src/theme.cpp create mode 100644 app/src/theme.h create mode 100644 app/tests/tst_language.cpp create mode 100644 app/tests/tst_segmentedcontrol.cpp create mode 100644 app/tests/tst_theme.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 6e287b1..8861073 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -17,7 +17,7 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON) option(EMBLINK_STUDIO_BUILD_TESTS "Build the Qt tests" ON) # Qt 6.8 LTS is the release target (spec section 9); newer 6.x builds for development. -find_package(Qt6 6.8 REQUIRED COMPONENTS Core Gui Widgets) +find_package(Qt6 6.8 REQUIRED COMPONENTS Core Gui Widgets LinguistTools) qt_standard_project_setup() # The Python that runs the core during development (spec section 11, question 4). diff --git a/app/CMakeLists.txt b/app/CMakeLists.txt index dca9d56..9f942a1 100644 --- a/app/CMakeLists.txt +++ b/app/CMakeLists.txt @@ -4,8 +4,8 @@ # This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. # Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. # -# Build of the desktop: the corelink library, the EmbLinkStudio application, -# its notices resource, and the Qt tests. +# Build of the desktop: the corelink, workbench and frame libraries, the EmbLinkStudio +# application, its notices resource, its translations, and the Qt tests. # The link to the core, shared by the application and its tests. qt_add_library(emblink_studio_corelink STATIC @@ -26,6 +26,20 @@ qt_add_library(emblink_studio_workbench STATIC target_include_directories(emblink_studio_workbench PUBLIC src) target_link_libraries(emblink_studio_workbench PUBLIC Qt6::Widgets ads::qtadvanceddocking-qt6) +# The frame (design brief section 4f): the theme read from the design tokens, the segmented +# control, the interface language and Settings. The tokens file in docs/design is the only +# source of the look; it is built in as :/design/tokens.json. +qt_add_library(emblink_studio_ui STATIC + src/theme.cpp src/theme.h + src/segmentedcontrol.cpp src/segmentedcontrol.h + src/language.cpp src/language.h + src/settingsdialog.cpp src/settingsdialog.h +) +target_include_directories(emblink_studio_ui PUBLIC src) +target_link_libraries(emblink_studio_ui PUBLIC Qt6::Widgets) +qt_add_resources(emblink_studio_ui design PREFIX "/design" BASE "${PROJECT_SOURCE_DIR}/docs/design" + FILES "${PROJECT_SOURCE_DIR}/docs/design/tokens.json") + # The notices list shown in the About box, generated from third_party/components.json. set(notices "${CMAKE_CURRENT_BINARY_DIR}/NOTICES.md") add_custom_command( @@ -45,7 +59,8 @@ qt_add_executable(emblinkstudio WIN32 MACOSX_BUNDLE src/main.cpp src/mainwindow.cpp src/mainwindow.h ) -target_link_libraries(emblinkstudio PRIVATE emblink_studio_corelink emblink_studio_workbench Qt6::Widgets) +target_link_libraries(emblinkstudio PRIVATE emblink_studio_corelink emblink_studio_workbench + emblink_studio_ui Qt6::Widgets) target_compile_definitions(emblinkstudio PRIVATE EMBLINK_STUDIO_VERSION="${PROJECT_VERSION}") set_source_files_properties("${notices}" PROPERTIES QT_RESOURCE_ALIAS NOTICES.md) qt_add_resources(emblinkstudio notices PREFIX "/" BASE "${CMAKE_CURRENT_BINARY_DIR}" FILES "${notices}") @@ -56,6 +71,16 @@ set_target_properties(emblinkstudio PROPERTIES MACOSX_BUNDLE_SHORT_VERSION_STRING "${PROJECT_VERSION}" ) +# The interface in French and Simplified Chinese (design brief section 4f). English is the +# source. `cmake --build --preset dev --target update_translations` refreshes the .ts files +# from the sources; translate them in Qt Linguist. They are compiled into the frame library. +qt_add_translations(TARGETS emblink_studio_ui + SOURCE_TARGETS emblinkstudio emblink_studio_ui + TS_FILES i18n/emblinkstudio_fr.ts i18n/emblinkstudio_zh_CN.ts + RESOURCE_PREFIX /i18n + LUPDATE_OPTIONS -no-obsolete -locations none +) + if(EMBLINK_STUDIO_BUILD_TESTS) foreach(test tst_framing tst_coreclient) qt_add_executable(${test} tests/${test}.cpp) @@ -68,4 +93,12 @@ if(EMBLINK_STUDIO_BUILD_TESTS) qt_add_executable(tst_workbench tests/tst_workbench.cpp) target_link_libraries(tst_workbench PRIVATE emblink_studio_workbench Qt6::Test) add_test(NAME tst_workbench COMMAND tst_workbench) + + foreach(test tst_theme tst_segmentedcontrol tst_language) + qt_add_executable(${test} tests/${test}.cpp) + target_link_libraries(${test} PRIVATE emblink_studio_ui Qt6::Test) + add_test(NAME ${test} COMMAND ${test}) + endforeach() + target_compile_definitions(tst_theme PRIVATE + EMBLINK_STUDIO_TOKENS="${PROJECT_SOURCE_DIR}/docs/design/tokens.json") endif() diff --git a/app/i18n/emblinkstudio_fr.ts b/app/i18n/emblinkstudio_fr.ts new file mode 100644 index 0000000..e58b6b9 --- /dev/null +++ b/app/i18n/emblinkstudio_fr.ts @@ -0,0 +1,158 @@ + + + + + emblinkstudio::MainWindow + + Connected to %1 %2, protocol %3. + Connecté à %1 %2, protocole %3. + + + EmbLink Studio Core stopped unexpectedly (exit code %1). Views are read-only until it restarts. + EmbLink Studio Core s’est arrêté de façon inattendue (code de sortie %1). Les vues restent en lecture seule jusqu’à son redémarrage. + + + EmbLink Studio + EmbLink Studio + + + No project open + Aucun projet ouvert + + + Configure + Configurer + + + Code + Code + + + Debug + Débogage + + + Verify + Vérification + + + Stage + Étape + + + Core + Core + + + Core log + Journal du Core + + + &Restart the core + &Redémarrer le Core + + + &File + &Fichier + + + &Settings... + &Réglages... + + + &Quit + &Quitter + + + &View + &Affichage + + + &Layouts + &Dispositions + + + &Save layout as... + &Enregistrer la disposition sous... + + + &Reset layout + &Rétablir la disposition + + + &Help + &Aide + + + &About EmbLink Studio + À &propos d’EmbLink Studio + + + Starting EmbLink Studio Core... + Démarrage d’EmbLink Studio Core... + + + Core starting + Core en démarrage + + + Core connected + Core connecté + + + Core stopped + Core arrêté + + + About EmbLink Studio + À propos d’EmbLink Studio + + + <b>EmbLink Studio</b> %1<br>The development system for EmbLinkRTOS. Licensed under the Apache License 2.0. + <b>EmbLink Studio</b> %1<br>Le système de développement d’EmbLinkRTOS. Sous licence Apache 2.0. + + + The notices list is missing. + La liste des mentions légales est absente. + + + No saved layouts + Aucune disposition enregistrée + + + &Delete + &Supprimer + + + Save layout + Enregistrer la disposition + + + Name of this layout, such as Debug: + Nom de cette disposition, par exemple Débogage : + + + + emblinkstudio::SettingsDialog + + Settings + Réglages + + + General + Général + + + &Language + &Langue + + + Applies at once, without a restart. + S’applique tout de suite, sans redémarrage. + + + Option keys, pin and register names, file names and code stay as they are in every language. + Les clés d’option, les noms de broches et de registres, les noms de fichiers et le code restent tels quels dans toutes les langues. + + + diff --git a/app/i18n/emblinkstudio_zh_CN.ts b/app/i18n/emblinkstudio_zh_CN.ts new file mode 100644 index 0000000..51cca50 --- /dev/null +++ b/app/i18n/emblinkstudio_zh_CN.ts @@ -0,0 +1,158 @@ + + + + + emblinkstudio::MainWindow + + Connected to %1 %2, protocol %3. + 已连接到 %1 %2,协议 %3。 + + + EmbLink Studio Core stopped unexpectedly (exit code %1). Views are read-only until it restarts. + EmbLink Studio Core 意外停止(退出代码 %1)。在它重新启动之前,视图为只读。 + + + EmbLink Studio + EmbLink Studio + + + No project open + 未打开项目 + + + Configure + 配置 + + + Code + 代码 + + + Debug + 调试 + + + Verify + 验证 + + + Stage + 阶段 + + + Core + Core + + + Core log + Core 日志 + + + &Restart the core + 重新启动 Core(&R) + + + &File + 文件(&F) + + + &Settings... + 设置(&S)... + + + &Quit + 退出(&Q) + + + &View + 视图(&V) + + + &Layouts + 布局(&L) + + + &Save layout as... + 布局另存为(&S)... + + + &Reset layout + 重置布局(&R) + + + &Help + 帮助(&H) + + + &About EmbLink Studio + 关于 EmbLink Studio(&A) + + + Starting EmbLink Studio Core... + 正在启动 EmbLink Studio Core... + + + Core starting + Core 正在启动 + + + Core connected + Core 已连接 + + + Core stopped + Core 已停止 + + + About EmbLink Studio + 关于 EmbLink Studio + + + <b>EmbLink Studio</b> %1<br>The development system for EmbLinkRTOS. Licensed under the Apache License 2.0. + <b>EmbLink Studio</b> %1<br>EmbLinkRTOS 的开发系统。采用 Apache License 2.0 许可。 + + + The notices list is missing. + 缺少第三方声明列表。 + + + No saved layouts + 没有已保存的布局 + + + &Delete + 删除(&D) + + + Save layout + 保存布局 + + + Name of this layout, such as Debug: + 此布局的名称,例如“调试”: + + + + emblinkstudio::SettingsDialog + + Settings + 设置 + + + General + 通用 + + + &Language + 语言(&L) + + + Applies at once, without a restart. + 立即生效,无需重启。 + + + Option keys, pin and register names, file names and code stay as they are in every language. + 选项键、引脚和寄存器名称、文件名和代码在所有语言中保持原样。 + + + diff --git a/app/src/language.cpp b/app/src/language.cpp new file mode 100644 index 0000000..4468feb --- /dev/null +++ b/app/src/language.cpp @@ -0,0 +1,144 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file language.cpp + * @brief Implementation of Language: loading, swapping and saving the translation. + * + * @details + * Two translators are installed for a language other than English: EmbLink Studio's + * own (:/i18n/emblinkstudio_.qm) and Qt's, for the texts of Qt's standard + * dialogs and buttons, when Qt's translations are installed beside Qt. Only the first + * is required; without Qt's, standard buttons stay in English. + * + * @see language.h + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#include "language.h" + +#include +#include +#include +#include +#include + +namespace emblinkstudio +{ + +namespace +{ + +const QString kSettingsKey = QStringLiteral("general/language"); + +QLocale localeFor(const QString &code) +{ + if (code == QStringLiteral("zh_CN")) + return QLocale(QLocale::Chinese, QLocale::SimplifiedHanScript, QLocale::China); + if (code == QStringLiteral("fr")) + return QLocale(QLocale::French, QLocale::France); + return QLocale(QLocale::English, QLocale::UnitedStates); +} + +} // namespace + +Language::Language(QObject *parent) : QObject(parent), m_current(QStringLiteral("en")) +{ +} + +Language::~Language() +{ + if (m_app) + QCoreApplication::removeTranslator(m_app); + if (m_qt) + QCoreApplication::removeTranslator(m_qt); +} + +QStringList Language::codes() +{ + return {QStringLiteral("en"), QStringLiteral("fr"), QStringLiteral("zh_CN")}; +} + +QString Language::nativeName(const QString &code) +{ + if (code == QStringLiteral("fr")) + return QStringLiteral("Français"); + if (code == QStringLiteral("zh_CN")) + return QStringLiteral("简体中文"); + return QStringLiteral("English"); +} + +QString Language::bestFor(const QLocale &locale) +{ + if (locale.language() == QLocale::French) + return QStringLiteral("fr"); + // Simplified Chinese is the only Chinese shipped; a Traditional script falls back to English. + if (locale.language() == QLocale::Chinese && locale.script() != QLocale::TraditionalHanScript) + return QStringLiteral("zh_CN"); + return QStringLiteral("en"); +} + +bool Language::set(const QString &code) +{ + if (!codes().contains(code)) + return false; + + QTranslator *app = nullptr; + QTranslator *qt = nullptr; + if (code != QStringLiteral("en")) { + app = new QTranslator(this); + if (!app->load(QStringLiteral(":/i18n/emblinkstudio_%1.qm").arg(code))) { + delete app; + return false; + } + qt = new QTranslator(this); + if (!qt->load(localeFor(code), QStringLiteral("qtbase"), QStringLiteral("_"), + QLibraryInfo::path(QLibraryInfo::TranslationsPath))) { + delete qt; + qt = nullptr; + } + } + + if (m_app) { + QCoreApplication::removeTranslator(m_app); + delete m_app; + } + if (m_qt) { + QCoreApplication::removeTranslator(m_qt); + delete m_qt; + } + m_app = app; + m_qt = qt; + QLocale::setDefault(localeFor(code)); + if (m_qt) + QCoreApplication::installTranslator(m_qt); + if (m_app) + QCoreApplication::installTranslator(m_app); + + const bool changedCode = code != m_current; + m_current = code; + if (changedCode) + emit changed(code); + return true; +} + +void Language::restore() +{ + QSettings settings; + const QString saved = settings.value(kSettingsKey).toString(); + if (!saved.isEmpty() && set(saved)) + return; + set(bestFor(QLocale::system())); +} + +void Language::save() const +{ + QSettings settings; + settings.setValue(kSettingsKey, m_current); +} + +} // namespace emblinkstudio diff --git a/app/src/language.h b/app/src/language.h new file mode 100644 index 0000000..5719a71 --- /dev/null +++ b/app/src/language.h @@ -0,0 +1,78 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file language.h + * @brief Language: the interface language, chosen in Settings and applied at once. + * + * @details + * EmbLink Studio speaks English (the source language), French and Simplified Chinese + * (design brief section 4f). Every visible string goes through tr(); the translations + * are Qt Linguist files in app/i18n, compiled into the application under :/i18n. + * + * set() swaps the installed translator and the default locale without a restart: + * Qt then sends every widget a LanguageChange event, and each window retranslates its + * own texts. Numbers and dates follow the language through QLocale; hex values, option + * keys, pin and register names are never translated. + * + * The choice is kept in the user's settings under general/language. With no choice + * yet, the system's language is used when it is one of the three, English otherwise. + * + * @see docs/design/tokens.json ("locale"), app/i18n + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#pragma once + +#include +#include +#include + +class QLocale; +class QTranslator; + +namespace emblinkstudio +{ + +class Language : public QObject +{ + Q_OBJECT + + public: + explicit Language(QObject *parent = nullptr); + ~Language() override; + + // "en", "fr", "zh_CN": the languages the interface ships in, English first. + static QStringList codes(); + // The language's own name, as the language menu shows it: "Français", "简体中文". + static QString nativeName(const QString &code); + // The supported language closest to `locale`; "en" when none is close. + static QString bestFor(const QLocale &locale); + + QString current() const + { + return m_current; + } + + // Applies `code` at once; false, and nothing changed, if it is not supported or its + // translation cannot be loaded. + bool set(const QString &code); + // Applies the saved choice, or the system's language when nothing is saved. + void restore(); + // Saves the current choice in the user's settings. + void save() const; + + signals: + void changed(const QString &code); + + private: + QString m_current; + QTranslator *m_app = nullptr; + QTranslator *m_qt = nullptr; +}; + +} // namespace emblinkstudio diff --git a/app/src/main.cpp b/app/src/main.cpp index 9f72ad9..c13b3b8 100644 --- a/app/src/main.cpp +++ b/app/src/main.cpp @@ -10,17 +10,28 @@ * * @details * Sets the application name, organization and version (EMBLINK_STUDIO_VERSION, - * defined by CMake from the project version), then shows MainWindow, which starts - * EmbLink Studio Core. + * defined by CMake from the project version), applies the interface language, then + * installs the theme from the built-in design tokens and shows MainWindow, which + * starts EmbLink Studio Core. The language comes first, so the theme's fonts follow + * its rules (no Chinese text below 12 px). * - * @see mainwindow.h + * Options, for development and for the pictures in progress-screenshots/: + * --language use this language for this run, without saving it + * --stage open on this stage + * --screenshot save a picture of the window to , then quit + * + * @see mainwindow.h, theme.h, language.h * @author Junior Deogracias * @date 2026-11-11 (created) */ +#include "language.h" #include "mainwindow.h" +#include "theme.h" #include +#include +#include int main(int argc, char *argv[]) { @@ -29,7 +40,50 @@ int main(int argc, char *argv[]) QApplication::setOrganizationName(QStringLiteral("EmbLink")); QApplication::setApplicationVersion(QStringLiteral(EMBLINK_STUDIO_VERSION)); - emblinkstudio::MainWindow window; + QCommandLineParser parser; + parser.addHelpOption(); + parser.addVersionOption(); + const QCommandLineOption languageOption( + QStringLiteral("language"), QStringLiteral("Use for this run: en, fr or zh_CN."), + QStringLiteral("code")); + const QCommandLineOption stageOption( + QStringLiteral("stage"), QStringLiteral("Open on : configure, code, debug, verify."), + QStringLiteral("stage")); + const QCommandLineOption screenshotOption( + QStringLiteral("screenshot"), + QStringLiteral("Save a picture of the window to , then quit."), + QStringLiteral("file")); + parser.addOptions({languageOption, stageOption, screenshotOption}); + parser.process(app); + + emblinkstudio::Language language(&app); + language.restore(); + if (parser.isSet(languageOption) && !language.set(parser.value(languageOption))) + qWarning("Unknown language %s", qPrintable(parser.value(languageOption))); + + emblinkstudio::Theme theme; + QString error; + if (!theme.load(emblinkstudio::Theme::defaultPath(), &error)) + qFatal("The design tokens are missing: %s", qPrintable(error)); + emblinkstudio::Theme::install(theme, app); + // A Chinese interface sets no text below 12 px: the fonts follow the language. + QObject::connect(&language, &emblinkstudio::Language::changed, &app, [&app] { + app.setFont(emblinkstudio::Theme::current().font(QStringLiteral("body"))); + }); + + emblinkstudio::MainWindow window(&language); + if (parser.isSet(stageOption)) + window.setStage(parser.value(stageOption)); window.show(); + + if (parser.isSet(screenshotOption)) { + const QString file = parser.value(screenshotOption); + // Long enough for the core to answer and the stage switch to settle. + QTimer::singleShot(1500, &window, [&window, &app, file] { + if (!window.grab().save(file)) + qWarning("Cannot save %s", qPrintable(file)); + app.exit(0); + }); + } return app.exec(); } diff --git a/app/src/mainwindow.cpp b/app/src/mainwindow.cpp index 1eacb63..3a56d2e 100644 --- a/app/src/mainwindow.cpp +++ b/app/src/mainwindow.cpp @@ -6,26 +6,35 @@ /** * @file mainwindow.cpp - * @brief Implementation of MainWindow: layout, menus, About dialog, core lifecycle. + * @brief Implementation of MainWindow: the stage bar, menus, Settings, About, the core. * * @details - * Builds two Workbench views, "Core" (the status label and the restart button) and - * "Core log", and the File, View and Help menus. The View menu shows or hides each - * view, opens and saves named layouts, and resets the layout. The layout is saved to - * the user's settings when the window closes and restored when it opens (per project - * in .emblink-studio/ once projects exist, spec section 6). The About dialog shows the third-party - * notices bundled as the - * :/NOTICES.md resource. The core is started when the window is built and stopped - * when it closes. + * Builds the stage bar (the project, the stage switch, the core's state), two + * Workbench views, "Core" (the status and the restart button) and "Core log", and the + * File, View and Help menus. The View menu holds the four stages with their shortcuts, + * shows or hides each view, opens and saves named layouts, and resets the layout. + * The layout and the stage are saved to the user's settings when the window closes and + * restored when it opens (per project in .emblink-studio/ once projects exist, spec + * section 6). The About dialog shows the third-party notices bundled as the + * :/NOTICES.md resource. The core is started when the window is built and stopped when + * it closes. + * + * Texts that depend on the core's state are kept as functions, so a language change + * rewrites them in the new language rather than leaving the old one on screen. * * @see mainwindow.h * @author Junior Deogracias * @date 2026-11-11 (created) */ +#include "language.h" #include "mainwindow.h" +#include "segmentedcontrol.h" +#include "settingsdialog.h" +#include "theme.h" #include "workbench.h" +#include #include #include #include @@ -39,24 +48,51 @@ #include #include #include +#include #include namespace emblinkstudio { -MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) +namespace { - setWindowTitle(tr("EmbLink Studio")); - resize(960, 600); + +QString dot(const QColor &color) +{ + return QStringLiteral("●").arg(color.name()); +} + +} // namespace + +QStringList MainWindow::stageIds() +{ + return {QStringLiteral("configure"), QStringLiteral("code"), QStringLiteral("debug"), + QStringLiteral("verify")}; +} + +MainWindow::MainWindow(Language *language, QWidget *parent) + : QMainWindow(parent), m_language(language) +{ + resize(1280, 800); + setUnifiedTitleAndToolBarOnMac(true); m_workbench = new Workbench(this); + const Theme &theme = Theme::current(); + const int gutter = int(theme.number(QStringLiteral("space.gutter"))); + m_workbench->manager()->setStyleSheet(theme.dockStyleSheet()); + m_workbench->manager()->setContentsMargins(gutter, gutter, gutter, gutter); auto *coreView = new QWidget; + // A view's own background is the card's (theme: QWidget#viewContent). + coreView->setObjectName(QStringLiteral("viewContent")); + coreView->setAttribute(Qt::WA_StyledBackground, true); auto *layout = new QVBoxLayout(coreView); + layout->setContentsMargins(16, 14, 16, 14); m_status = new QLabel(coreView); m_status->setTextInteractionFlags(Qt::TextSelectableByMouse | Qt::TextSelectableByKeyboard); m_status->setWordWrap(true); - m_restart = new QPushButton(tr("&Restart the core"), coreView); + m_restart = new QPushButton(coreView); + m_restart->setProperty("role", QStringLiteral("primary")); m_restart->setVisible(false); layout->addWidget(m_status); layout->addWidget(m_restart, 0, Qt::AlignLeft); @@ -65,64 +101,211 @@ MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) m_log = new QPlainTextEdit; m_log->setReadOnly(true); m_log->setMaximumBlockCount(5000); + m_log->setFont(theme.font(QStringLiteral("code"))); // The ids name the views in saved layouts: keep them stable. - m_workbench->addView(QStringLiteral("core"), tr("Core"), coreView, ads::CenterDockWidgetArea); - m_workbench->addView(QStringLiteral("coreLog"), tr("Core log"), m_log, - ads::BottomDockWidgetArea); + m_workbench->addView(QStringLiteral("core"), QString(), coreView, ads::CenterDockWidgetArea); + m_workbench->addView(QStringLiteral("coreLog"), QString(), m_log, ads::BottomDockWidgetArea); m_workbench->captureDefaultLayout(); + + buildStageBar(); + buildMenus(); + + connect(m_workbench, &Workbench::stageChanged, this, + [this](const QString &id) { m_stages->setCurrentIndex(int(stageIds().indexOf(id))); }); { QSettings settings; settings.beginGroup(QStringLiteral("layout")); m_workbench->restore(settings); } - - QMenu *file = menuBar()->addMenu(tr("&File")); - file->addAction(tr("&Quit"), QKeySequence::Quit, this, &QWidget::close); - QMenu *view = menuBar()->addMenu(tr("&View")); - for (ads::CDockWidget *v : m_workbench->views()) - view->addAction(v->toggleViewAction()); - view->addSeparator(); - m_layouts = view->addMenu(tr("&Layouts")); - connect(m_layouts, &QMenu::aboutToShow, this, &MainWindow::fillLayoutsMenu); - view->addAction(tr("&Save layout as..."), this, &MainWindow::saveLayoutAs); - view->addAction(tr("&Reset layout"), m_workbench, &Workbench::resetLayout); - QMenu *help = menuBar()->addMenu(tr("&Help")); - help->addAction(tr("&About EmbLink Studio"), this, &MainWindow::showAbout); + if (m_workbench->stage().isEmpty()) + m_workbench->setStage(stageIds().first()); connect(m_restart, &QPushButton::clicked, this, &MainWindow::startCore); connect(&m_core, &CoreClient::logLine, m_log, &QPlainTextEdit::appendPlainText); connect(&m_core, &CoreClient::ready, this, [this](const QJsonObject &info) { const QJsonObject server = info.value(QStringLiteral("server")).toObject(); - setStatus(tr("Connected to %1 %2, protocol %3.") - .arg(server.value(QStringLiteral("name")).toString(), - server.value(QStringLiteral("version")).toString(), - info.value(QStringLiteral("protocol_version")).toString()), - false); + const QString name = server.value(QStringLiteral("name")).toString(); + const QString version = server.value(QStringLiteral("version")).toString(); + const QString protocol = info.value(QStringLiteral("protocol_version")).toString(); + setStatus( + [=] { return tr("Connected to %1 %2, protocol %3.").arg(name, version, protocol); }, + CoreState::Connected); + }); + connect(&m_core, &CoreClient::failed, this, [this](const QString &message) { + setStatus([=] { return message; }, CoreState::Stopped); }); - connect(&m_core, &CoreClient::failed, this, - [this](const QString &message) { setStatus(message, true); }); connect(&m_core, &CoreClient::exited, this, [this](int code, bool expected) { if (!expected) - setStatus(tr("EmbLink Studio Core stopped unexpectedly (exit code %1). Views are " - "read-only until it restarts.") - .arg(code), - true); + setStatus( + [=] { + return tr("EmbLink Studio Core stopped unexpectedly (exit code %1). Views " + "are read-only until it restarts.") + .arg(code); + }, + CoreState::Stopped); }); + retranslate(); startCore(); } +void MainWindow::buildStageBar() +{ + m_stageBar = new QToolBar(this); + m_stageBar->setObjectName(QStringLiteral("stageBar")); + m_stageBar->setMovable(false); + m_stageBar->setFloatable(false); + m_stageBar->toggleViewAction()->setVisible(false); + addToolBar(Qt::TopToolBarArea, m_stageBar); + + // The window's own controls sit to the left on macOS; keep clear of the edge everywhere. + auto *lead = new QWidget(m_stageBar); + lead->setFixedWidth(8); + m_stageBar->addWidget(lead); + m_project = new QLabel(m_stageBar); + m_project->setObjectName(QStringLiteral("projectName")); + QFont projectFont = Theme::current().font(QStringLiteral("body")); + projectFont.setWeight(QFont::DemiBold); + m_project->setFont(projectFont); + m_stageBar->addWidget(m_project); + + m_stages = new SegmentedControl(m_stageBar); + for (int i = 0; i < int(stageIds().size()); ++i) + m_stages->addSegment(QString()); + m_stageBar->addWidget(m_stages); + connect(m_stages, &SegmentedControl::currentChanged, this, + [this](int index) { m_workbench->setStage(stageIds().value(index)); }); + + auto *spacer = new QWidget(m_stageBar); + spacer->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Preferred); + m_stageBar->addWidget(spacer); + + m_corePill = new QLabel(m_stageBar); + m_corePill->setObjectName(QStringLiteral("corePill")); + m_corePill->setTextFormat(Qt::RichText); + m_stageBar->addWidget(m_corePill); + auto *trail = new QWidget(m_stageBar); + trail->setFixedWidth(8); + m_stageBar->addWidget(trail); +} + +void MainWindow::buildMenus() +{ + m_fileMenu = menuBar()->addMenu(QString()); + m_settingsAction = m_fileMenu->addAction(QString(), this, &MainWindow::showSettings); + m_settingsAction->setShortcut(QKeySequence::Preferences); + m_settingsAction->setMenuRole(QAction::PreferencesRole); + m_fileMenu->addSeparator(); + m_quitAction = m_fileMenu->addAction(QString(), QKeySequence::Quit, this, &QWidget::close); + m_quitAction->setMenuRole(QAction::QuitRole); + + m_viewMenu = menuBar()->addMenu(QString()); + for (int i = 0; i < int(stageIds().size()); ++i) { + // Ctrl is ⌘ on macOS: ⌘1 to ⌘4 (design brief section 4g). + QAction *a = + m_viewMenu->addAction(QString(), this, [this, i] { m_stages->setCurrentIndex(i); }); + a->setShortcut(QKeySequence(Qt::CTRL | Qt::Key(Qt::Key_1 + i))); + m_stageActions.append(a); + } + m_viewMenu->addSeparator(); + for (ads::CDockWidget *v : m_workbench->views()) + m_viewMenu->addAction(v->toggleViewAction()); + m_viewMenu->addSeparator(); + m_layouts = m_viewMenu->addMenu(QString()); + connect(m_layouts, &QMenu::aboutToShow, this, &MainWindow::fillLayoutsMenu); + m_saveLayoutAction = m_viewMenu->addAction(QString(), this, &MainWindow::saveLayoutAs); + m_resetLayoutAction = m_viewMenu->addAction(QString(), m_workbench, &Workbench::resetLayout); + + m_helpMenu = menuBar()->addMenu(QString()); + m_aboutAction = m_helpMenu->addAction(QString(), this, &MainWindow::showAbout); + m_aboutAction->setMenuRole(QAction::AboutRole); +} + +void MainWindow::retranslate() +{ + setWindowTitle(tr("EmbLink Studio")); + m_project->setText(tr("No project open")); + const QStringList stages{tr("Configure"), tr("Code"), tr("Debug"), tr("Verify")}; + for (int i = 0; i < int(stages.size()); ++i) { + m_stages->setSegmentText(i, stages.at(i)); + m_stageActions.at(i)->setText(stages.at(i)); + } + m_stages->setAccessibleName(tr("Stage")); + + const QList views = m_workbench->views(); + views.at(0)->setWindowTitle(tr("Core")); + views.at(1)->setWindowTitle(tr("Core log")); + for (ads::CDockWidget *v : views) + v->toggleViewAction()->setText(v->windowTitle()); + m_restart->setText(tr("&Restart the core")); + + m_fileMenu->setTitle(tr("&File")); + m_settingsAction->setText(tr("&Settings...")); + m_quitAction->setText(tr("&Quit")); + m_viewMenu->setTitle(tr("&View")); + m_layouts->setTitle(tr("&Layouts")); + m_saveLayoutAction->setText(tr("&Save layout as...")); + m_resetLayoutAction->setText(tr("&Reset layout")); + m_helpMenu->setTitle(tr("&Help")); + m_aboutAction->setText(tr("&About EmbLink Studio")); + + setStatus(m_statusText, m_coreState); +} + +void MainWindow::changeEvent(QEvent *event) +{ + if (event->type() == QEvent::LanguageChange) + retranslate(); + QMainWindow::changeEvent(event); +} + +void MainWindow::setStage(const QString &id) +{ + const int index = int(stageIds().indexOf(id)); + if (index >= 0) + m_stages->setCurrentIndex(index); +} + +QString MainWindow::stage() const +{ + return m_workbench->stage(); +} + void MainWindow::startCore() { - setStatus(tr("Starting EmbLink Studio Core..."), false); + setStatus([] { return tr("Starting EmbLink Studio Core..."); }, CoreState::Starting); m_core.start(CoreClient::defaultLaunch()); } -void MainWindow::setStatus(const QString &text, bool canRestart) +void MainWindow::setStatus(std::function text, CoreState state) { - m_status->setText(text); - m_restart->setVisible(canRestart); + m_statusText = std::move(text); + m_coreState = state; + m_status->setText(m_statusText ? m_statusText() : QString()); + m_restart->setVisible(state == CoreState::Stopped); + + const Theme &theme = Theme::current(); + switch (state) { + case CoreState::Starting: + m_corePill->setText(dot(theme.color(QStringLiteral("state.warning.base"))) + + QLatin1Char(' ') + tr("Core starting").toHtmlEscaped()); + break; + case CoreState::Connected: + m_corePill->setText(dot(theme.color(QStringLiteral("state.success.base"))) + + QLatin1Char(' ') + tr("Core connected").toHtmlEscaped()); + break; + case CoreState::Stopped: + m_corePill->setText(dot(theme.color(QStringLiteral("state.danger.base"))) + + QLatin1Char(' ') + tr("Core stopped").toHtmlEscaped()); + break; + } +} + +void MainWindow::showSettings() +{ + SettingsDialog dialog(m_language, this); + dialog.exec(); } void MainWindow::showAbout() @@ -130,8 +313,8 @@ void MainWindow::showAbout() QDialog dialog(this); dialog.setWindowTitle(tr("About EmbLink Studio")); auto *layout = new QVBoxLayout(&dialog); - layout->addWidget(new QLabel(tr("EmbLink Studio %1
The IDE made for EmbLinkRTOS. " - "Licensed under the Apache License 2.0.") + layout->addWidget(new QLabel(tr("EmbLink Studio %1
The development system for " + "EmbLinkRTOS. Licensed under the Apache License 2.0.") .arg(QApplication::applicationVersion()), &dialog)); auto *notices = new QTextBrowser(&dialog); diff --git a/app/src/mainwindow.h b/app/src/mainwindow.h index 736be43..3f6d400 100644 --- a/app/src/mainwindow.h +++ b/app/src/mainwindow.h @@ -6,16 +6,24 @@ /** * @file mainwindow.h - * @brief MainWindow: the main window of EmbLink Studio (stage S0). + * @brief MainWindow: the main window of EmbLink Studio, in the frame of the design brief. * * @details - * Shows whether EmbLink Studio Core is connected, offers a restart when the core - * fails or stops unexpectedly, and shows the core's log. Both are views of the - * Workbench, so they can be moved, split, floated and closed, and the layout is kept - * from one run to the next. The window owns the CoreClient for the life of the - * application. + * The window is the frame every screen shares (design brief section 4d): a stage bar + * at the top, merged with the title bar on macOS, holding the project and the four + * stages (Configure, Code, Debug, Verify) as one segmented control, with ⌘1 to ⌘4 + * (Ctrl elsewhere); and below it the Workbench, where every view is a card. Each stage + * keeps its own layout. * - * @see Spec sections 4 and 7; coreclient.h, workbench.h + * The views so far show whether EmbLink Studio Core is connected, with a restart when + * the core fails or stops unexpectedly, and the core's log. The window owns the + * CoreClient for the life of the application. + * + * Every visible text is set in retranslate(), which runs again when the interface + * language changes, so the window follows a change made in Settings at once. + * + * @see Spec sections 4 and 7; design brief sections 4d, 4f, 4g; + * coreclient.h, workbench.h, segmentedcontrol.h, language.h * @author Junior Deogracias * @date 2026-11-11 (created) */ @@ -24,42 +32,82 @@ #include "coreclient.h" +#include #include +#include +class QAction; class QLabel; class QMenu; class QPlainTextEdit; class QPushButton; +class QToolBar; namespace emblinkstudio { +class Language; +class SegmentedControl; class Workbench; -// S0's window: the core's state, its log, and a restart if it stops (spec section 4). class MainWindow : public QMainWindow { Q_OBJECT public: - explicit MainWindow(QWidget *parent = nullptr); + explicit MainWindow(Language *language, QWidget *parent = nullptr); + + // The stages, in the order of the switch: "configure", "code", "debug", "verify". + static QStringList stageIds(); + void setStage(const QString &id); + QString stage() const; protected: void closeEvent(QCloseEvent *event) override; + void changeEvent(QEvent *event) override; private: + enum class CoreState { + Starting, + Connected, + Stopped + }; + + void buildStageBar(); + void buildMenus(); + void retranslate(); void startCore(); void showAbout(); - void setStatus(const QString &text, bool canRestart); + void showSettings(); + void setStatus(std::function text, CoreState state); void fillLayoutsMenu(); void saveLayoutAs(); + Language *m_language = nullptr; CoreClient m_core; Workbench *m_workbench = nullptr; + + QToolBar *m_stageBar = nullptr; + QLabel *m_project = nullptr; + SegmentedControl *m_stages = nullptr; + QLabel *m_corePill = nullptr; + + QMenu *m_fileMenu = nullptr; + QMenu *m_viewMenu = nullptr; + QMenu *m_helpMenu = nullptr; QMenu *m_layouts = nullptr; + QAction *m_settingsAction = nullptr; + QAction *m_quitAction = nullptr; + QAction *m_saveLayoutAction = nullptr; + QAction *m_resetLayoutAction = nullptr; + QAction *m_aboutAction = nullptr; + QList m_stageActions; + QLabel *m_status = nullptr; QPushButton *m_restart = nullptr; QPlainTextEdit *m_log = nullptr; + std::function m_statusText; + CoreState m_coreState = CoreState::Starting; }; } // namespace emblinkstudio diff --git a/app/src/segmentedcontrol.cpp b/app/src/segmentedcontrol.cpp new file mode 100644 index 0000000..b597887 --- /dev/null +++ b/app/src/segmentedcontrol.cpp @@ -0,0 +1,240 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file segmentedcontrol.cpp + * @brief Implementation of SegmentedControl: layout, painting, the slide, input. + * + * @details + * Segments are as wide as their text plus the token padding, laid out from the left + * inside a 3 px track. The chosen segment's rectangle is animated between the old and + * the new place; while it is not moving, it follows the layout, so a font or text + * change never leaves it behind. + * + * @see segmentedcontrol.h + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#include "segmentedcontrol.h" +#include "theme.h" + +#include +#include +#include +#include +#include +#include +#include + +namespace emblinkstudio +{ + +namespace +{ + +constexpr double kTrackPad = 3.0; // the well around the segments +constexpr double kSegmentPad = 13.0; // either side of a segment's text +constexpr int kSegmentHeight = 26; // in the title bar (tokens: size.control) + +QFont segmentFont() +{ + QFont font = Theme::current().font(QStringLiteral("body")); + font.setWeight(QFont::Medium); + return font; +} + +} // namespace + +SegmentedControl::SegmentedControl(QWidget *parent) : QWidget(parent) +{ + setFocusPolicy(Qt::StrongFocus); + setMouseTracking(true); + setFont(segmentFont()); + setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Fixed); + + m_slide = new QVariantAnimation(this); + m_slide->setDuration(Theme::current().duration(QStringLiteral("move"))); + m_slide->setEasingCurve(Theme::current().easing(QStringLiteral("move"))); + connect(m_slide, &QVariantAnimation::valueChanged, this, [this](const QVariant &value) { + m_knob = value.toRectF(); + update(); + }); +} + +int SegmentedControl::addSegment(const QString &text) +{ + m_texts.append(text); + updateGeometry(); + update(); + if (m_current < 0) + setCurrentIndex(0); + return int(m_texts.size()) - 1; +} + +void SegmentedControl::setSegmentText(int index, const QString &text) +{ + if (index < 0 || index >= count()) + return; + m_texts[index] = text; + updateGeometry(); + update(); +} + +QString SegmentedControl::segmentText(int index) const +{ + return index >= 0 && index < count() ? m_texts.at(index) : QString(); +} + +void SegmentedControl::setCurrentIndex(int index) +{ + if (index < 0 || index >= count() || index == m_current) + return; + const QRectF from = m_current >= 0 ? segmentRect(m_current) : segmentRect(index); + m_current = index; + m_slide->stop(); + if (isVisible()) { + m_slide->setStartValue(m_knob.isNull() ? from : m_knob); + m_slide->setEndValue(segmentRect(index)); + m_slide->start(); + } else { + m_knob = segmentRect(index); + } + update(); + emit currentChanged(index); +} + +double SegmentedControl::segmentWidth(int index) const +{ + return fontMetrics().horizontalAdvance(m_texts.at(index)) + 2 * kSegmentPad; +} + +QRectF SegmentedControl::segmentRect(int index) const +{ + double x = kTrackPad; + for (int i = 0; i < index; ++i) + x += segmentWidth(i); + return QRectF(x, kTrackPad, index < count() ? segmentWidth(index) : 0, + height() - 2 * kTrackPad); +} + +QSize SegmentedControl::sizeHint() const +{ + double w = 2 * kTrackPad; + for (int i = 0; i < count(); ++i) + w += segmentWidth(i); + return QSize(qCeil(w), kSegmentHeight + int(2 * kTrackPad)); +} + +QSize SegmentedControl::minimumSizeHint() const +{ + return sizeHint(); +} + +int SegmentedControl::segmentAt(const QPointF &pos) const +{ + for (int i = 0; i < count(); ++i) + if (segmentRect(i).contains(pos)) + return i; + return -1; +} + +void SegmentedControl::paintEvent(QPaintEvent *) +{ + const Theme &theme = Theme::current(); + QPainter p(this); + p.setRenderHint(QPainter::Antialiasing); + + const double trackRadius = theme.number(QStringLiteral("radius.track")); + const double segRadius = theme.number(QStringLiteral("radius.control")); + QPainterPath track; + track.addRoundedRect(QRectF(rect()), trackRadius, trackRadius); + p.fillPath(track, theme.color(QStringLiteral("fill.well"))); + + if (m_current >= 0) { + if (m_slide->state() != QAbstractAnimation::Running) + m_knob = segmentRect(m_current); + // The knob shadow (tokens: elevation.knob), then the chosen segment. + QPainterPath shadow; + shadow.addRoundedRect(m_knob.translated(0, 1), segRadius, segRadius); + p.fillPath(shadow, QColor(0, 0, 0, 102)); + QPainterPath knob; + knob.addRoundedRect(m_knob, segRadius, segRadius); + p.fillPath(knob, theme.color(QStringLiteral("fill.segment"))); + } + + for (int i = 0; i < count(); ++i) { + const QRectF r = segmentRect(i); + QColor ink = theme.color(QStringLiteral("text.secondary")); + if (i == m_current) + ink = theme.color(QStringLiteral("text.strong")); + else if (i == m_hover) + ink = theme.color(QStringLiteral("text.primary")); + p.setPen(ink); + p.drawText(r, Qt::AlignCenter, m_texts.at(i)); + } + + if (hasFocus() && m_current >= 0) { + QPen ring(theme.color(QStringLiteral("accent.base")), 2); + p.setPen(ring); + p.setBrush(Qt::NoBrush); + p.drawRoundedRect(segmentRect(m_current).adjusted(1, 1, -1, -1), segRadius, segRadius); + } +} + +void SegmentedControl::mousePressEvent(QMouseEvent *event) +{ + if (event->button() == Qt::LeftButton) + setCurrentIndex(segmentAt(event->position())); +} + +void SegmentedControl::mouseMoveEvent(QMouseEvent *event) +{ + const int hover = segmentAt(event->position()); + if (hover != m_hover) { + m_hover = hover; + update(); + } +} + +void SegmentedControl::leaveEvent(QEvent *) +{ + m_hover = -1; + update(); +} + +void SegmentedControl::keyPressEvent(QKeyEvent *event) +{ + switch (event->key()) { + case Qt::Key_Left: + case Qt::Key_Up: + setCurrentIndex(m_current - 1); + break; + case Qt::Key_Right: + case Qt::Key_Down: + setCurrentIndex(m_current + 1); + break; + case Qt::Key_Home: + setCurrentIndex(0); + break; + case Qt::Key_End: + setCurrentIndex(count() - 1); + break; + default: + QWidget::keyPressEvent(event); + } +} + +void SegmentedControl::changeEvent(QEvent *event) +{ + if (event->type() == QEvent::FontChange) + updateGeometry(); + else if (event->type() == QEvent::LanguageChange) + setFont(segmentFont()); // a Chinese interface sets no text below 12 px + QWidget::changeEvent(event); +} + +} // namespace emblinkstudio diff --git a/app/src/segmentedcontrol.h b/app/src/segmentedcontrol.h new file mode 100644 index 0000000..2962914 --- /dev/null +++ b/app/src/segmentedcontrol.h @@ -0,0 +1,88 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file segmentedcontrol.h + * @brief SegmentedControl: a row of choices, one of them chosen, as macOS draws it. + * + * @details + * The stage switch in the title bar (Configure, Code, Debug, Verify) and every + * segmented choice in the frame. It is drawn from the theme's tokens: a well-coloured + * track, the chosen segment raised with the knob shadow, and the chosen segment slides + * to its new place with the "move" motion (design brief section 4f). + * + * The control takes keyboard focus; Left and Right (or Up and Down) choose the + * neighbouring segment, Home and End the first and the last. Segment texts can be + * changed in place, so the control is retranslated without being rebuilt. + * + * @see theme.h; docs/design/tokens.json + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#pragma once + +#include +#include +#include + +class QVariantAnimation; + +namespace emblinkstudio +{ + +class SegmentedControl : public QWidget +{ + Q_OBJECT + Q_PROPERTY(int currentIndex READ currentIndex WRITE setCurrentIndex NOTIFY currentChanged) + + public: + explicit SegmentedControl(QWidget *parent = nullptr); + + int addSegment(const QString &text); + void setSegmentText(int index, const QString &text); + QString segmentText(int index) const; + int count() const + { + return int(m_texts.size()); + } + + int currentIndex() const + { + return m_current; + } + // Chooses `index` and emits currentChanged; out-of-range indexes are ignored. + void setCurrentIndex(int index); + + QSize sizeHint() const override; + QSize minimumSizeHint() const override; + + // The rectangle segment `index` occupies, in widget coordinates. + QRectF segmentRect(int index) const; + + signals: + void currentChanged(int index); + + protected: + void paintEvent(QPaintEvent *event) override; + void mousePressEvent(QMouseEvent *event) override; + void mouseMoveEvent(QMouseEvent *event) override; + void leaveEvent(QEvent *event) override; + void keyPressEvent(QKeyEvent *event) override; + void changeEvent(QEvent *event) override; + + private: + int segmentAt(const QPointF &pos) const; + double segmentWidth(int index) const; + + QStringList m_texts; + int m_current = -1; + int m_hover = -1; + QRectF m_knob; + QVariantAnimation *m_slide = nullptr; +}; + +} // namespace emblinkstudio diff --git a/app/src/settingsdialog.cpp b/app/src/settingsdialog.cpp new file mode 100644 index 0000000..21b5caa --- /dev/null +++ b/app/src/settingsdialog.cpp @@ -0,0 +1,129 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file settingsdialog.cpp + * @brief Implementation of SettingsDialog: the General section and the language. + * + * @details + * The language box lists each language in its own name, so a person can always find + * theirs. Choosing one applies it and saves it at once; the dialog then retranslates + * itself through the LanguageChange event like every other window. + * + * @see settingsdialog.h + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#include "language.h" +#include "settingsdialog.h" +#include "theme.h" + +#include +#include +#include +#include +#include +#include + +namespace emblinkstudio +{ + +SettingsDialog::SettingsDialog(Language *language, QWidget *parent) + : QDialog(parent), m_language(language) +{ + setObjectName(QStringLiteral("settings")); + resize(720, 460); + const Theme &theme = Theme::current(); + const int gutter = int(theme.number(QStringLiteral("space.gutter"))); + + auto *outer = new QHBoxLayout(this); + outer->setContentsMargins(gutter, gutter, gutter, gutter); + outer->setSpacing(gutter); + + // Sections, in a card on the left. + auto *sectionsCard = new QFrame(this); + sectionsCard->setProperty("role", QStringLiteral("card")); + sectionsCard->setFixedWidth(200); + auto *sectionsLayout = new QVBoxLayout(sectionsCard); + sectionsLayout->setContentsMargins(8, 10, 8, 10); + m_sections = new QListWidget(sectionsCard); + m_sections->setObjectName(QStringLiteral("settingsSections")); + m_sections->addItem(QString()); + m_sections->setCurrentRow(0); + sectionsLayout->addWidget(m_sections); + outer->addWidget(sectionsCard); + + // The chosen section, in the work card. + auto *page = new QFrame(this); + page->setProperty("role", QStringLiteral("card")); + auto *pageLayout = new QVBoxLayout(page); + pageLayout->setContentsMargins(26, 22, 26, 22); + pageLayout->setSpacing(10); + m_title = new QLabel(page); + m_title->setFont(theme.font(QStringLiteral("title1"))); + pageLayout->addWidget(m_title); + pageLayout->addSpacing(8); + + auto *group = new QFrame(page); + group->setProperty("role", QStringLiteral("group")); + auto *row = new QHBoxLayout(group); + row->setContentsMargins(12, 8, 12, 8); + auto *labels = new QVBoxLayout; + labels->setSpacing(1); + m_languageLabel = new QLabel(group); + m_languageLabel->setFont(theme.font(QStringLiteral("bodySmall"))); + m_languageHint = new QLabel(group); + m_languageHint->setProperty("role", QStringLiteral("quiet")); + m_languageHint->setFont(theme.font(QStringLiteral("meta"))); + labels->addWidget(m_languageLabel); + labels->addWidget(m_languageHint); + row->addLayout(labels, 1); + m_languageBox = new QComboBox(group); + for (const QString &code : Language::codes()) + m_languageBox->addItem(Language::nativeName(code), code); + m_languageBox->setMinimumWidth(170); + m_languageLabel->setBuddy(m_languageBox); + row->addWidget(m_languageBox); + pageLayout->addWidget(group); + + m_untranslated = new QLabel(page); + m_untranslated->setProperty("role", QStringLiteral("quiet")); + m_untranslated->setFont(theme.font(QStringLiteral("small"))); + m_untranslated->setWordWrap(true); + pageLayout->addWidget(m_untranslated); + pageLayout->addStretch(); + outer->addWidget(page, 1); + + const int index = m_languageBox->findData(m_language->current()); + m_languageBox->setCurrentIndex(index < 0 ? 0 : index); + connect(m_languageBox, &QComboBox::currentIndexChanged, this, [this](int i) { + if (m_language->set(m_languageBox->itemData(i).toString())) + m_language->save(); + }); + + retranslate(); +} + +void SettingsDialog::changeEvent(QEvent *event) +{ + if (event->type() == QEvent::LanguageChange) + retranslate(); + QDialog::changeEvent(event); +} + +void SettingsDialog::retranslate() +{ + setWindowTitle(tr("Settings")); + m_sections->item(0)->setText(tr("General")); + m_title->setText(tr("General")); + m_languageLabel->setText(tr("&Language")); + m_languageHint->setText(tr("Applies at once, without a restart.")); + m_untranslated->setText(tr("Option keys, pin and register names, file names and code stay as " + "they are in every language.")); +} + +} // namespace emblinkstudio diff --git a/app/src/settingsdialog.h b/app/src/settingsdialog.h new file mode 100644 index 0000000..eb0d274 --- /dev/null +++ b/app/src/settingsdialog.h @@ -0,0 +1,66 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file settingsdialog.h + * @brief SettingsDialog: EmbLink Studio's settings, as macOS's System Settings lays them out. + * + * @details + * A list of sections on the left and the chosen section's settings on the right, each + * group of settings a rounded group of rows (design brief section 4f). Settings apply + * as soon as they change; there is no OK or Apply. The first section, General, holds + * the interface language; toolchains, probes, the core's log and shortcuts join it as + * the stages that need them arrive (spec section 7, Settings). + * + * Opened with Settings (⌘, on macOS, Ctrl+, elsewhere), it is built directly in Qt, + * without a mockup (owner, 2026-11-12). + * + * @see language.h; docs/design/brief.md section 4f + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#pragma once + +#include + +class QComboBox; +class QLabel; +class QListWidget; + +namespace emblinkstudio +{ + +class Language; + +class SettingsDialog : public QDialog +{ + Q_OBJECT + + public: + explicit SettingsDialog(Language *language, QWidget *parent = nullptr); + + QComboBox *languageBox() const + { + return m_languageBox; + } + + protected: + void changeEvent(QEvent *event) override; + + private: + void retranslate(); + + Language *m_language = nullptr; + QListWidget *m_sections = nullptr; + QLabel *m_title = nullptr; + QLabel *m_languageLabel = nullptr; + QLabel *m_languageHint = nullptr; + QLabel *m_untranslated = nullptr; + QComboBox *m_languageBox = nullptr; +}; + +} // namespace emblinkstudio diff --git a/app/src/theme.cpp b/app/src/theme.cpp new file mode 100644 index 0000000..3da502f --- /dev/null +++ b/app/src/theme.cpp @@ -0,0 +1,420 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file theme.cpp + * @brief Implementation of Theme: reading the tokens, the palette and the style sheets. + * + * @details + * Tokens are looked up by walking the JSON object; a token is either a bare value or + * an object with a "value" field. Font sizes in the tokens are pixels at the design's + * scale and become point sizes for the screen's logical resolution. The style sheets + * are written from the tokens with colours as #AARRGGBB, which Qt's style sheets read + * for every colour, translucent ones included. + * + * @see theme.h + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#include "theme.h" + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace emblinkstudio +{ + +namespace +{ + +Theme &installed() +{ + static Theme theme; + return theme; +} + +// The value at `path` below `node`; an object with a "value" field stands for that value. +QJsonValue walk(const QJsonObject &root, const QString &group, const QString &path) +{ + QJsonValue node = root.value(group); + for (const QString &part : path.split(QLatin1Char('.'), Qt::SkipEmptyParts)) { + if (!node.isObject()) + return {}; + node = node.toObject().value(part); + } + if (node.isObject() && node.toObject().contains(QStringLiteral("value"))) + return node.toObject().value(QStringLiteral("value")); + return node; +} + +void collectColors(const QJsonObject &node, const QString &prefix, QStringList &out) +{ + for (auto it = node.begin(); it != node.end(); ++it) { + const QString path = prefix.isEmpty() ? it.key() : prefix + QLatin1Char('.') + it.key(); + if (it->isString() && it.key() != QStringLiteral("use")) { + if (!Theme::parseColor(it->toString()).isValid()) + continue; + out.append(path.endsWith(QStringLiteral(".value")) ? path.chopped(6) : path); + } else if (it->isObject()) { + collectColors(it->toObject(), path, out); + } + } +} + +bool chineseInterface() +{ + const QLocale locale; + return locale.language() == QLocale::Chinese; +} + +QString css(const QColor &color) +{ + return color.name(color.alpha() == 255 ? QColor::HexRgb : QColor::HexArgb); +} + +} // namespace + +bool Theme::load(const QString &path, QString *error) +{ + QFile file(path); + if (!file.open(QIODevice::ReadOnly)) { + if (error) + *error = QStringLiteral("cannot open %1").arg(path); + return false; + } + QJsonParseError parse; + const QJsonDocument doc = QJsonDocument::fromJson(file.readAll(), &parse); + if (!doc.isObject()) { + if (error) + *error = QStringLiteral("%1: %2").arg(path, parse.errorString()); + return false; + } + m_root = doc.object(); + return true; +} + +QColor Theme::color(const QString &path) const +{ + return parseColor(walk(m_root, QStringLiteral("color"), path).toString()); +} + +double Theme::number(const QString &path) const +{ + const int dot = path.indexOf(QLatin1Char('.')); + if (dot < 0) + return walk(m_root, path, QString()).toDouble(); + return walk(m_root, path.left(dot), path.mid(dot + 1)).toDouble(); +} + +QFont Theme::font(const QString &style) const +{ + const QJsonObject type = m_root.value(QStringLiteral("type")).toObject(); + const QJsonObject families = type.value(QStringLiteral("family")).toObject(); + const QJsonObject scale = + type.value(QStringLiteral("scale")).toObject().value(style).toObject(); + + auto familyList = [&](const QString &key) { + const QJsonObject f = families.value(key).toObject(); + QStringList out{f.value(QStringLiteral("value")).toString()}; + for (const QJsonValue &v : f.value(QStringLiteral("fallback")).toArray()) + out.append(v.toString()); + return out; + }; + const bool mono = scale.value(QStringLiteral("family")).toString() == QStringLiteral("mono"); + QStringList wanted = familyList(mono ? QStringLiteral("mono") : QStringLiteral("ui")); + wanted.append(familyList(QStringLiteral("cjk"))); + // Only the families installed here, so Qt never searches for a missing one; the system + // font stays the last resort. Inter and JetBrains Mono are bundled in a later change. + const QStringList installed = QFontDatabase::families(); + QStringList list; + for (const QString &family : std::as_const(wanted)) + if (installed.contains(family)) + list.append(family); + + double px = scale.value(QStringLiteral("size")).toDouble(13); + QString tracking = scale.value(QStringLiteral("tracking")).toString(); + bool upper = scale.value(QStringLiteral("case")).toString() == QStringLiteral("upper"); + if (chineseInterface()) { + px = qMax(px, 12.0); + if (upper) { + upper = false; + tracking.clear(); + } + } + + QFont font; + if (!list.isEmpty()) + font.setFamilies(list); + else if (mono) + font.setStyleHint(QFont::Monospace); + // The tokens are pixels at 72 logical dots per inch, macOS's scale. + const QScreen *screen = QGuiApplication::primaryScreen(); + const double dpi = screen ? screen->logicalDotsPerInch() : 72.0; + font.setPointSizeF(px * 72.0 / dpi); + font.setWeight(QFont::Weight(scale.value(QStringLiteral("weight")).toInt(400))); + if (tracking.endsWith(QStringLiteral("em"))) + font.setLetterSpacing(QFont::PercentageSpacing, + 100.0 + tracking.chopped(2).toDouble() * 100.0); + if (upper) + font.setCapitalization(QFont::AllUppercase); + return font; +} + +int Theme::duration(const QString &motion) const +{ + return m_root.value(QStringLiteral("motion")) + .toObject() + .value(motion) + .toObject() + .value(QStringLiteral("duration")) + .toInt(200); +} + +QEasingCurve Theme::easing(const QString &motion) const +{ + return parseEasing(m_root.value(QStringLiteral("motion")) + .toObject() + .value(motion) + .toObject() + .value(QStringLiteral("easing")) + .toString()); +} + +QStringList Theme::colorPaths() const +{ + QStringList out; + collectColors(m_root.value(QStringLiteral("color")).toObject(), QString(), out); + return out; +} + +QColor Theme::parseColor(const QString &value) +{ + const QString v = value.trimmed(); + if (v.startsWith(QLatin1Char('#'))) { + if (v.size() == 9) { // #rrggbbaa, as CSS writes it + QColor c(v.left(7)); + c.setAlpha(v.mid(7).toInt(nullptr, 16)); + return c; + } + return QColor(v); + } + static const QRegularExpression rgba( + QStringLiteral(R"(^rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*,\s*([0-9.]+)\s*\)$)")); + const QRegularExpressionMatch m = rgba.match(v); + if (!m.hasMatch()) + return {}; + QColor c(m.captured(1).toInt(), m.captured(2).toInt(), m.captured(3).toInt()); + c.setAlphaF(qBound(0.0, m.captured(4).toDouble(), 1.0)); + return c; +} + +QEasingCurve Theme::parseEasing(const QString &value) +{ + const QString v = value.trimmed(); + if (v == QStringLiteral("linear")) + return QEasingCurve(QEasingCurve::Linear); + if (v == QStringLiteral("ease-out")) + return QEasingCurve(QEasingCurve::OutCubic); + static const QRegularExpression bezier(QStringLiteral( + R"(^cubic-bezier\(\s*([0-9.]+)\s*,\s*([0-9.-]+)\s*,\s*([0-9.]+)\s*,\s*([0-9.-]+)\s*\)$)")); + const QRegularExpressionMatch m = bezier.match(v); + if (!m.hasMatch()) + return QEasingCurve(QEasingCurve::OutCubic); + QEasingCurve curve(QEasingCurve::BezierSpline); + curve.addCubicBezierSegment(QPointF(m.captured(1).toDouble(), m.captured(2).toDouble()), + QPointF(m.captured(3).toDouble(), m.captured(4).toDouble()), + QPointF(1, 1)); + return curve; +} + +QColor Theme::flattened(const QColor &layer, const QColor &surface) +{ + const double a = layer.alphaF(); + return QColor::fromRgbF(layer.redF() * a + surface.redF() * (1 - a), + layer.greenF() * a + surface.greenF() * (1 - a), + layer.blueF() * a + surface.blueF() * (1 - a)); +} + +QPalette Theme::palette() const +{ + const QColor ground = color(QStringLiteral("surface.ground")); + const QColor card = color(QStringLiteral("surface.card")); + auto over = [&](const char *path, const QColor &surface) { + return flattened(color(QString::fromLatin1(path)), surface); + }; + + QPalette p; + p.setColor(QPalette::Window, ground); + p.setColor(QPalette::WindowText, color(QStringLiteral("text.primary"))); + p.setColor(QPalette::Base, over("fill.well", card)); + p.setColor(QPalette::AlternateBase, card); + p.setColor(QPalette::Text, color(QStringLiteral("text.primary"))); + p.setColor(QPalette::PlaceholderText, color(QStringLiteral("text.quiet"))); + p.setColor(QPalette::Button, over("fill.control", card)); + p.setColor(QPalette::ButtonText, color(QStringLiteral("text.primary"))); + p.setColor(QPalette::BrightText, color(QStringLiteral("text.strong"))); + p.setColor(QPalette::Highlight, color(QStringLiteral("accent.base"))); + p.setColor(QPalette::HighlightedText, color(QStringLiteral("text.onAccent"))); + p.setColor(QPalette::Link, color(QStringLiteral("accent.link"))); + p.setColor(QPalette::LinkVisited, color(QStringLiteral("accent.link"))); + p.setColor(QPalette::ToolTipBase, over("surface.floating", ground)); + p.setColor(QPalette::ToolTipText, color(QStringLiteral("text.primary"))); + p.setColor(QPalette::Light, over("line.strong", card)); + p.setColor(QPalette::Midlight, over("line.control", card)); + p.setColor(QPalette::Mid, over("line.card", card)); + p.setColor(QPalette::Dark, ground); + p.setColor(QPalette::Shadow, Qt::black); + for (QPalette::ColorRole role : {QPalette::WindowText, QPalette::Text, QPalette::ButtonText}) + p.setColor(QPalette::Disabled, role, color(QStringLiteral("text.disabled"))); + p.setColor(QPalette::Disabled, QPalette::Highlight, over("fill.selected", card)); + return p; +} + +QString Theme::styleSheet() const +{ + auto c = [&](const char *path) { return css(color(QString::fromLatin1(path))); }; + auto n = [&](const char *path) { return QString::number(number(QString::fromLatin1(path))); }; + const QColor card = color(QStringLiteral("surface.card")); + auto over = [&](const char *path, const QColor &surface) { + return css(flattened(color(QString::fromLatin1(path)), surface)); + }; + + QString s; + s += QStringLiteral("QMainWindow, QDialog { background: %1; }\n").arg(c("surface.ground")); + s += QStringLiteral("QToolBar#stageBar { background: %1; border: 0; border-bottom: 1px solid " + "%2; spacing: 12px; padding: 7px 12px; }\n") + .arg(c("surface.titlebar"), c("line.hairline")); + s += QStringLiteral("QLabel#projectName { font-weight: 600; }\n"); + s += QStringLiteral( + "QLabel#corePill { background: %1; border: 1px solid %2; border-radius: 14px; " + "padding: 0 12px; min-height: 26px; color: %3; }\n") + .arg(c("fill.hover"), c("line.control"), c("text.secondary")); + s += QStringLiteral("QLabel[role=\"caption\"] { color: %1; }\n").arg(c("text.tertiary")); + s += QStringLiteral("QLabel[role=\"secondary\"] { color: %1; }\n").arg(c("text.secondary")); + s += QStringLiteral("QLabel[role=\"quiet\"] { color: %1; }\n").arg(c("text.quiet")); + s += QStringLiteral("QFrame[role=\"card\"] { background: %1; border: 1px solid %2; " + "border-radius: %3px; }\n") + .arg(c("surface.card"), c("line.card"), n("radius.card")); + s += QStringLiteral("QFrame[role=\"group\"] { background: %1; border: 0; border-radius: %2px; " + "}\n") + .arg(over("fill.group", card), n("radius.group")); + s += QStringLiteral("QMenu { background: %1; border: 1px solid %2; border-radius: %3px; " + "padding: 6px; }\n" + "QMenu::item { padding: 5px 14px; border-radius: 6px; }\n" + "QMenu::item:selected { background: %4; }\n" + "QMenu::separator { height: 1px; background: %2; margin: 5px 8px; }\n") + .arg(over("surface.floating", color(QStringLiteral("surface.ground"))), + c("line.strong"), n("radius.group"), over("accent.tint", card)); + s += QStringLiteral("QToolTip { background: %1; color: %2; border: 1px solid %3; " + "border-radius: 8px; padding: 5px 8px; }\n") + .arg(over("surface.floating", color(QStringLiteral("surface.ground"))), + c("text.primary"), c("line.strong")); + s += QStringLiteral("QPushButton { background: %1; border: 0; border-radius: %2px; " + "padding: 0 14px; min-height: %3px; }\n" + "QPushButton:hover { background: %4; }\n" + "QPushButton:disabled { color: %5; }\n" + "QPushButton[role=\"primary\"] { background: %6; color: %7; " + "font-weight: 700; }\n") + .arg(c("fill.control"), n("radius.button"), n("size.button"), c("line.strong"), + c("text.disabled"), c("accent.base"), c("text.onAccent")); + s += QStringLiteral("QLineEdit, QPlainTextEdit, QTextBrowser, QComboBox { background: %1; " + "border: 1px solid %2; border-radius: %3px; padding: 4px 8px; " + "selection-background-color: %4; }\n" + "QComboBox { min-height: %5px; padding: 0 10px; }\n" + "QComboBox::drop-down { border: 0; width: 20px; }\n" + "QComboBox QAbstractItemView { background: %6; border: 1px solid %7; " + "border-radius: 8px; padding: 4px; selection-background-color: %4; }\n") + .arg(over("fill.well", card), c("line.control"), n("radius.control"), + over("accent.tint", card), n("size.control"), + over("surface.floating", color(QStringLiteral("surface.ground"))), + c("line.strong")); + s += QStringLiteral("QListWidget#settingsSections { background: transparent; border: 0; " + "outline: 0; }\n" + "QListWidget#settingsSections::item { padding: 7px 10px; " + "border-radius: 8px; }\n" + "QListWidget#settingsSections::item:selected { background: %1; " + "color: %2; }\n") + .arg(c("fill.selected"), c("text.strong")); + s += QStringLiteral( + "QScrollBar:vertical { width: 10px; background: transparent; margin: 2px; }\n" + "QScrollBar:horizontal { height: 10px; background: transparent; " + "margin: 2px; }\n" + "QScrollBar::handle { background: %1; border-radius: 3px; min-height: 24px; " + "min-width: 24px; }\n" + "QScrollBar::handle:hover { background: %2; }\n" + "QScrollBar::add-line, QScrollBar::sub-line { width: 0; height: 0; }\n" + "QScrollBar::add-page, QScrollBar::sub-page { background: transparent; }\n") + .arg(c("line.strong"), c("text.disabled")); + return s; +} + +QString Theme::dockStyleSheet() const +{ + auto c = [&](const char *path) { return css(color(QString::fromLatin1(path))); }; + auto n = [&](const char *path) { return QString::number(number(QString::fromLatin1(path))); }; + + QString s; + s += QStringLiteral("ads--CDockContainerWidget { background: %1; }\n").arg(c("surface.ground")); + s += QStringLiteral("ads--CDockSplitter::handle { background: %1; }\n" + "ads--CDockSplitter::handle:horizontal { width: %2px; }\n" + "ads--CDockSplitter::handle:vertical { height: %2px; }\n") + .arg(c("surface.ground"), n("space.gutter")); + s += QStringLiteral("ads--CDockAreaWidget { background: %1; border: 1px solid %2; " + "border-radius: %3px; }\n") + .arg(c("surface.card"), c("line.card"), n("radius.card")); + s += QStringLiteral("ads--CDockAreaTitleBar { background: transparent; border: 0; " + "border-bottom: 1px solid %1; min-height: 34px; padding: 0 6px; }\n") + .arg(c("line.hairline")); + s += QStringLiteral("ads--CDockWidgetTab { background: transparent; border: 0; " + "border-radius: 6px; margin: 5px 1px; padding: 0 9px; }\n" + "ads--CDockWidgetTab:hover { background: %1; }\n" + "ads--CDockWidgetTab[activeTab=\"true\"] { background: %2; }\n" + "ads--CDockWidgetTab QLabel { color: %3; }\n" + "ads--CDockWidgetTab[activeTab=\"true\"] QLabel { color: %4; }\n") + .arg(c("fill.hover"), c("fill.selected"), c("text.secondary"), c("text.strong")); + s += QStringLiteral("ads--CDockWidget { background: %1; border: 0; }\n" + "QWidget#viewContent { background: %1; }\n" + "ads--CDockWidget > QScrollArea { background: transparent; border: 0; }\n") + .arg(c("surface.card")); + s += QStringLiteral("ads--CDockWidgetTab QAbstractButton { background: transparent; border: 0; " + "border-radius: 4px; min-height: 0; padding: 0; margin: 0 0 0 4px; }\n" + "ads--CDockWidgetTab QAbstractButton:hover { background: %1; }\n" + "ads--CTitleBarButton::menu-indicator { image: none; width: 0; }\n") + .arg(c("line.strong")); + s += QStringLiteral("ads--CTitleBarButton { background: transparent; border: 0; " + "border-radius: 6px; padding: 2px; }\n" + "ads--CTitleBarButton:hover { background: %1; }\n") + .arg(c("fill.hover")); + s += QStringLiteral("ads--CDockAreaWidget QPlainTextEdit, ads--CDockAreaWidget QTextBrowser " + "{ background: %1; border: 0; border-radius: 0; color: %2; }\n") + .arg(c("surface.card"), c("text.primary")); + return s; +} + +void Theme::install(const Theme &theme, QApplication &app) +{ + installed() = theme; + app.setPalette(theme.palette()); + app.setFont(theme.font(QStringLiteral("body"))); + app.setStyleSheet(theme.styleSheet()); +} + +const Theme &Theme::current() +{ + Theme &theme = installed(); + if (!theme.isLoaded()) + theme.load(defaultPath()); + return theme; +} + +} // namespace emblinkstudio diff --git a/app/src/theme.h b/app/src/theme.h new file mode 100644 index 0000000..543ac38 --- /dev/null +++ b/app/src/theme.h @@ -0,0 +1,96 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file theme.h + * @brief Theme: the design tokens, read from docs/design/tokens.json. + * + * @details + * Every colour, size, radius, font and timing the frame uses comes from the tokens + * (design brief section 4f); nothing else defines one. The tokens file is built into + * the application as the resource :/design/tokens.json, so the file in docs/design is + * the only source. + * + * A token is named by its path below its group: color("surface.ground"), + * color("state.success.base"), number("radius.card"), font("title2"), + * motion("move"). Colours are "#rrggbb" or "rgba(r,g,b,a)"; translucent colours are + * layers drawn over the ground, and flattened() gives the opaque colour a layer makes + * over a given surface, for the places Qt needs one (QPalette). + * + * install() sets the application's palette, font and style sheet; current() is the + * installed theme. dockStyleSheet() styles Qt Advanced Docking System, which sets its + * own style sheet on the dock manager and so must be given ours there. + * + * @see docs/design/tokens.json, docs/design/brief.md section 4f + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#pragma once + +#include +#include +#include +#include +#include +#include +#include + +class QApplication; + +namespace emblinkstudio +{ + +class Theme +{ + public: + // The tokens built into the application. + static QString defaultPath() + { + return QStringLiteral(":/design/tokens.json"); + } + + // Reads a tokens file. On failure, returns false and says why in `error`. + bool load(const QString &path, QString *error = nullptr); + bool isLoaded() const + { + return !m_root.isEmpty(); + } + + // color("surface.ground"): a colour token below "color". Invalid if there is none. + QColor color(const QString &path) const; + // number("radius.card"), number("size.titlebar"), number("space.gutter"). + double number(const QString &path) const; + // font("body"): a style of the type scale, in the interface family with its fallbacks + // (the Chinese family among them). In a Chinese interface no text is set below 12 px, + // and the caption loses its capitals and letter spacing (tokens: locale.chinese). + QFont font(const QString &style) const; + // motion("move"): its duration in milliseconds and its easing. + int duration(const QString &motion) const; + QEasingCurve easing(const QString &motion) const; + + QPalette palette() const; + QString styleSheet() const; + QString dockStyleSheet() const; + + // Every colour token, as a path, for checks and tests. + QStringList colorPaths() const; + + // "#rrggbb", "#rrggbbaa" or "rgba(r,g,b,a)"; invalid otherwise. + static QColor parseColor(const QString &value); + // "linear", "ease-out" or "cubic-bezier(x1,y1,x2,y2)". + static QEasingCurve parseEasing(const QString &value); + // The opaque colour `layer` makes when drawn over `surface`. + static QColor flattened(const QColor &layer, const QColor &surface); + + static void install(const Theme &theme, QApplication &app); + static const Theme ¤t(); + + private: + QJsonObject m_root; +}; + +} // namespace emblinkstudio diff --git a/app/src/workbench.cpp b/app/src/workbench.cpp index ff896c0..2cdc895 100644 --- a/app/src/workbench.cpp +++ b/app/src/workbench.cpp @@ -116,16 +116,48 @@ QStringList Workbench::namedLayouts() const return m_manager->perspectiveNames(); } +void Workbench::setStage(const QString &stage) +{ + if (stage == m_stage) + return; + if (!m_stage.isEmpty()) + m_stageLayouts.insert(m_stage, saveLayout()); + m_stage = stage; + const auto saved = m_stageLayouts.constFind(stage); + if (saved != m_stageLayouts.cend()) + restoreLayout(saved.value()); + emit stageChanged(stage); +} + void Workbench::save(QSettings &settings) const { settings.setValue(QStringLiteral("current"), saveLayout()); m_manager->savePerspectives(settings); + settings.setValue(QStringLiteral("stage"), m_stage); + settings.beginGroup(QStringLiteral("stages")); + settings.remove(QString()); + for (auto it = m_stageLayouts.cbegin(); it != m_stageLayouts.cend(); ++it) + if (it.key() != m_stage) + settings.setValue(it.key(), it.value()); + if (!m_stage.isEmpty()) + settings.setValue(m_stage, saveLayout()); + settings.endGroup(); } void Workbench::restore(QSettings &settings) { m_manager->loadPerspectives(settings); restoreLayout(settings.value(QStringLiteral("current")).toByteArray()); + settings.beginGroup(QStringLiteral("stages")); + m_stageLayouts.clear(); + for (const QString &key : settings.childKeys()) + m_stageLayouts.insert(key, settings.value(key).toByteArray()); + settings.endGroup(); + const QString stage = settings.value(QStringLiteral("stage")).toString(); + if (!stage.isEmpty() && stage != m_stage) { + m_stage = stage; + emit stageChanged(stage); + } emit namedLayoutsChanged(); } diff --git a/app/src/workbench.h b/app/src/workbench.h index 4bbfff1..6be0d24 100644 --- a/app/src/workbench.h +++ b/app/src/workbench.h @@ -17,6 +17,10 @@ * saves and restores the current layout, and keeps layouts saved by name. It knows * nothing about what the views show, so it is tested on its own. * + * Each stage (Configure, Code, Debug, Verify) keeps its own layout: switching stage + * keeps the layout of the stage left and brings back the one of the stage entered, + * or keeps the current one the first time a stage is entered (design brief 4d, 4g). + * * @see Spec sections 7 and 11; mainwindow.h * @author Junior Deogracias * @date 2026-11-11 (created) @@ -26,6 +30,7 @@ #include #include +#include #include #include #include @@ -62,7 +67,15 @@ class Workbench : public QObject void removeNamedLayout(const QString &name); QStringList namedLayouts() const; - // The current layout and every named layout, under `settings`' current group. + // Switches to `stage`, keeping each stage's layout. `stage` names it in saved settings. + void setStage(const QString &stage); + QString stage() const + { + return m_stage; + } + + // The current layout, the current stage and each stage's layout, and every named layout, + // under `settings`' current group. void save(QSettings &settings) const; void restore(QSettings &settings); @@ -80,11 +93,14 @@ class Workbench : public QObject signals: void namedLayoutsChanged(); + void stageChanged(const QString &stage); private: ads::CDockManager *m_manager = nullptr; QList m_views; QByteArray m_default; + QString m_stage; + QHash m_stageLayouts; }; } // namespace emblinkstudio diff --git a/app/tests/tst_language.cpp b/app/tests/tst_language.cpp new file mode 100644 index 0000000..445447d --- /dev/null +++ b/app/tests/tst_language.cpp @@ -0,0 +1,160 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file tst_language.cpp + * @brief Qt Test suite for Language, the interface language. + * + * @details + * Checks the three languages and their own names; the choice of a language for the + * system's locale; that French and Simplified Chinese translate the interface and set + * the locale numbers follow, and that English removes the translation; that a language + * not shipped is refused without changing anything; that open widgets are told to + * retranslate; and that the choice survives a restart. Settings go to a temporary + * directory, never to the user's. + * + * @see language.h, app/i18n + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#include "language.h" + +#include +#include +#include +#include +#include +#include +#include +#include + +using emblinkstudio::Language; + +namespace +{ + +QString stage(const char *text) +{ + return QCoreApplication::translate("emblinkstudio::MainWindow", text); +} + +// Counts the LanguageChange events a widget receives. +class Listener : public QWidget +{ + public: + int changes = 0; + + protected: + void changeEvent(QEvent *event) override + { + if (event->type() == QEvent::LanguageChange) + ++changes; + QWidget::changeEvent(event); + } +}; + +} // namespace + +class TestLanguage : public QObject +{ + Q_OBJECT + + private: + QTemporaryDir m_dir; + + private slots: + void initTestCase() + { + QVERIFY(m_dir.isValid()); + QSettings::setDefaultFormat(QSettings::IniFormat); + QSettings::setPath(QSettings::IniFormat, QSettings::UserScope, m_dir.path()); + QCoreApplication::setOrganizationName(QStringLiteral("EmbLinkTest")); + QCoreApplication::setApplicationName(QStringLiteral("tst_language")); + } + + void threeLanguagesInTheirOwnNames() + { + QCOMPARE(Language::codes(), (QStringList{QStringLiteral("en"), QStringLiteral("fr"), + QStringLiteral("zh_CN")})); + QCOMPARE(Language::nativeName(QStringLiteral("fr")), QStringLiteral("Français")); + QCOMPARE(Language::nativeName(QStringLiteral("zh_CN")), QStringLiteral("简体中文")); + } + + void bestForTheSystem() + { + QCOMPARE(Language::bestFor(QLocale(QLocale::French, QLocale::Canada)), + QStringLiteral("fr")); + QCOMPARE(Language::bestFor( + QLocale(QLocale::Chinese, QLocale::SimplifiedHanScript, QLocale::China)), + QStringLiteral("zh_CN")); + QCOMPARE(Language::bestFor( + QLocale(QLocale::Chinese, QLocale::TraditionalHanScript, QLocale::Taiwan)), + QStringLiteral("en")); + QCOMPARE(Language::bestFor(QLocale(QLocale::German)), QStringLiteral("en")); + } + + void frenchAndChineseTranslateTheInterface() + { + Language language; + QVERIFY(language.set(QStringLiteral("fr"))); + QCOMPARE(stage("Configure"), QStringLiteral("Configurer")); + QCOMPARE(stage("Verify"), QStringLiteral("Vérification")); + QCOMPARE(QCoreApplication::translate("emblinkstudio::SettingsDialog", "General"), + QStringLiteral("Général")); + QCOMPARE(QLocale().toString(6.8, 'f', 1), QStringLiteral("6,8")); + + QVERIFY(language.set(QStringLiteral("zh_CN"))); + QCOMPARE(stage("Configure"), QStringLiteral("配置")); + QCOMPARE(stage("Debug"), QStringLiteral("调试")); + QCOMPARE(QLocale().language(), QLocale::Chinese); + + QVERIFY(language.set(QStringLiteral("en"))); + QCOMPARE(stage("Configure"), QStringLiteral("Configure")); + QCOMPARE(QLocale().toString(6.8, 'f', 1), QStringLiteral("6.8")); + } + + void languageNotShippedIsRefused() + { + Language language; + QVERIFY(language.set(QStringLiteral("fr"))); + QSignalSpy changed(&language, &Language::changed); + QVERIFY(!language.set(QStringLiteral("de"))); + QCOMPARE(language.current(), QStringLiteral("fr")); + QCOMPARE(stage("Configure"), QStringLiteral("Configurer")); + QCOMPARE(changed.count(), 0); + QVERIFY(language.set(QStringLiteral("en"))); + } + + void openWidgetsAreToldToRetranslate() + { + Language language; + Listener widget; + QSignalSpy changed(&language, &Language::changed); + QVERIFY(language.set(QStringLiteral("fr"))); + QCoreApplication::processEvents(); + QVERIFY(widget.changes >= 1); + QCOMPARE(changed.count(), 1); + QVERIFY(language.set(QStringLiteral("en"))); + } + + void choiceSurvivesARestart() + { + { + Language language; + QVERIFY(language.set(QStringLiteral("zh_CN"))); + language.save(); + } + Language again; + again.restore(); + QCOMPARE(again.current(), QStringLiteral("zh_CN")); + QCOMPARE(stage("Code"), QStringLiteral("代码")); + QVERIFY(again.set(QStringLiteral("en"))); + } +}; + +QTEST_MAIN(TestLanguage) +#include "tst_language.moc" diff --git a/app/tests/tst_segmentedcontrol.cpp b/app/tests/tst_segmentedcontrol.cpp new file mode 100644 index 0000000..5d25105 --- /dev/null +++ b/app/tests/tst_segmentedcontrol.cpp @@ -0,0 +1,110 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file tst_segmentedcontrol.cpp + * @brief Qt Test suite for SegmentedControl, the stage switch. + * + * @details + * Checks that the first segment is chosen when segments are added; that a click + * chooses the segment under it; that the keyboard moves the choice and stops at the + * ends; that an index out of range is ignored; and that a longer text, as a + * translation brings, widens the control instead of being cut. + * + * @see segmentedcontrol.h + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#include "segmentedcontrol.h" + +#include +#include + +using emblinkstudio::SegmentedControl; + +namespace +{ + +void fill(SegmentedControl &c) +{ + for (const char *text : {"Configure", "Code", "Debug", "Verify"}) + c.addSegment(QString::fromLatin1(text)); +} + +} // namespace + +class TestSegmentedControl : public QObject +{ + Q_OBJECT + + private slots: + void firstSegmentIsChosen() + { + SegmentedControl c; + QCOMPARE(c.currentIndex(), -1); + fill(c); + QCOMPARE(c.count(), 4); + QCOMPARE(c.currentIndex(), 0); + } + + void clickChoosesTheSegment() + { + SegmentedControl c; + fill(c); + c.resize(c.sizeHint()); + c.show(); + QVERIFY(QTest::qWaitForWindowExposed(&c)); + QSignalSpy changed(&c, &SegmentedControl::currentChanged); + QTest::mouseClick(&c, Qt::LeftButton, {}, c.segmentRect(2).center().toPoint()); + QCOMPARE(c.currentIndex(), 2); + QCOMPARE(changed.count(), 1); + QCOMPARE(changed.first().first().toInt(), 2); + QTest::mouseClick(&c, Qt::LeftButton, {}, c.segmentRect(2).center().toPoint()); + QCOMPARE(changed.count(), 1); // the same segment again changes nothing + } + + void keyboardMovesTheChoice() + { + SegmentedControl c; + fill(c); + QTest::keyClick(&c, Qt::Key_Right); + QCOMPARE(c.currentIndex(), 1); + QTest::keyClick(&c, Qt::Key_End); + QCOMPARE(c.currentIndex(), 3); + QTest::keyClick(&c, Qt::Key_Right); + QCOMPARE(c.currentIndex(), 3); + QTest::keyClick(&c, Qt::Key_Home); + QCOMPARE(c.currentIndex(), 0); + QTest::keyClick(&c, Qt::Key_Left); + QCOMPARE(c.currentIndex(), 0); + } + + void outOfRangeIsIgnored() + { + SegmentedControl c; + fill(c); + c.setCurrentIndex(9); + c.setCurrentIndex(-1); + QCOMPARE(c.currentIndex(), 0); + QCOMPARE(c.segmentText(9), QString()); + } + + void longerTextWidensTheControl() + { + SegmentedControl c; + fill(c); + const int before = c.sizeHint().width(); + c.setSegmentText(0, QStringLiteral("Configurer")); + c.setSegmentText(3, QStringLiteral("Vérification")); + QVERIFY(c.sizeHint().width() > before); + QCOMPARE(c.segmentText(3), QStringLiteral("Vérification")); + QVERIFY(c.segmentRect(3).right() <= c.sizeHint().width()); + } +}; + +QTEST_MAIN(TestSegmentedControl) +#include "tst_segmentedcontrol.moc" diff --git a/app/tests/tst_theme.cpp b/app/tests/tst_theme.cpp new file mode 100644 index 0000000..a0973f1 --- /dev/null +++ b/app/tests/tst_theme.cpp @@ -0,0 +1,139 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Junior Deogracias +// +// This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +// Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. + +/** + * @file tst_theme.cpp + * @brief Qt Test suite for Theme, the design tokens in Qt. + * + * @details + * Checks that the tokens built into the application are the file in docs/design; that + * every colour token parses, in each of the forms the file uses; that the palette, the + * fonts, the motions and the style sheets are taken from the tokens; and that a Chinese + * interface sets no text below 12 px and drops the caption's capitals. + * + * @see theme.h, docs/design/tokens.json + * @author Junior Deogracias + * @date 2026-11-12 (created) + */ + +#include "theme.h" + +#include +#include +#include +#include +#include + +using emblinkstudio::Theme; + +class TestTheme : public QObject +{ + Q_OBJECT + + private: + Theme m_theme; + + private slots: + void initTestCase() + { + QString error; + QVERIFY2(m_theme.load(Theme::defaultPath(), &error), qPrintable(error)); + } + + void builtInTokensAreTheFileInTheRepository() + { + QFile builtIn(Theme::defaultPath()); + QFile source(QStringLiteral(EMBLINK_STUDIO_TOKENS)); + QVERIFY(builtIn.open(QIODevice::ReadOnly)); + QVERIFY(source.open(QIODevice::ReadOnly)); + QCOMPARE(builtIn.readAll(), source.readAll()); + } + + void everyColourTokenParses() + { + const QStringList paths = m_theme.colorPaths(); + QVERIFY2(paths.size() >= 50, qPrintable(QString::number(paths.size()))); + for (const QString &path : paths) + QVERIFY2(m_theme.color(path).isValid(), qPrintable(path)); + QVERIFY(!m_theme.color(QStringLiteral("surface.nothing")).isValid()); + } + + void colourForms() + { + QCOMPARE(Theme::parseColor(QStringLiteral("#111214")), QColor(0x11, 0x12, 0x14)); + const QColor hairline = Theme::parseColor(QStringLiteral("rgba(255,255,255,.05)")); + QCOMPARE(hairline.red(), 255); + QCOMPARE(hairline.alpha(), 13); + QCOMPARE(Theme::parseColor(QStringLiteral("#64d2ff80")).alpha(), 128); + QVERIFY(!Theme::parseColor(QStringLiteral("cyan-ish")).isValid()); + } + + void flattenedIsWhatALayerMakes() + { + const QColor half = Theme::flattened(QColor(255, 255, 255, 128), Qt::black); + QCOMPARE(half.alpha(), 255); + QVERIFY(qAbs(half.red() - 128) <= 1); + } + + void paletteComesFromTheTokens() + { + const QPalette p = m_theme.palette(); + QCOMPARE(p.color(QPalette::Window), m_theme.color(QStringLiteral("surface.ground"))); + QCOMPARE(p.color(QPalette::Highlight), m_theme.color(QStringLiteral("accent.base"))); + QCOMPARE(p.color(QPalette::HighlightedText), + m_theme.color(QStringLiteral("text.onAccent"))); + QCOMPARE(p.color(QPalette::Base).alpha(), 255); // flattened, never translucent + } + + void numbersAndMotions() + { + QCOMPARE(m_theme.number(QStringLiteral("radius.card")), 12.0); + QCOMPARE(m_theme.number(QStringLiteral("space.gutter")), 6.0); + QCOMPARE(m_theme.number(QStringLiteral("size.titlebar")), 50.0); + QCOMPARE(m_theme.duration(QStringLiteral("move")), 350); + QCOMPARE(m_theme.easing(QStringLiteral("move")).type(), QEasingCurve::BezierSpline); + // cubic-bezier(.2,.8,.2,1) is ahead of linear halfway. + QVERIFY(m_theme.easing(QStringLiteral("move")).valueForProgress(0.5) > 0.6); + QCOMPARE(Theme::parseEasing(QStringLiteral("linear")).type(), QEasingCurve::Linear); + } + + void fontsFollowTheScale() + { + QLocale::setDefault(QLocale(QLocale::English)); + const QFont caption = m_theme.font(QStringLiteral("caption")); + QCOMPARE(caption.capitalization(), QFont::AllUppercase); + QCOMPARE(caption.weight(), QFont::DemiBold); + // Only installed families are named: never one Qt would have to search for. + const QStringList installed = QFontDatabase::families(); + for (const QString &family : caption.families()) + QVERIFY2(installed.contains(family), qPrintable(family)); + QVERIFY(caption.pointSizeF() < m_theme.font(QStringLiteral("small")).pointSizeF()); + } + + void chineseSetsNoTextBelowTwelvePixels() + { + QLocale::setDefault( + QLocale(QLocale::Chinese, QLocale::SimplifiedHanScript, QLocale::China)); + const QFont caption = m_theme.font(QStringLiteral("caption")); + QCOMPARE(caption.capitalization(), QFont::MixedCase); + QCOMPARE(caption.pointSizeF(), m_theme.font(QStringLiteral("small")).pointSizeF()); + QLocale::setDefault(QLocale(QLocale::English)); + } + + void styleSheetsAreComplete() + { + static const QRegularExpression leftover(QStringLiteral("%\\d")); + const QString app = m_theme.styleSheet(); + const QString dock = m_theme.dockStyleSheet(); + QVERIFY(app.contains(QStringLiteral("#111214"))); + QVERIFY(dock.contains(QStringLiteral("ads--CDockAreaWidget"))); + QVERIFY2(!app.contains(leftover), qPrintable(app)); + QVERIFY2(!dock.contains(leftover), qPrintable(dock)); + } +}; + +QTEST_MAIN(TestTheme) +#include "tst_theme.moc" diff --git a/app/tests/tst_workbench.cpp b/app/tests/tst_workbench.cpp index c0f15a0..b68aaf5 100644 --- a/app/tests/tst_workbench.cpp +++ b/app/tests/tst_workbench.cpp @@ -12,7 +12,8 @@ * Checks the layout rule of spec section 7: every view can be moved, floated and closed; * a layout saved is the layout restored, in a new window as after a restart; named * layouts survive a restart through QSettings; Reset brings back the default; and a - * layout from another version is refused rather than half applied. + * layout from another version is refused rather than half applied; and each stage keeps + * its own layout, across a restart too. * * @see workbench.h * @author Junior Deogracias @@ -25,6 +26,7 @@ #include #include #include +#include #include #include #include @@ -174,6 +176,49 @@ class TestWorkbench : public QObject QVERIFY(second.consoleTabbedWithLog()); QVERIFY(!second.workbench->restoreLayout(QByteArray())); } + + void eachStageKeepsItsLayout() + { + Window w; + QSignalSpy changed(w.workbench, &Workbench::stageChanged); + w.workbench->setStage(QStringLiteral("configure")); + w.moveConsoleRight(); + // A stage entered for the first time keeps the layout on screen. + w.workbench->setStage(QStringLiteral("code")); + QVERIFY(!w.consoleTabbedWithLog()); + w.workbench->resetLayout(); + QVERIFY(w.consoleTabbedWithLog()); + w.workbench->setStage(QStringLiteral("configure")); + QVERIFY(!w.consoleTabbedWithLog()); + w.workbench->setStage(QStringLiteral("code")); + QVERIFY(w.consoleTabbedWithLog()); + w.workbench->setStage(QStringLiteral("code")); // no change, no signal + QCOMPARE(changed.count(), 4); + QCOMPARE(w.workbench->stage(), QStringLiteral("code")); + } + + void stageLayoutsSurviveARestart() + { + QTemporaryDir dir; + QVERIFY(dir.isValid()); + const QString ini = dir.filePath(QStringLiteral("layout.ini")); + { + Window first; + first.workbench->setStage(QStringLiteral("configure")); + first.moveConsoleRight(); + first.workbench->setStage(QStringLiteral("code")); + first.workbench->resetLayout(); + QSettings settings(ini, QSettings::IniFormat); + first.workbench->save(settings); + } + Window second; + QSettings settings(ini, QSettings::IniFormat); + second.workbench->restore(settings); + QCOMPARE(second.workbench->stage(), QStringLiteral("code")); + QVERIFY(second.consoleTabbedWithLog()); + second.workbench->setStage(QStringLiteral("configure")); + QVERIFY(!second.consoleTabbedWithLog()); + } }; QTEST_MAIN(TestWorkbench) diff --git a/docs/development.md b/docs/development.md index 7fbb0fb..dabe3a1 100644 --- a/docs/development.md +++ b/docs/development.md @@ -28,6 +28,27 @@ Run the application: `build/dev/app/EmbLinkStudio.app/Contents/MacOS/EmbLinkStud `build/dev/app/EmbLinkStudio` elsewhere. It runs the core from `core/src` with the Python CMake found; set `EMBLINK_STUDIO_CORE` to an installed `emblink-studio-core` to use that instead. +Options for a run: `--language en|fr|zh_CN` uses that language without saving it, `--stage +configure|code|debug|verify` opens on that stage, and `--screenshot ` saves a picture of the window and +quits. + +## The look and the languages + +Every colour, size, font and timing comes from [`docs/design/tokens.json`](design/tokens.json), which the +build compiles into the application; change the look there, not in the C++. The design brief explains the +tokens in section 4f. + +The interface is in English, French and Simplified Chinese. Write every visible string in English inside +`tr()`, then refresh the translation files and translate the new strings in Qt Linguist: + +```sh +cmake --build --preset dev --target update_translations # updates app/i18n/*.ts from the sources +linguist app/i18n/emblinkstudio_fr.ts app/i18n/emblinkstudio_zh_CN.ts +``` + +The build compiles the `.ts` files into the application. A string with no translation shows in English. +Option keys, pin, register and file names, and code are never translated. + ## The editor The repository's [`.clangd`](../.clangd) points clangd at `build/dev/compile_commands.json`, so any @@ -37,7 +58,7 @@ as missing. After the first configure, restart the language server (in VS Code: *clangd: Restart language server*). `progress-screenshots/` is ignored by git: keep pictures of the application as it grows there, on your -machine only. +machine only, for example with `--screenshot progress-screenshots/configure-fr.png --language fr`. ## How a change reaches `main` @@ -58,8 +79,10 @@ Release tags (`v*`) can only be created by the maintainers, and can never be mov | Path | What | | --- | --- | | `app/` | The Qt application and its tests | +| `app/i18n/` | The French and Simplified Chinese translations | | `core/` | EmbLink Studio Core: `emblink-studio-core serve` | | `protocol/` | JSON Schemas of every method's parameters and result | | `docs/` | The specification and this guide | +| `docs/design/` | The design brief and the design tokens the application reads | | `third_party/components.json` | Every third-party component and its licence | | `tools/notices.py` | Checks those licences and writes the notices list for the About box | From eec6a90a2504a217b965e0692c9d879eb8eb42c3 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:14:06 +0100 Subject: [PATCH 3/8] ci: rerun failed Qt tests with their full output Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- .github/workflows/ci.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fe97668..c587e82 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -69,6 +69,9 @@ jobs: - run: cmake --preset dev - run: cmake --build --preset dev - run: ctest --preset dev + - name: Failed tests, again, with their full output + if: failure() + run: ctest --preset dev --rerun-failed --extra-verbose format: name: clang-format From b87aa6ad111780eeb9e93e109eff18b79b8c7d89 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:19:29 +0100 Subject: [PATCH 4/8] ci: TEMPORARY, run tst_theme directly on Windows Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- .github/workflows/ci.yml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c587e82..2a8ae9f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,6 +72,14 @@ jobs: - name: Failed tests, again, with their full output if: failure() run: ctest --preset dev --rerun-failed --extra-verbose + - name: TEMPORARY tst_theme on Windows + if: failure() && runner.os == 'Windows' + env: + QT_QPA_PLATFORM: offscreen + working-directory: build/dev/app + run: | + & ../tst_theme.exe -v2 -maxwarnings 0 2>&1 | Out-String -Stream + echo "exit code: $LASTEXITCODE" format: name: clang-format From 2d05a6d09b22f411a18417ac814e0b8a568d5df6 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:22:49 +0100 Subject: [PATCH 5/8] app: tests are console programs, so CTest shows their output on Windows Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- .github/workflows/ci.yml | 8 -------- 1 file changed, 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2a8ae9f..c587e82 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,14 +72,6 @@ jobs: - name: Failed tests, again, with their full output if: failure() run: ctest --preset dev --rerun-failed --extra-verbose - - name: TEMPORARY tst_theme on Windows - if: failure() && runner.os == 'Windows' - env: - QT_QPA_PLATFORM: offscreen - working-directory: build/dev/app - run: | - & ../tst_theme.exe -v2 -maxwarnings 0 2>&1 | Out-String -Stream - echo "exit code: $LASTEXITCODE" format: name: clang-format From 66a3dff33061134518cb04cc1ed1f59f5ad81567 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:26:08 +0100 Subject: [PATCH 6/8] app: tests are console programs, so CTest shows their output on Windows Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- app/CMakeLists.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/app/CMakeLists.txt b/app/CMakeLists.txt index 9f942a1..e81a3eb 100644 --- a/app/CMakeLists.txt +++ b/app/CMakeLists.txt @@ -99,6 +99,10 @@ if(EMBLINK_STUDIO_BUILD_TESTS) target_link_libraries(${test} PRIVATE emblink_studio_ui Qt6::Test) add_test(NAME ${test} COMMAND ${test}) endforeach() + # qt_standard_project_setup() makes executables GUI programs on Windows and bundles on + # macOS; a test is a console program, so its output reaches CTest on every system. + set_target_properties(tst_framing tst_coreclient tst_workbench tst_theme tst_segmentedcontrol + tst_language PROPERTIES WIN32_EXECUTABLE OFF MACOSX_BUNDLE OFF) target_compile_definitions(tst_theme PRIVATE EMBLINK_STUDIO_TOKENS="${PROJECT_SOURCE_DIR}/docs/design/tokens.json") endif() From d084751807736ccf09d06652295bb325d83e616e Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:29:04 +0100 Subject: [PATCH 7/8] ci: TEMPORARY, tst_theme's output to a file on Windows Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- .github/workflows/ci.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c587e82..ab4ed71 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,6 +72,16 @@ jobs: - name: Failed tests, again, with their full output if: failure() run: ctest --preset dev --rerun-failed --extra-verbose + - name: TEMPORARY tst_theme on Windows + if: failure() && runner.os == 'Windows' + env: + QT_QPA_PLATFORM: offscreen + working-directory: build/dev/app + run: | + dumpbin /headers ..\tst_theme.exe | Select-String "subsystem" + $p = Start-Process -FilePath ..\tst_theme.exe -ArgumentList '-o','out.txt,txt','-v1' -Wait -PassThru -NoNewWindow + echo "exit code: $($p.ExitCode)" + if (Test-Path out.txt) { Get-Content out.txt } else { echo "no out.txt" } format: name: clang-format From 70846dfe10448fde60f6c22beb880630f8184dfe Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:35:10 +0100 Subject: [PATCH 8/8] tst_theme: check font families only where fonts are installed Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- .github/workflows/ci.yml | 10 ---------- app/tests/tst_theme.cpp | 8 +++++--- 2 files changed, 5 insertions(+), 13 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ab4ed71..c587e82 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,16 +72,6 @@ jobs: - name: Failed tests, again, with their full output if: failure() run: ctest --preset dev --rerun-failed --extra-verbose - - name: TEMPORARY tst_theme on Windows - if: failure() && runner.os == 'Windows' - env: - QT_QPA_PLATFORM: offscreen - working-directory: build/dev/app - run: | - dumpbin /headers ..\tst_theme.exe | Select-String "subsystem" - $p = Start-Process -FilePath ..\tst_theme.exe -ArgumentList '-o','out.txt,txt','-v1' -Wait -PassThru -NoNewWindow - echo "exit code: $($p.ExitCode)" - if (Test-Path out.txt) { Get-Content out.txt } else { echo "no out.txt" } format: name: clang-format diff --git a/app/tests/tst_theme.cpp b/app/tests/tst_theme.cpp index a0973f1..6c35b7a 100644 --- a/app/tests/tst_theme.cpp +++ b/app/tests/tst_theme.cpp @@ -106,10 +106,12 @@ class TestTheme : public QObject const QFont caption = m_theme.font(QStringLiteral("caption")); QCOMPARE(caption.capitalization(), QFont::AllUppercase); QCOMPARE(caption.weight(), QFont::DemiBold); - // Only installed families are named: never one Qt would have to search for. + // Only installed families are named: never one Qt would have to search for. (Where + // no font is installed at all, as on Windows' offscreen platform, there is none to name.) const QStringList installed = QFontDatabase::families(); - for (const QString &family : caption.families()) - QVERIFY2(installed.contains(family), qPrintable(family)); + if (!installed.isEmpty()) + for (const QString &family : caption.families()) + QVERIFY2(installed.contains(family), qPrintable(family)); QVERIFY(caption.pointSizeF() < m_theme.font(QStringLiteral("small")).pointSizeF()); }