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,76 @@
+# LabelledField
+
+## Обзор компонента
+
+`Minecraft_launcher` — десктопный лаунчер Minecraft на Qt Quick с полностью самостоятельно
+оформленным тёмным интерфейсом. В диалоге настроек и в редакторе сборок много однотипных полей
+ввода: подпись сверху, поле под ней. `LabelledField` собирает эту пару в один компонент, чтобы
+отступы, цвета и подсветка фокуса не переписывались в каждом месте заново.
+
+Компонент нужен там, где пользователь вводит короткое значение: имя профиля, объём памяти, путь,
+аргументы запуска.
+
+## Место в проекте и зависимости
+
+Импортирует `QtQuick` и `QtQuick.Controls 2.15`; C++-типы не используются.
+
+Объявлен в `QML_FILES` модуля `Minecraft_launcher` (`CMakeLists.txt`) и доступен по имени внутри
+модуля без импорта. Применяется в диалоге настроек и в карточке сборки — см. [Main](Main.md) и
+[BuildsDialog](BuildsDialog.md).
+
+## Иерархия и роль
+
+Корневой тип — `Column` с расстоянием 3 px между элементами. Колонка содержит два потомка:
+`Text` с подписью (серый, 11 px) и `TextField` фиксированной высоты 32 px с тёмным фоном,
+скруглением 6 px и рамкой, которая при фокусе поля меняет цвет на акцентный.
+
+Ширина поля привязана к ширине самой колонки, поэтому размер задаётся снаружи одним свойством
+`width` корневого элемента. Высоту `Column` вычисляет сам.
+
+## Свойства
+
+| Свойство | Тип | По умолчанию | Обязательное | Описание |
+|----------|-----|--------------|--------------|----------|
+| `text` | `string` (алиас на `text` внутреннего поля) | `""` | Нет | Содержимое поля ввода. Работает в обе стороны: чтение возвращает введённое значение, запись подставляет новое. |
+| `validator` | `var` (алиас на `validator` внутреннего поля) | `null` | Нет | Валидатор ввода — например `IntValidator` для числовых полей. Ограничивает то, что пользователь может набрать. |
+| `label` | `string` | `""` | Нет | Текст подписи над полем. |
+| `placeholder` | `string` | `""` | Нет | Подсказка, показываемая в пустом поле приглушённым цветом. |
+
+## Сигналы
+
+#### editingFinished()
+
+Проброшен из внутреннего `TextField`: срабатывает, когда правка закончена — поле потеряло фокус
+или пользователь нажал Enter. Промежуточные нажатия клавиш сигнала не вызывают.
+
+Обработчик обычно сохраняет введённое значение: читает `text` и передаёт его в бэкенд или в
+модель родительского диалога. Именно из-за этой семантики поля настроек сохраняются по завершении
+правки, а не на каждый символ.
+
+## Методы
+
+Собственных функций нет.
+
+## Взаимодействие с другими компонентами
+
+Компонент не знает ни о бэкенде, ни о содержащем его диалоге. Родитель задаёт `label`,
+`placeholder`, начальный `text` и при необходимости `validator`, а затем подписывается на
+`editingFinished`, чтобы записать значение. Двусторонней привязки к бэкенду внутри компонента нет
+— решение о том, когда и куда сохранять, целиком за родителем.
+
+## Пример использования
+
+```qml
+LabelledField {
+    width: parent.width
+    label: "Оперативная память, МБ"
+    placeholder: "2048"
+    text: String(settings.memoryMb)
+    validator: IntValidator { bottom: 512; top: 32768 }
+    onEditingFinished: settings.memoryMb = parseInt(text)
+}
+```
+
+---
+
+При создании этого документа использовался ИИ.