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
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..e81a3eb 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,16 @@ 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()
+ # 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()
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..6c35b7a
--- /dev/null
+++ b/app/tests/tst_theme.cpp
@@ -0,0 +1,141 @@
+// 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. (Where
+ // no font is installed at all, as on Windows' offscreen platform, there is none to name.)
+ const QStringList installed = QFontDatabase::families();
+ if (!installed.isEmpty())
+ 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/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."
+ }
+ }
+}
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 |