new docs for project

2026-09-03 09:16:56 +03:00
parent f1a840174b
commit 00e7c957e4
34 changed files with 5323 additions and 0 deletions
@@ -0,0 +1,97 @@
+# main.cpp — точка входа
+
+## Обзор
+
+`Minecraft_launcher` — десктопный лаунчер Minecraft на Qt 6 Quick. Интерфейс написан на QML,
+вся работа — авторизация, скачивание версий, установка модлоадеров и Java, запуск игры — лежит в
+C++-классе [LauncherBackend](LauncherBackend.md) и его сервисах.
+
+`main.cpp` — стартовая последовательность приложения: здесь при необходимости инициализируется
+Qt WebEngine, создаётся объект приложения, читается каталог переводов, выбирается стиль
+Qt Quick Controls, загружается QML-модуль и запускается цикл событий. Файл намеренно короткий:
+ни одного объекта предметной области он не создаёт — всё, что нужно, QML заводит сам.
+
+## Настройка приложения Qt
+
+Создаётся `QGuiApplication` — не `QApplication`: интерфейс целиком на Qt Quick, виджеты не
+используются, и модуль Qt Widgets в проект не подключён.
+
+До создания приложения, при сборке с Qt WebEngine, вызывается `QtWebEngineQuick::initialize()`.
+Порядок здесь принципиален: инициализация выставляет общий контекст OpenGL, а после создания
+объекта приложения это уже не действует. Вызов обёрнут в условную компиляцию по макросу
+`LAUNCHER_HAS_WEBENGINE`.
+
+## Каталог переводов
+
+Сразу после создания приложения вызывается `Localization::instance().load()` — он читает
+`i18n/translations.json` из ресурсов и определяет язык интерфейса. Порядок важен: язык нужно
+знать до того, как QML вычислит первую привязку, а [LauncherBackend](LauncherBackend.md),
+который ведёт `settings.json`, появляется только вместе с движком — поэтому ключ `language`
+[Localization](Localization.md) читает из файла сам.
+
+Неудача — не повод продолжать: каталог вкомпилирован в бинарник, значит его отсутствие или
+поломка означают ошибку сборки. `main()` пишет причину и возвращает `-1`.
+
+## Стиль Qt Quick Controls
+
+Стиль Qt Quick Controls принудительно выставляется в `Basic`
+вызовом `QQuickStyle::setStyle()`. Причина в оформлении: всё окно лаунчера стилизовано вручную, а
+нативный стиль Windows игнорирует пользовательские `contentItem` и `background` и сыплет
+предупреждениями.
+
+## Обработка командной строки
+
+Аргументы командной строки не разбираются: `argc` и `argv` передаются в конструктор
+`QGuiApplication` и дальше не используются. Ни `QCommandLineParser`, ни собственного разбора в
+файле нет.
+
+## Создание объектов верхнего уровня
+
+В `main()` создаётся ровно два объекта.
+
+| Объект | Тип | Роль |
+|--------|-----|------|
+| `app` | `QGuiApplication` | объект приложения и цикл событий |
+| `engine` | `QQmlApplicationEngine` | загружает и исполняет QML-модуль лаунчера |
+
+Экземпляр `LauncherBackend` здесь не создаётся: тип зарегистрирован через `QML_ELEMENT`, и главное
+окно объявляет его само декларативно. Поэтому в `main.cpp` нет ни одного `#include` классов
+предметной области.
+
+## Связывание и подключения
+
+Единственное подключение — обработка неудачи создания корневого объекта: сигнал
+`QQmlApplicationEngine::objectCreationFailed` замыкается на лямбду, которая завершает приложение
+с кодом `-1`. Соединение создаётся с типом `Qt::QueuedConnection` и с объектом `app` в роли
+контекста, чтобы выход из приложения происходил уже внутри цикла событий, а не в разгар загрузки
+QML.
+
+Контекстные свойства не задаются, начальные свойства корневому объекту не передаются: связь между
+QML и C++ идёт исключительно через зарегистрированный тип.
+
+## Цикл событий
+
+QML загружается вызовом `engine.loadFromModule("Minecraft_launcher", "Main")` — по URI модуля и
+имени типа, а не по пути к файлу. Модуль объявлен в `CMakeLists.txt` через `qt_add_qml_module`, а
+`Main` — это [Main.qml](../qml/Main.md), корневой элемент которого `Window` с `visible: true`,
+поэтому окно показывается само.
+
+Цикл событий запускается `app.exec()`, его результат возвращается из `main()` как код завершения
+процесса.
+
+## Зависимости
+
+| Заголовок | Что даёт |
+|-----------|----------|
+| `QGuiApplication` | объект приложения и цикл событий для приложения без виджетов |
+| `QQmlApplicationEngine` | загрузка QML-модуля и создание корневого объекта |
+| `QQuickStyle` | выбор стиля Qt Quick Controls до загрузки QML |
+| `QtWebEngineQuick` | инициализация WebEngine; подключается только при сборке с Qt WebEngine |
+
+Модули сборки: `Qt6::Quick`, `Qt6::QuickControls2`, `Qt6::Core`, `Qt6::CorePrivate`, `Qt6::Gui`,
+`Qt6::Network` и опционально `Qt6::WebEngineQuick`. Макрос `LAUNCHER_HAS_WEBENGINE` определяется в
+`CMakeLists.txt` только тогда, когда `find_package` нашёл `Qt6WebEngineQuick`.
+
+---
+
+При создании этого документа использовался ИИ.