91 lines
6.3 KiB
Markdown
91 lines
6.3 KiB
Markdown
|
# ProgressPanel
|
|||
|
|
|
|||
|
|
## Обзор компонента
|
|||
|
|
|
|||
|
|
`Minecraft_launcher` — десктопный лаунчер Minecraft на Qt Quick. Почти каждое действие в нём
|
|||
|
|
долгое: скачивание версии игры, установка Java, распаковка и архивация папки `.minecraft` при
|
|||
|
|
смене сборки, загрузка сезонной сборки. Лаунчер не блокирует окно на это время, поэтому ход
|
|||
|
|
операции нужно показывать неотрывно от остального интерфейса.
|
|||
|
|
|
|||
|
|
`ProgressPanel` — та самая плашка прогресса. Она размещается в левом нижнем углу главного окна,
|
|||
|
|
где не перекрывает кнопку запуска, сообщение по центру и кнопки папки и настроек. Компонент
|
|||
|
|
только отображает переданное состояние; сам он ничего не считает и ни за чем не следит.
|
|||
|
|
|
|||
|
|
## Место в проекте и зависимости
|
|||
|
|
|
|||
|
|
Импортирует `QtQuick` и `QtQuick.Controls 2.15`; C++-типы напрямую не использует.
|
|||
|
|
|
|||
|
|
Объявлен в `QML_FILES` модуля `Minecraft_launcher` (`CMakeLists.txt`), поэтому доступен по имени
|
|||
|
|
внутри модуля без импорта. Инстанцируется в [Main](Main.md) — по одной плашке на вид долгой
|
|||
|
|
операции.
|
|||
|
|
|
|||
|
|
## Иерархия и роль
|
|||
|
|
|
|||
|
|
Корневой тип — `Rectangle` фиксированного размера 320×72 px со скруглением 8 px, тёмной заливкой,
|
|||
|
|
акцентной рамкой и лёгкой полупрозрачностью, чтобы плашка читалась поверх фонового изображения
|
|||
|
|
окна.
|
|||
|
|
|
|||
|
|
Внутри — пять элементов без внешних зависимостей: заголовок слева сверху, проценты справа сверху,
|
|||
|
|
полоса прогресса (дорожка и заполнение с плавной анимацией ширины на 120 мс), строка подробностей
|
|||
|
|
снизу и крестик отмены в правом нижнем углу с увеличенной областью нажатия.
|
|||
|
|
|
|||
|
|
## Свойства
|
|||
|
|
|
|||
|
|
| Свойство | Тип | По умолчанию | Обязательное | Описание |
|
|||
|
|
|----------|-----|--------------|--------------|----------|
|
|||
|
|
| `title` | `string` | `""` | Нет | Заголовок операции в левом верхнем углу, полужирным. Длинный текст обрезается справа многоточием. |
|
|||
|
|
| `status` | `string` | `""` | Нет | Строка состояния внизу плашки. Показывается только когда `detail` пуст. |
|
|||
|
|
| `fraction` | `double` | `-1` | Нет | Доля выполнения от `0` до `1`. Значение `-1` означает «итог ещё неизвестен»: вместо процентов выводится многоточие, а полоса остаётся пустой. |
|
|||
|
|
| `detail` | `string` | `""` | Нет | Необязательная вторая строка подробностей — мегабайты у загрузки, путь у архивации. Если задана, вытесняет `status`. Длинный текст обрезается посередине, чтобы у пути были видны и начало, и конец. |
|
|||
|
|
| `cancellable` | `bool` | `true` | Нет | Показывать ли крестик отмены. Ставится в `false` для операций, которые прерывать нельзя. |
|
|||
|
|
|
|||
|
|
## Сигналы
|
|||
|
|
|
|||
|
|
#### cancelRequested()
|
|||
|
|
|
|||
|
|
Пользователь нажал крестик в правом нижнем углу. Сигнал сообщает только о намерении: плашка не
|
|||
|
|
скрывает себя и не меняет своё состояние.
|
|||
|
|
|
|||
|
|
Обработчик должен сам остановить операцию в бэкенде и убрать плашку с экрана — как правило, вызвав
|
|||
|
|
соответствующий метод отмены у `LauncherBackend`; видимость плашки при этом снимется сама, потому
|
|||
|
|
что она привязана к свойству занятости бэкенда.
|
|||
|
|
|
|||
|
|
Сигнал не испускается при `cancellable: false` — в этом случае крестик скрыт.
|
|||
|
|
|
|||
|
|
## Методы
|
|||
|
|
|
|||
|
|
Собственных функций нет.
|
|||
|
|
|
|||
|
|
## Взаимодействие с другими компонентами
|
|||
|
|
|
|||
|
|
Все пять свойств плашки — точки внешней привязки. В [Main](Main.md) они связаны со свойствами
|
|||
|
|
`LauncherBackend`: у загрузки версии это группа `downloading` / `downloadProgress` /
|
|||
|
|
`downloadVersion` / `downloadStatus` / `downloadBytesDone` / `downloadBytesTotal`, у смены сборки —
|
|||
|
|
`switching` / `switchProgress` / `switchStage` / `switchStatus`. Байты в мегабайты переводит
|
|||
|
|
функция `formatMb()` главного окна, а не сама плашка.
|
|||
|
|
|
|||
|
|
Видимостью плашки управляет родитель, обычно привязывая её к тому же признаку занятости, который
|
|||
|
|
питает `fraction`. Сигнал `cancelRequested` родитель замыкает на метод отмены бэкенда.
|
|||
|
|
|
|||
|
|
## Пример использования
|
|||
|
|
|
|||
|
|
```qml
|
|||
|
|
ProgressPanel {
|
|||
|
|
anchors.left: parent.left
|
|||
|
|
anchors.bottom: parent.bottom
|
|||
|
|
anchors.margins: 16
|
|||
|
|
visible: backend.downloading
|
|||
|
|
|
|||
|
|
title: qsTr("Загрузка Minecraft %1").arg(backend.downloadVersion)
|
|||
|
|
status: backend.downloadStatus
|
|||
|
|
fraction: backend.downloadProgress
|
|||
|
|
detail: formatMb(backend.downloadBytesDone) + " / " + formatMb(backend.downloadBytesTotal)
|
|||
|
|
|
|||
|
|
onCancelRequested: backend.cancelDownload()
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
При создании этого документа использовался ИИ.
|