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,89 @@
+# DarkCombo
+
+## Обзор компонента
+
+`Minecraft_launcher` — десктопный лаунчер Minecraft на Qt Quick. Всё окно оформлено вручную в
+тёмной теме, а стиль Qt Quick Controls принудительно выставлен в `Basic` (`main.cpp`), потому что
+нативные стили игнорируют пользовательские `contentItem` и `background`. Из-за этого каждый
+стандартный элемент управления, попадающий в интерфейс, приходится переопределять самому.
+
+`DarkCombo` — как раз такое переопределение: выпадающий список в общем тёмном стиле окна.
+Компонент не добавляет логики, он целиком про внешний вид — фон, рамку, стрелку, делегат строки и
+всплывающую панель. К нему обращаются всюду, где нужен выпадающий список внутри диалогов: выбор
+версии модлоадера, выбор Java, поля в настройках.
+
+## Место в проекте и зависимости
+
+Импортирует `QtQuick` и `QtQuick.Controls 2.15`; собственных C++-типов не использует.
+
+Объявлен в `QML_FILES` модуля `Minecraft_launcher` (см. `CMakeLists.txt`), поэтому доступен по
+имени `DarkCombo` в любом файле того же модуля без явного импорта.
+
+Используется в [LoaderRow](LoaderRow.md) — список версий модлоадера — и дважды в [Main](Main.md):
+в выпадающих списках профиля и сборки на главном окне.
+
+Компонент ссылается на ресурсы `images/Profile_Box/Asset_23.svg` и
+`images/Profile_Box/Asset_24.svg` — они перечислены в `RESOURCES` того же QML-модуля, отдельного
+подключения не требуют.
+
+## Иерархия и роль
+
+Корневой тип — `ComboBox` из Qt Quick Controls. Всё поведение (модель, `currentIndex`,
+`activated`, `displayText`, клавиатурная навигация) наследуется без изменений; `DarkCombo`
+переопределяет только четыре визуальных слота базового типа:
+
+| Слот | Что даёт `DarkCombo` |
+|------|----------------------|
+| `indicator` | стрелка из SVG-ресурса вместо двойного шеврона Basic-стиля; при открытом списке (`down`) картинка меняется |
+| `contentItem` | текст текущего значения белым, с обрезкой справа многоточием и отступом под стрелку |
+| `background` | тёмный прямоугольник со скруглением 6 px; рамка подсвечивается акцентным цветом при фокусе |
+| `delegate` | строка списка: белый текст, подсветка фона у элемента под курсором |
+| `popup` | всплывающая панель шириной с сам комбобокс, высотой не более 220 px, с вертикальным индикатором прокрутки |
+
+## Свойства
+
+Собственных свойств компонент не объявляет — доступен весь набор свойств `ComboBox`
+(`model`, `currentIndex`, `currentText`, `displayText`, `editable` и прочие).
+
+Внутри `delegate` объявлены два обязательных свойства делегата, они относятся к строке списка,
+а не к самому комбобоксу:
+
+| Свойство | Тип | По умолчанию | Обязательное | Описание |
+|----------|-----|--------------|--------------|----------|
+| `modelData` | `var` | — | **Да** | Значение строки модели; выводится текстом в строке списка. Модель ожидается плоской — списком строк, а не объектов. |
+| `index` | `int` | — | **Да** | Позиция строки; сравнивается с `highlightedIndex` комбобокса, чтобы подсветить строку под курсором. |
+
+## Сигналы
+
+Собственных сигналов нет. Наследуются сигналы `ComboBox`, из которых на практике используется
+`activated(int index)` — выбор строки пользователем (в отличие от `currentIndexChanged`, он не
+срабатывает при программной смене значения).
+
+## Методы
+
+Собственных функций нет.
+
+## Взаимодействие с другими компонентами
+
+Компонент самодостаточен и ничего не знает ни о бэкенде, ни о родителе: модель приходит извне
+через `model`, результат выбора родитель получает через унаследованный `activated`. Так,
+[LoaderRow](LoaderRow.md) передаёт в `model` список подписей версий модлоадера и в обработчике
+`activated` переводит индекс обратно в номер версии.
+
+Поскольку модель ожидается списком строк, вызывающий код обычно сам приводит массив объектов к
+массиву подписей перед присваиванием.
+
+## Пример использования
+
+```qml
+DarkCombo {
+    width: 200
+    height: 32
+    model: ["1.21.1", "1.20.6", "1.20.4"]
+    onActivated: (index) => console.log("выбрано:", model[index])
+}
+```
+
+---
+
+При создании этого документа использовался ИИ.