– Docs

Docs: Настройка проекта на C++

Mon, 01 Jan 0001 00:00:00 +0000

Установка Kirigami

Прежде чем начать, необходимо установить Kirigami на компьютере. Сделать это можно тремя способами:

Установка Kirigami из репозиториев дистрибутива Linux
Использование kde-builder
Установка Kirigami с помощью Craft

Если используется достаточно актуальный дистрибутив, например Debian Testing, последняя версия Ubuntu без долгосрочной поддержки, Fedora, openSUSE Tumbleweed или Arch, можно установить Kirigami из дистрибутива.

Если используется устаревший дистрибутив, например Debian Stable или Ubuntu LTS, для работы с этим руководством следует использовать kde-builder. Ему потребуется не более 2 ГБ дискового пространства.

Установка Kirigami из репозиториев дистрибутива Linux

Требуются компилятор C++, пакеты разработки Qt и Kirigami. Откройте терминал и выполните одну из следующих команд в зависимости от используемого дистрибутива Linux:

Kubuntu KDE Neon	sudo apt install build-essential cmake extra-cmake-modules libkirigami-dev libkf6i18n-dev libkf6coreaddons-dev libkf6iconthemes-dev qt6-base-dev qt6-declarative-dev libkf6qqc2desktopstyle-dev
Manjaro Arch	sudo pacman -S base-devel extra-cmake-modules cmake kirigami ki18n kcoreaddons breeze kiconthemes qt6-base qt6-declarative qqc2-desktop-style
OpenSUSE	sudo zypper install cmake kf6-extra-cmake-modules kf6-kirigami-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-base-devel qt6-declarative-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style
Fedora	sudo dnf install @development-tools @development-libs cmake extra-cmake-modules kf6-kirigami-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-qtbase-devel qt6-qtdeclarative-devel kf6-qqc2-desktop-style

Дополнительные сведения для других дистрибутивов можно найти в разделе Установка зависимостей для сборки.

Использование kde-builder

Настройка среды разработки с помощью kde-builder. Это даст необходимые инструменты разработки и базовые библиотеки, а также позволит собрать KDE Frameworks с нуля.

Создайте папку ~/kde/src/kirigami-tutorial. В этой папке будут размещены файлы с исходным кодом из этого учебного руководства.

Добавьте в конец файла ~/.config/kde-builder.yaml следующее:

project kirigami-tutorial:
 no-src: true

⏳ С помощью kdesrc-build…

Нажмите здесь, чтобы узнать, как это делалось с kdesrc-build

Раньше этот шаг выполнялся иначе — записью в ~/.config/kdesrc-buildrc с другим синтаксисом:

# after include ${module-definitions-dir}/kf6-qt6.ksb
module kirigami-tutorial
no-src
end module

Установка Kirigami с помощью Craft

В KDE есть собственный инструмент, позволяющий легко устанавливать большинство своих библиотек и программ: Craft. С его помощью можно установить Kirigami в Windows, Android и macOS.

Хотя Craft также доступен для Linux и FreeBSD, он предназначен только для AppImage и упаковки.

Необходимо выполнить инструкции по настройке Craft. К концу настройки должен быть запущен файл настройки окружения (craftenv.ps1 в Windows или craftenv.sh на всех остальных платформах), который предоставит оболочку терминала, где будет выполняться сборка приложения Kirigami.

После этого в терминале можно выполнить следующее:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

При первом запуске это займёт некоторое время. Если закрыть терминал, можно запустить файл настройки окружения, чтобы подготовить его заново.

Структура проекта

Хотя существуют инструменты, позволяющие легко настроить эти файлы, их предстоит создать вручную. Это позволит лучше понять компоненты, из которых будет состоять новое приложение.

Сначала создаётся папка проекта (можно использовать приведённые ниже команды). Папка будет называться kirigami-tutorial/.

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

В этой папке будут созданы папка src/ и файл CMakeLists.txt. Обычно рекомендуется размещать все основные файлы с кодом C++ в папке src/. В неё также помещается файл Main.qml, поскольку он будет запускаться вместе с исполняемым файлом.

Совет

Эту структуру файлов можно быстро создать с помощью:

mkdir -p kirigami-tutorial/src
touch kirigami-tutorial/{CMakeLists.txt,org.kde.tutorial.desktop}
touch kirigami-tutorial/src/{CMakeLists.txt,main.cpp,Main.qml}

Примечание

Если требуется автоматически собрать проект с помощью kde-builder, имя пользовательского модуля должно совпадать с именем корневой папки проекта (в нашем случае — «kirigami-tutorial»), иначе потребуется настроить source-dir или dest-dir для модуля. Предполагается, что путь к main.cpp будет таким: ~/kde/src/kirigami-tutorial/src/main.cpp.

Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 // i18nc() makes a string translatable
 // and provides additional context for the translators
 title: i18nc("@title:window", "Hello World")

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: i18n("Hello World!")
 }
 }
}

Здесь мы займёмся фронтендом приложения.

Тем, кто знаком с JavaScript, многое в QML покажется знакомым (хотя у него есть свои особенности). В документации Qt содержится обширный материал по этому языку, если возникнет желание попробовать что-то самостоятельно. В этих уроках основное внимание будет уделено коду QML, где с помощью Kirigami можно извлечь из него максимум.

Пока сосредоточимся на Main.qml. Сначала импортируем несколько важных модулей:

QtQuick — стандартная библиотека, используемая в приложениях QML.
QtQuick Controls предоставляет ряд стандартных элементов управления, которые можно использовать, чтобы сделать приложения интерактивными.
QtQuick Layouts, который предоставляет средства для размещения компонентов в окне приложения.
Kirigami, предоставляющий набор компонентов, подходящих для создания приложений, работающих на устройствах разных форм и размеров.

Примечание

Размещение импортов QtQuick Controls и Kirigami в отдельных пространствах имён с помощью ключевого слова as — рекомендуемая практика, гарантирующая, что компоненты с одинаковыми именами не будут конфликтовать. В разных источниках можно встретить другие имена для QtQuick Controls, например «QQC» или «QQC2». В этом руководстве для ясности будет использоваться «Controls».

Далее следует базовый элемент — Kirigami.ApplicationWindow, который предоставляет ряд основных возможностей, необходимых всем приложениям Kirigami. Это окно, в котором будут размещаться все страницы — основные разделы пользовательского интерфейса.

Затем свойству id окна присваивается значение «root». Идентификаторы полезны, поскольку позволяют однозначно ссылаться на компонент, даже если имеется несколько компонентов одного типа.

Кроме того, свойству title окна присваивается значение «Hello World». Можно заметить, что строка «Hello World» обёрнута в функцию i18nc(), в которой указывается как контекст строки, так и сама строка.

Примечание

Функции i18n() делают перевод приложения более простым, поскольку возвращают вариант предоставленной строки на языке пользователя (при условии, что приложение локализовано для этого языка). Англоязычный пользователь увидит заголовок окна как «Hello World», а испаноязычный — как «Hola Mundo».

Функция i18nc() основана на функции i18n() и позволяет разработчикам предоставлять переводчикам, работающим над приложением, контекст. Здесь уточняется, что компонент интерфейса — это заголовок окна приложения, поэтому перед «Hello World» добавлена строка «@title:window». Дополнительные сведения см. в руководстве программиста Ki18n.

Затем задаётся первая страница стека страниц. Большинство приложений Kirigami организованы в виде стека страниц, каждая из которых содержит связанные компоненты, подходящие для конкретной задачи. Пока всё делается просто, и используется только одна страница. pageStack — это изначально пустой стек страниц, предоставляемый Kirigami.ApplicationWindow, а с помощью pageStack.initialPage: Kirigami.Page {...} первая страница, показываемая при загрузке приложения, задаётся как Kirigami.Page. Именно на ней будет размещено всё содержимое.

Наконец, на страницу добавляется Controls.Label, позволяющий разместить текст. Чтобы выровнять надпись по центру по горизонтали и вертикали внутри родительского элемента, используется anchors.centerIn: parent. В этом случае родительским компонентом надписи является Kirigami.Page. Последнее, что нужно сделать, — задать её текст: text: i18n("Hello World!").

org.kde.tutorial.desktop

Основное назначение файлов .desktop — показывать приложение в меню запуска приложений в Linux. Ещё одна причина их использовать — значки окон в Wayland, поскольку они нужны, чтобы сообщить композитору: «это окно соответствует этому значку».

Оно должно соответствовать схеме обратного именования DNS, за которой следует расширение .desktop, например org.kde.tutorial.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


[Desktop Entry]
Name=Kirigami Tutorial
Name[ar]=درس كيريغامي
Name[ca]=Guia d'aprenentatge del Kirigami
Name[cs]=Tutoriál Kirigami
Name[eo]=Lernilo pri Kirigami
Name[es]=Tutorial de Kirigami
Name[fr]=Tutoriel pour Kirigami
Name[it]=Esercitazione di Kirigami
Name[nl]=Kirigami handleiding
Name[pt_BR]=Tutorial do Kirigami
Name[ro]=Îndrumar Kirigami
Name[ru]=Учебное руководство по Kirigami
Name[sk]=Tutoriál Kirigami
Name[sl]=Učbenik Kirigami
Name[sv]=Kirigami-handledning
Name[tr]=Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami
Name[zh_TW]=Kirigami 教學
Exec=kirigami-hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

Примечание

Значки окон и панели задач будут работать в сеансе Wayland только если файлы .desktop приложений размещены в ~/.local/share/applications или /usr/share/applications. Чтобы значки работали при выполнении этого руководства, скопируйте туда файл .desktop приложения или переключитесь на сеанс разработки, как описано в руководстве по kde-builder. У некоторых приложений KDE значки могут работать, если они уже установлены в системе.

CMakeLists.txt

Для использования выбранной в KDE системы сборки — CMake — нужны файлы CMakeLists.txt. В файле kirigami-tutorial/CMakeLists.txt будут указаны некоторые характеристики приложения. Он также включает некоторые зависимости, требующиеся для сборки проекта.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

Файл CMakeLists.txt определяет, как собирать проекты. Большая часть содержимого здесь служит лишь для первоначальной настройки проекта. Подробное построчное объяснение того, что делает этот файл CMakeLists, можно прочитать здесь.

Самое важное, что следует помнить: зависимостями сборки C++ для Qt и KDE Frameworks управляет find_package(), а зависимостями времени выполнения QML — ecm_find_qml_module(). Эти строки придётся изменить и включить в них любые дополнительные компоненты, которые решено использовать при разработке приложения.

Строка с add_subdirectory(src) указывает CMake на папку kirigami-tutorial/src/, в котором находится исходный код.

Строка с install() указывает CMake, куда устанавливать файл .desktop.

Разберём файл kirigami-tutorial/src/CMakeLists.txt в этой папке.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Этот файл состоит из пяти шагов:

создать исполняемый файл
преобразовать исполняемый файл в модуль QML, принимающий файлы QML
добавить файлы C++ и QML в исполняемый файл
связать библиотеки, необходимые для запуска исполняемого файла
установить исполняемый файл в нужное место

Когда потребуется добавить другие файлы QML, добавьте их в существующий вызов ecm_target_qml_sources(). Файлы C++, в которых используется ключевое слово QML_ELEMENT, рассматриваемое далее в уроке, можно добавить с помощью target_sources().

Теперь, когда с CMake разобрались, рассмотрим файлы, с которыми предстоит работать большую часть времени.

main.cpp

Файл kirigami-tutorial/src/main.cpp отвечает за «бизнес-логику» приложения. C++ удобен, поскольку гибок и быстр, хотя и сложнее других языков программирования.

Он также служит точкой входа в приложение. Обе части проекта — бэкенд и пользовательский интерфейс — настраиваются и запускаются здесь.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

Пока не нужно подробно разбирать, что делает код в main.cpp, но его роль значительно возрастёт, когда в будущем в приложение будет добавлена более сложная функциональность.

Оформление в Windows

Нажмите здесь, чтобы узнать больше

Чтобы приложение показывалось в Windows, ему необходимо задать тему значков, QStyle и стиль Qt Quick Controls как Breeze. Подробнее об этом см. в разделе Разбор main.cpp.

Чтобы забежать вперёд, можно подробнее прочитать о том, как работает main.cpp, в разделе Разбор main.cpp.

Чтобы узнать о нескольких способах улучшения кода на C++, например об использовании KAboutData для переводимых метаданных приложения, ознакомьтесь с руководством по KXmlGui.

Пока что нас интересует эта строка:

engine.loadFromModule("org.kde.tutorial", "Main");

Первый аргумент — это URI, заданный в kirigami-tutorial/src/CMakeLists.txt, а второй — имя модуля QML, который требуется использовать (Main, происходящее от имени файла Main.qml, которое должно начинаться с прописной буквы).

Старый метод

Такой альтернативный способ загрузки файлов QML может встретиться в реальном коде!

Старый способ загрузки файлов QML имел ряд недостатков, а после Qt6 стал чрезмерно многословным:

engine.load(QUrl(QStringLiteral("qrc:/qt/qml/org/kde/tutorial/qml/Main.qml")));

Приведённый выше URI ресурса Qt соответствует шаблону <resource_prefix><import_URI><optional_QML_dir><file>. В этом случае:

префикс ресурса = по умолчанию / в Qt5, /qt/qml в Qt6
import URI = /org/kde/tutorial, что соответствует URI org.kde.tutorial
необязательная папка QML = /qml, необходима, если файлы QML хранятся в папке qml/
file = файл QML

Сборка и установка приложения

Финиш уже близко. Осталось собрать и запустить приложение. Как именно это сделать, зависит от используемой платформы.

Linux или FreeBSD

Сборка с помощью kde-builder

Убедитесь, что выполнены инструкции из раздела Использование kde-builder.

Соберите необходимые зависимости сборки с помощью kde-builder, затем соберите kirigami-tutorial, выполнив следующие команды в терминале:

kde-builder kirigami ki18n kcoreaddons breeze kiconthemes qqc2-desktop-style
kde-builder kirigami-tutorial

Компиляция вручную

Перейдите в корневую папку проекта и выполните в терминале следующую команду:

cmake -B build/ --install-prefix ~/.local
cmake --build build/
cmake --install build/

Приложение будет установлено в ~/.local/bin, а его файл .desktop — в ~/.local/share/applications.

Windows

Если сборка проекта выполняется в Windows после настройки Craft, CMake должен автоматически определить нужный компилятор:

cmake -B build/
cmake --build build/
cmake --install build/

В зависимости от того, как установлен компилятор, на первом шаге может потребоваться указать генератор CMake: это зависит от того, используется ли для сборки проектов Visual Studio (msvc) или MinGW (make).

Если используется Visual Studio, то в зависимости от выбранного при установке компилятора это может быть:

cmake -B build/ -G "Visual Studio 16 2019"

Или:

cmake -B build/ -G "Visual Studio 17 2022"

При использовании MinGW:

cmake -B build/ -G "MinGW Makefiles"
cmake --build build/
cmake --install build/

В обоих случаях программа будет установлена в C:\CraftRoot\bin.

Если когда-либо возникнут сомнения относительно того, какой компилятор следует использовать при вызове cmake, выполните:

cmake -G

Будет выведен список всех доступных генераторов.

Запуск приложения

Затем запустите приложение kirigami-hello с помощью:

kirigami-hello # В Linux вручную
kde-builder --run kirigami-hello # С помощью kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # С помощью kdesrc-build
kirigami-hello.exe # В Windows

Вот и всё! Теперь перед глазами появится самое первое приложение Kirigami.

Чтобы запустить новое приложение QML в мобильном режиме, можно использовать QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Если проект был собран вручную с помощью CMake и по какой-то причине его требуется удалить, можно выполнить:

cmake --build build/ --target uninstall

Примечание

В следующий раз, когда потребуется создать нужные файлы и папки, можно воспользоваться KAppTemplate или KDevelop, чтобы автоматически создать подходящий проект для начала работы. Они доступны в репозиториях каждого крупного дистрибутива. Эти приложения также создают файлы с метаданными AppStream и файл .desktop, содержащий сведения о том, как приложение должно показываться в меню запуска приложений Linux.

Благодаря магии CMakeLists можно также использовать такие IDE, как KDevelop или QtCreator, для разработки этого приложения в комфортной среде с минимальными усилиями.

Docs: Настройка проекта на Python

Mon, 01 Jan 0001 00:00:00 +0000

Предварительные требования

Прежде чем начать, необходимо установить Kirigami и PySide на компьютере.

Manjaro Arch

sudo pacman -S python-pipx python-pyqt6 pyside6 kirigami flatpak-builder qqc2-desktop-style appstream

OpenSUSE

sudo zypper install python3-pipx python3-qt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style AppStream-compose

Fedora

sudo dnf install pipx python3-pyqt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style appstream-compose

Если в дистрибутиве установлены старые пакеты PySide6 или PyQt6, для работы с этим руководством можно использовать раздел Сборка программного обеспечения с помощью distrobox.

Структура проекта

Сначала создаётся папка проекта (можно использовать приведённые ниже команды). Папка будет называться kirigami_python/.

kirigami_python/
├── README.md
├── LICENSE.txt
├── MANIFEST.in # Добавление файлов QML
├── pyproject.toml # Основной файл управления проектом
├── org.kde.kirigami_python.desktop
└── src/
├── __init__.py # Импорт папки src/ в качестве пакета
├── __main__.py # Указание app в качестве точки входа
├── app.py
└── qml/
└── Main.qml

Имя пакета будет kirigami_python, «исполняемый файл» (консольный сценарий) будет называться kirigami_hello, а точкой входа будет app.

Совет

Чтобы быстро создать такую структуру папок, просто выполните: mkdir -p kirigami_python/src/qml/.

Более полный проект, в котором структура этих файлов рассматривается подробнее, описан в разделе Весь проект на Python + Kirigami.

pyproject.toml

Современным приложениям Python достаточно одного файла TOML, чтобы указать все метаданные, сведения о пакете и зависимости в соответствии с PEP 621. Приведённый ниже пример послужит хорошей отправной точкой для приложения, и его можно расширить в дальнейшем.

Большая часть содержимого этого файла — шаблонный код, а более полную его версию можно увидеть в разделе Python с Kirigami: общая структура.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "kirigami_python"
version = "0.1"
authors = [
 {name = "Konqi", email = "konqi@example.com"}
]
classifiers = [
 "Development Status :: 5 - Production/Stable",
 "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
 "Intended Audience :: End Users/Desktop",
 "Topic :: Utilities",
 "Programming Language :: Python",
 "Operating System :: POSIX :: Linux",
]

[project.scripts]
kirigami_hello = "kirigami_python.app:main"

[tool.setuptools]
packages = ["kirigami_python"]
package-dir = {kirigami_python = "src"}
include-package-data = true

[tool.setuptools.data-files]
"share/applications" = ["org.kde.kirigami_python.desktop"]

Обратите внимание на выделенные строки. Как упоминалось в разделе Структура проекта, имя пакета — kirigami_python, имя исполняемого файла — kirigami_hello, а имя точки входа — app. В частности, следует отметить следующее:

Сценарий проекта состоит из сценария точки входа, который будет создан setuptools для запуска приложения, в этом случае — kirigami_hello.
Сценарий созданного проекта kirigami_hello запускает функцию main() в сценарии app.py пакета kirigami_python.
По умолчанию package-dir для проектов Python обычно является корневой папкой. В этом случае он переопределяется вложенной папкой src/, чтобы тот выступал в роли корневой папки пакета.
Именно из-за package-dir созданный сценарий проекта выполняет kirigami_python → app, а не kirigami_python → src → app.
package-dir также объясняет, почему вызов importlib.resources.files() в app.py возвращает kirigami_python → qml → Main.qml, а не kirigami_python → src → qml → Main.qml.

Подробнее см. в разделе Прямой запуск, запуск в качестве модуля и в качестве консольного сценария.

org.kde.kirigami_python.desktop

Оно должно соответствовать схеме обратного именования DNS, за которой следует расширение .desktop, например org.kde.kirigami_python.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


[Desktop Entry]
Name=Kirigami Tutorial in Python
Name[ar]=درس كيريغامي ببايثون
Name[ca]=Guia d'aprenentatge del Kirigami en Python
Name[eo]=Lernilo pri Kirigami en Python
Name[es]=Tutorial de Kirigami en Python
Name[fr]=Tutoriel pour Kirigami en Python
Name[it]=Esercitazione di Kirigami in Python
Name[nl]=Kirigami handleiding in Python
Name[pt_BR]=Tutorial do Kirigami em Python
Name[ro]=Îndrumar Kirigami în Python
Name[ru]=Учебное руководство по Kirigami на Python
Name[sk]=Tutoriál Kirigami v Pythone
Name[sl]=Učbenik Kirigami v Pythonu
Name[sv]=Kirigami-handledning i Python
Name[tr]=Python ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Python
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

Примечание

MANIFEST.in

Этот файл — просто объявление дополнительных файлов исходного кода, которые должны присутствовать в пакете при запуске приложения. Python по умолчанию не включает файлы QML в пакеты, и они должны быть доступны, чтобы приложение работало.

1

include src/qml/*.qml

src/app.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


#!/usr/bin/env python3

import os
import sys
import signal
from importlib.resources import files

from PySide6.QtGui import QGuiApplication
from PySide6.QtCore import QUrl
from PySide6.QtQml import QQmlApplicationEngine

def main():
 app = QGuiApplication(sys.argv)
 engine = QQmlApplicationEngine()

 """Needed to close the app with Ctrl+C"""
 signal.signal(signal.SIGINT, signal.SIG_DFL)

 """Needed to get proper KDE style outside of Plasma"""
 if not os.environ.get("QT_QUICK_CONTROLS_STYLE"):
 os.environ["QT_QUICK_CONTROLS_STYLE"] = "org.kde.desktop"

 base_path = files('kirigami_python').joinpath('qml', 'Main.qml')
 url = QUrl(f"{base_path}")
 engine.load(url)

 app.exec()

if __name__ == "__main__":
 main()

Так как это приложение с графическим интерфейсом, нужно, чтобы главная функция выполнялась только при запуске сценария, а не при его импорте, поэтому в конце файла требуется условие if __name__ == "__main__". Дополнительные сведения см. в разделе Прямой запуск, запуск в качестве модуля и в качестве консольного сценария.

Создаётся QGuiApplication и инициализируется движок QML, а с помощью QGuiApplication.exec() приложение продолжает работу до закрытия. Затем importlib.resources.files() получает путь к файлу, присутствующему в пакете, а именно к Main.qml. С помощью этого пути файл QML загружается в движок QML как основная точка входа для интерфейса приложения.

src/init.py

Создайте пустой файл kirigami_python/src/__init__.py. Этот файл нужен лишь для того, чтобы папку можно было импортировать как пакет.

touch __init__.py

src/main.py

Создайте файл kirigami_python/src/__main__.py со следующим содержимым:

1
2
3


from . import app

app.main()

Он просто добавляет содержимое текущей папки (src/) и импортирует его как модуль с именем app, после чего сразу запускает функцию main() приложения.

src/qml/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 title: "Hello World"

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: "Hello World!"
 }
 }
}

Здесь мы займёмся фронтендом приложения.

Пока сосредоточимся на Main.qml. Сначала импортируем несколько важных модулей:

QtQuick — стандартная библиотека, используемая в приложениях QML.
QtQuick Controls предоставляет ряд стандартных элементов управления, которые можно использовать, чтобы сделать приложения интерактивными.
QtQuick Layouts, который предоставляет средства для размещения компонентов в окне приложения.
Kirigami, предоставляющий набор компонентов, подходящих для создания приложений, работающих на устройствах разных форм и размеров.

Примечание

Также свойству title окна присваивается значение «Hello World».

Запуск приложения

Консольный сценарий kirigami_hello можно запустить без предварительной установки:

pipx run --system-site-packages --spec . kirigami_hello

Флаг --system-site-packages нужен, чтобы Python получил доступ к пакетам Python из дистрибутива. Это необходимо, поскольку Kirigami и PySide должны быть собраны с одной и той же версией Qt, чтобы работать, — а это так, когда оба они входят в состав дистрибутива.

Флаг --spec определяет путь к исходному коду или пакету wheel, содержащему программу, а kirigami_hello — исполняемый сценарий, который нужно запустить.

Для сборки и установки пакета Python выполните:

pipx install --force --system-site-packages .

Пакет будет установлен в ~/.local/share/pipx/venvs/kirigami-python, а исполняемый сценарий — в ~/.local/bin/kirigami_hello.

Использование pipx вместо pip

В отличие от раздела Python с Kirigami: создание пакета Python, в этом руководстве для упрощения запуска и установки проекта использовался pipx. Те же шаги можно выполнить вручную с помощью venv, build и pip, как в более полном руководстве.

pipx полезен и рекомендован согласно PEP 668 для запуска приложений Python, а pip универсален и подходит также для импортируемых модулей Python.

После этого приложение запускается командой:

kirigami_hello

Чтобы запустить новое приложение QML в мобильном режиме, можно использовать QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Вот и всё! Теперь перед глазами появится самое первое приложение Kirigami.

Docs: Настройка проекта на Rust

Mon, 01 Jan 0001 00:00:00 +0000

Установка Kirigami

Прежде чем начать, необходимо установить Kirigami и Rust на компьютере.

Manjaro Arch

sudo pacman -S cargo cmake extra-cmake-modules kirigami breeze qqc2-desktop-style

OpenSUSE

sudo zypper install cargo cmake kf6-extra-cmake-modules kf6-kirigami-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style-devel

Fedora

sudo dnf install cargo cmake extra-cmake-modules kf6-kirigami-devel kf6-qqc2-desktop-style

Дополнительные сведения для других дистрибутивов можно найти в разделе Установка зависимостей для сборки.

Структура проекта

Сначала создаётся папка проекта (можно использовать приведённые ниже команды). Папка будет называться kirigami_rust/. Структура проекта будет такой:

kirigami_rust/
├── CMakeLists.txt
├── Cargo.toml
├── build.rs
├── org.kde.kirigami_rust.desktop
└── src/
├── main.rs
└── qml/
└── Main.qml

В этом проекте CMake будет использоваться для вызова Cargo, который, в свою очередь, соберёт проект.

О CMake и Cargo

Это не традиционный способ сборки проекта на Rust: технически для его сборки требуется только Cargo, обычно с помощью cargo build и cargo run.

Однако для установки приложений для рабочего стола требуется CMake (или его аналог, например Meson, используемый в GNOME, или Just, используемый в COSMIC), поскольку в Cargo отсутствуют возможности, нужные для установки графических приложений для рабочего стола.

Проект будет называться kirigami_rust и создаст исполняемый файл с именем kirigami_hello.

💡 Совет

Эту структуру файлов можно быстро создать с помощью команды: mkdir -p kirigami_rust/src/qml/.

org.kde.kirigami_rust.desktop

Оно должно соответствовать схеме обратного именования DNS, за которой следует расширение .desktop, например org.kde.kirigami_rust.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


[Desktop Entry]
Name=Kirigami Tutorial in Rust
Name[ar]=درس كيريغامي برست
Name[ca]=Guia d'aprenentatge del Kirigami en Rust
Name[es]=Tutorial de Kirigami en Rust
Name[fr]=Tutoriel pour Kirigami en Rust
Name[it]=Esercitazione di Kirigami in Rust
Name[nl]=Kirigami handleiding in Rust
Name[pt_BR]=Tutorial do Kirigami em Rust
Name[ro]=Îndrumar Kirigami în Rust
Name[ru]=Учебное руководство по Kirigami на Rust
Name[sk]=Tutoriál Kirigami v Ruste
Name[sl]=Učbenik Kirigami v Rustu
Name[sv]=Kirigami-handledning i Rust
Name[tr]=Rust ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Rust
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

CMakeLists.txt

Файл CMakeLists.txt будет использоваться для запуска Cargo и установки необходимых файлов вместе с приложением. Он также предоставляет ряд удобных возможностей, например гарантирует установку Kirigami во время сборки и указывает дистрибутивам Linux установить необходимые зависимости вместе с приложением.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


cmake_minimum_required(VERSION 3.28)

project(kirigami_rust)

find_package(ECM 6.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
include(KDEInstallDirs)
include(ECMUninstallTarget)

include(ECMFindQmlModule)
ecm_find_qmlmodule(org.kde.kirigami REQUIRED)
find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)

add_custom_target(kirigami_rust
 ALL
 COMMAND cargo build --target-dir ${CMAKE_CURRENT_BINARY_DIR}
)

install(
 PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/debug/kirigami_hello
 DESTINATION ${KDE_INSTALL_BINDIR}
)

install(FILES org.kde.kirigami_rust.desktop DESTINATION ${KDE_INSTALL_APPDIR})

Первым делом в проект добавляется Extra CMake Modules (ECM) из KDE, чтобы можно было использовать ecm_find_qml_module для проверки наличия Kirigami при попытке сборки приложения, а если его нет — немедленно прервать сборку. Ещё одна полезная возможность ECM — ECMUninstallTarget, позволяющая при желании легко удалить приложение средствами CMake.

Также используется find_package() из CMake, чтобы убедиться в наличии qqc2-desktop-style — стиля QML KDE для рабочего стола. Это одна из двух причин использования CMake в этом руководстве.

Проекты на Rust обычно собираются с помощью Cargo, и здесь будет так же. Создаётся цель, которая при выполнении просто запускает Cargo, и помечается меткой ALL, чтобы она собиралась по умолчанию. Cargo соберёт исполняемый файл в папке сборки CMake (обычно build/).

Подробнее о CMake, целях и папке сборки можно прочитать в разделе Сборка программного обеспечения KDE вручную.

После этого остаётся лишь установить исполняемый файл kirigami_rust, созданный Cargo в папке сборки, в BINDIR, который обычно указывает на /usr/bin, /usr/local/bin или ~/.local/bin. Кроме того, в APPDIR, обычно /usr/share/applications или ~/.local/share/applications, устанавливается требуемый файл .desktop. Это вторая причина использования CMake в этом руководстве.

Дополнительные сведения о том, куда устанавливается программное обеспечение KDE, можно найти в разделе Сборка программного обеспечения KDE вручную: шаг установки.

Теперь, когда с CMake разобрались, рассмотрим файлы, с которыми предстоит работать большую часть времени.

Cargo.toml

Далее приведён очень простой Cargo.toml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


[package]
name = "kirigami_hello"
version = "0.1.0"
authors = [ "Konqi the Konqueror <konqi@kde.org>" ]
edition = "2024"
license = "GPLv3"

[dependencies]
cxx = "1.0.194" # Check the latest available version at https://crates.io/crates/cxx

# Check the latest available version of all related cxx-qt crates at https://crates.io/crates/cxx-qt
cxx-qt = "0.8.1"
cxx-qt-lib = { version="0.8.1", features = ["qt_full"] }
cxx-qt-lib-extras = "0.8.1"

[build-dependencies]
# The link_qt_object_files feature is required for statically linking Qt 6.
cxx-qt-build = { version = "0.8.1", features = [ "link_qt_object_files" ] }

Он состоит из метаданных проекта и списка зависимостей, которые Cargo загрузит автоматически, а именно cxx и cxx-qt, необходимых для запуска приложений Qt, написанных на Rust.

build.rs

Если в C++ элементы QML обычно регистрируются с помощью QML_ELEMENT и ecm_add_qml_module с использованием декларативной регистрации, то в Rust его потребуется объявить в файле сценария сборки build.rs:

1
2
3
4
5
6
7
8
9


use cxx_qt_build::{CxxQtBuilder, QmlModule};

fn main() {
 CxxQtBuilder::new_qml_module(
 QmlModule::new("org.kde.tutorial")
 .qml_files(&["src/qml/Main.qml"])
 )
 .build();
}

Это необходимо, чтобы файл QML был доступен в точке входа приложения main.rs.

src/main.rs

Файл kirigami_rust/src/main.rs инициализирует проект, а затем загружает файл QML, который будет представлять собой пользовательский интерфейс приложения.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


use cxx_qt_lib::{QGuiApplication, QQmlApplicationEngine, QQuickStyle};
use cxx_qt_lib_extras::QApplication;
use std::env;

fn main() {
 let mut app = QApplication::new();
 let mut engine = QQmlApplicationEngine::new();

 // To associate the executable to the installed desktop file
 QGuiApplication::set_desktop_file_name(&"org.kde.kirigami_rust".into());
 // To ensure the style is set correctly
 let style = env::var("QT_QUICK_CONTROLS_STYLE");
 if style.is_err() {
 QQuickStyle::set_style(&"org.kde.desktop".into());
 }

 if let Some(engine) = engine.as_mut() {
 engine.load(&"qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml".into());
 }

 if let Some(app) = app.as_mut() {
 app.exec();
 }
}

Первая часть, помеченная макросом Rust #[cxx_qt::bridge], просто создаёт фиктивный QObject из фиктивной структуры Rust. Это нужно лишь для того, чтобы завершить использование QmlModule в предыдущем сценарии сборки build.rs. В будущем уроке, посвящённом тому, как сделать код Rust доступным для QML, ей будет отведена более важная роль, но пока её можно игнорировать.

После этого начинается важная часть:

Строки 12–13 импортируют необходимые библиотеки Qt, предоставляемые через cxx-qt.

Сначала создаётся новый экземпляр QApplication, затем в строках 20–26 выполняются несколько интеграций.

Затем идёт часть, которая непосредственно создаёт окно приложения:

Длинный URL qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml соответствует файлу Main.qml согласно системе ресурсов Qt и следует схеме: <resource_prefix><import_URI><QML_dir><file>.

Иными словами: префикс ресурса по умолчанию qrc:/qt/qml/ + URI импорта org/kde/tutorial (задан в build.rs, разделён косыми чертами вместо точек) + папка QML src/qml/ + файл QML Main.qml.

src/qml/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 title: "Hello World"

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: "Hello World!"
 }
 }
}

Здесь мы займёмся фронтендом приложения.

Пока сосредоточимся на Main.qml. Сначала импортируем несколько важных модулей:

QtQuick — стандартная библиотека, используемая в приложениях QML.
QtQuick Controls предоставляет ряд стандартных элементов управления, которые можно использовать, чтобы сделать приложения интерактивными.
QtQuick Layouts, который предоставляет средства для размещения компонентов в окне приложения.
Kirigami, предоставляющий набор компонентов, подходящих для создания приложений, работающих на устройствах разных форм и размеров.

Примечание

Также свойству title окна присваивается значение «Hello World».

Затем задаётся первая страница стека страниц. Большинство приложений Kirigami организованы в виде стека страниц, каждая из которых содержит связанные компоненты, подходящие для конкретной задачи. Пока всё делается просто, и используется только одна страница. pageStack — это изначально пустой стек страниц, предоставляемый Kirigami.ApplicationWindow, а с помощью pageStack.initialPage: Kirigami.Page {...} первая страница, показываемая при загрузке приложения, задаётся как Kirigami.Page. Эта страница будет содержать всё содержимое.

Сборка и установка приложения

Созданный исполняемый файл kirigami_hello должен находиться в build/debug/kirigami_hello. Его можно запустить напрямую или с помощью cargo run, но у него не будет значка окна. Чтобы исправить это, сначала устанавливается приложение.

Выполните следующее:

cmake -B build --install-prefix ~/.local
cmake --build build/
cmake --install build/

С помощью первой команды CMake выполнит поиск Kirigami и qqc2-desktop-style.

С помощью второй команды CMake соберёт цель kirigami_rust, которая просто вызывает cargo build --target-dir build/. Этот шаг займёт некоторое время, но при следующем выполнении второй команды CMake сборка пройдёт быстрее или компилировать вообще не потребуется.

На третьем шаге CMake установит исполняемый файл kirigami_hello в ~/.local/bin/kirigami_hello и файл .desktop в ~/.local/share/applications, а в меню появится новый пункт «Kirigami Tutorial in Rust».

Откройте пункт меню — и готово! Теперь перед глазами появится самое первое приложение Kirigami.

Чтобы запустить новое приложение QML в мобильном режиме, можно использовать QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Если проект был собран вручную с помощью CMake и по какой-то причине его требуется удалить, можно выполнить:

cmake --build build/ --target uninstall

Docs: Объяснение страниц

Mon, 01 Jan 0001 00:00:00 +0000

Наше приложение

В предыдущем руководстве удалось настроить, собрать и скомпилировать первое приложение Kirigami. Когда основы освоены, можно приступить к созданию полнофункционального приложения.

Эти руководства будут посвящены созданию приложения, позволяющего пользователю видеть, сколько дней осталось до выбранного события.

Также рекомендуется ознакомиться с Kirigami Gallery, где представлен ряд полезных примеров интерфейса.

В этом разделе основное внимание будет уделено страницам — одному из ключевых структурных элементов любого приложения Kirigami.

Страницы

Приложения Kirigami обычно организуются в страницы с помощью Kirigami.Page. Страницы — это различные «экраны» приложения. Для отдельных аспектов взаимодействия приложения стоит предусмотреть отдельную страницу, а чтобы упростить задачу, можно создать отдельные файлы QML для каждой страницы.

Страницы организуются в стек страниц, куда их можно помещать и откуда извлекать. На телефоне показывается только самая верхняя страница, тогда как на большом экране (настольный компьютер или планшет) при желании можно показывать несколько страниц рядом друг с другом.

Одна страница на телефоне

Две страницы рядом друг с другом на рабочем столе

Примечание

Kirigami.Page наследуется от Controls.Page, поэтому можно использовать и свойства последнего.

При просмотре документации по API QML следует также обратить внимание на функции и свойства, унаследованные от рассматриваемого API.

Вернёмся к файлу Main.qml, созданному в предыдущем руководстве:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 // i18nc() makes a string translatable
 // and provides additional context for the translators
 title: i18nc("@title:window", "Hello World")

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: i18n("Hello World!")
 }
 }
}

Сделаем так, чтобы при запуске приложение открывало нашу Kirigami.Page. Всё, что в неё включено, — это надпись с текстом «Hello World», но вскоре всё это будет немного приукрашено.

Замысел приложения состоит в том, чтобы показывать пользователю множество обратных отсчётов. Проблема обычной Kirigami.Page в том, что она имеет фиксированный вертикальный размер, поэтому вместо неё можно использовать Kirigami.ScrollablePage, которая уже оснащена встроенной полосой прокрутки.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")
 }
}

Страницы Kirigami также имеют аккуратные заголовки, размещённые на панели инструментов, которые быстро показывают пользователю, на какой странице он находится. Всё, что нужно сделать, — задать заголовок страницы с помощью свойства title у Kirigami.ScrollablePage. В этом случае была использована одна из функций i18nc(), рассмотренных в предыдущем руководстве.

Примечание

Страницу можно также определить в отдельном документе QML. Для этого нужно создать новый файл QML, например kirigami-tutorial/src/qml/StartPage.qml, добавить его в файл kirigami-tutorial/src/CMakeLists.txt и задать первую страницу окна для его загрузки, например так:

pageStack.initialPage: Qt.resolvedUrl("StartPage.qml")

pageStack.initialPage задаёт начальную страницу стека страниц приложения, а Qt.resolvedUrl преобразует относительный URL-адрес файла QML в абсолютный.

Дополнительные сведения об альтернативных структурах страниц приведены в документации Kirigami.

Docs: Компоновки, списки и карточки

Mon, 01 Jan 0001 00:00:00 +0000

Размещение содержимого

Теперь, когда работа страниц понятна, пора наполнить их содержимым. Далее будут рассмотрены несколько важных компонентов и элементов компоновки, которые пригодятся при разработке приложения.

К концу этого раздела получится приложение с аккуратным внешним видом.

ListViews

Если доводилось пользоваться Discover, NeoChat или «Параметрами системы» Plasma, то наверняка встречался ListView. Проще говоря, он позволяет выводить данные в виде списка.

pageStack.initialPage: Kirigami.ScrollablePage {
 // …
 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
}

Звучит загадочно, но не стоит беспокоиться. Начнём с самого начала.

Этот компонент добавляется в Kirigami.ScrollablePage из предыдущего руководства.

Здесь используется Kirigami.CardsListView — это ListView, позволяющий легко показывать карточки в виде списка. Однако ListView созданы для показа данных, взятых из модели, — для автоматического заполнения из набора данных, на который они указывают. Именно для этого служит свойство model: в этом примере оно указывает на kountdownModel.

Модель

Kirigami.ApplicationWindow {
 // …
 ListModel {
 id: kountdownModel
 // Каждый ListElement — это элемент списка, содержащий информацию.
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }
 // …
}

Наш kountdownModel добавляется в Kirigami.ApplicationWindow из предыдущего руководства.

Модель определяет способ структурирования записи данных. Наша kountdownModel пока будет состоять только из одного элемента. Взглянув на ListElement выше, можно увидеть, как структурированы данные kountdownModel: она содержит имя, описание и дату. Это не догма, и в модели могут быть данные других типов. Первые два значения — просто строки, а третье — число, используемое в качестве заполнителя.

Примечание

Поскольку QML построен на основе JavaScript, многие возможности этого языка доступны для использования в файлах QML. Однако перед переменными QML нужно указывать property, если только они не находятся внутри блока кода JS. Подробнее об этом можно прочитать на этой странице.

Модели также полезны тем, что их можно изменять с помощью нескольких методов. Некоторые важные из них:

ListModel.append(yourobject: jsobject) добавляет объект JavaScript (JSObject) yourobject в ListModel и помещает его после последнего элемента модели. Чтобы это произошло правильно, необходимо указать объект JSObject с правильными свойствами и типами данных.
ListModel.get(index: int) возвращает JSObject по указанному индексу.
ListModel.remove(index: int, count: int) удаляет JSObject в позиции index и далее столько объектов, сколько указано в count (значение 1 означает удаление только JSObject в указанной позиции)
ListModel.set(index: int, yourobject: jsobject) изменяет элемент в позиции index значениями, заданными в yourobject. Действуют те же правила, что и для append().

Делегаты

В то время как kountdownModel содержит данные, которые будут показаны, kountdownDelegate управляет тем, как эти данные будут показаны в ListView. Для этого используется Kirigami.CardsListView, предназначенный для показа делегатов карточного типа, а сами делегаты визуально представляются с помощью Kirigami.AbstractCard.

Делегаты автоматически получают свойства экземпляров ListElement, указанных в модели. Поэтому можно просто обращаться к их свойствам name, description и date, как к обычным переменным внутри делегата.

Создание карточки делегата

Component, который будет представлять делегат, можно добавить внутрь Kirigami.ApplicationWindow. Затем будет рассмотрено, что делает каждая часть компонента-делегата.

Kirigami.ApplicationWindow {
 // …
 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 // implicitWidth/Height задают естественную ширину/высоту элемента, если ширина или
 // высота не указаны. Параметр ниже определяет предпочтительный размер компонента
 // исходя из его содержимого
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18nc("@action:button","Edit")
 // onClicked: будет сделано… скоро!
 }
 }
 }
 }
 }
 // …
}

implicitWidth и implicitHeight

В первой части рассматривается управление шириной и высотой компонента:

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 // …
 }
 }
}

Рассматривая наш Kirigami.AbstractCard, можно заметить, что первыми задаются свойства implicitWidth и implicitHeight. Им присвоены значения delegateLayout.implicitWidth и delegateLayout.implicitHeight, то есть implicitWidth и implicitHeight элемента GridLayout.

Неявные ширина и высота — это свойства, доступные в любом Item, которые служат подсказками и задаются по умолчанию либо как запасной вариант, если для этих компонентов не заданы явные ширина и высота. По умолчанию эти значения равны 0x0, поэтому очень важно задавать их в обычных компонентах Item, как показано выше.

Здесь implicitWidth и implicitHeight нашей Kirigami.AbstractCard заданы равными соответствующим свойствам расположенного ниже GridLayout, чтобы содержимое не выходило за пределы карточки. Так карточка занимает ровно столько места, сколько необходимо для её содержимого.

Компоновки

GridLayout находится внутри компонента Item, предоставленного для свойства contentItem. Именно этот Item содержит то, что будет показано в карточке.

Также необходимо выбрать компоновку для компонентов, чтобы они не нагромождались друг на друга. Можно выбрать один из трёх основных типов:

ColumnLayout размещает компоненты вертикально, в один столбец
RowLayout размещает компоненты горизонтально в один ряд
GridLayout размещает компоненты в сетке с выбранной компоновкой

С помощью ColumnLayout и RowLayout достаточно лишь поместить свои компоненты внутрь компонента Layout. Как видно, здесь используется GridLayout, что требует немного больше ручной работы.

GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2
 // …
}

Первое, что видно, — это наши anchors. Система якорей QtQuick предоставляет удобный способ размещения компонентов в определённых частях родительского компонента. Наш GridLayout закреплён за левым, верхним и правым краями родительской карточки, благодаря чему содержимое растягивается на всю карточку.

Далее задаётся расстояние между строками и столбцами внутри сетки, чтобы компоненты не сбивались в кучу. Kirigami предоставляет ряд удобных предопределённых единиц, которые можно использовать для этой цели:

Единица Kirigami	Пиксели
smallSpacing	4px
largeSpacing	8px
gridUnit	18px

Примечание

Группа визуального дизайна KDE (VDG) приводит гораздо больше сведений о различных единицах, определённых в Plasma и Kirigami, в Руководстве по проектированию пользовательского интерфейса.

Напомним, что root — идентификатор нашего Kirigami.ApplicationWindow. Он предоставляет свойство wideScreen, используемое для определения того, является ли экран текущего устройства широкоэкранным (то есть монитором компьютера или телефоном в альбомной ориентации). Здесь используется тернарный условный оператор, чтобы изменять число столбцов в сетке в зависимости от используемого экрана: если экран широкоэкранный, сетка будет содержать 4 столбца, иначе — 2.

Внутренние компоненты

Можно было бы просто создать три надписи в компоненте-делегате и на этом остановиться, но это выглядело бы не очень красиво. Будут задействованы несколько более удобных компонентов:

GridLayout {
 // …
 Kirigami.Heading {
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }

 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }

 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }

 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18nc("@action:button","Edit")
 }
}

Внешний вид пользовательской карточки

Слева — Kirigami.Heading: использует date из ListElement в качестве заголовка первого уровня.
В центре — ColumnLayout: содержит Kirigami.Heading, показывающий название задачи; Kirigami.Separator, обеспечивающий горизонтальную линию; и Controls.Label, показывающий необязательное описание задачи. Последние два компонента имеют свойство visible, которое проверяет, пусто ли описание, и показывает компоненты в зависимости от результата description.length > 0.
Справа — Controls.Button: кнопка, которая что-то сделает… скоро!

Наше приложение на данный момент

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 // ListModel needed for ListView, contains elements to be displayed
 ListModel {
 id: kountdownModel
 // Each ListElement is an element on the list, containing information
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 // Level determines the size of the heading
 level: 1
 text: date
 }

 // Layout for positioning elements vertically
 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 // Horizontal rule
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 // Labels contain text
 Controls.Label {
 Layout.fillWidth: true
 // Word wrap makes text stay within box and shift with size
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 // Column spanning within grid layout (vertically in this case)
 Layout.columnSpan: 2
 text: i18nc("@action:button","Edit")
 //onClicked: to be done...
 }
 }
 }
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // List view for card elements
 Kirigami.CardsListView {
 id: cardsView
 // Model contains info to be displayed
 model: kountdownModel
 // Delegate is how the information will be presented in the ListView
 delegate: kountdownDelegate
 }
 }
}

Вот и базовая карточка!

Эти шаги заложили основу для добавления всей функциональности в приложение.

Docs: Добавление действий

Mon, 01 Jan 0001 00:00:00 +0000

Резюме

Пока что создано простое приложение, которое умеет показывать карточки. Однако сейчас нет способа добавить новые карточки в представление карточек.

В этом руководстве рассматриваются действия Kirigami. С их помощью можно единообразно, быстро и с учётом требований доступности добавить интерактивность в приложение.

Действия

Kirigami.Action инкапсулирует действие пользовательского интерфейса. Такие действия позволяют снабдить приложения легкодоступными операциями, необходимыми для их работы.

Если раньше уже доводилось пользоваться приложениями Kirigami, то наверняка приходилось сталкиваться с действиями Kirigami. На этом изображении справа от заголовка страницы показаны действия с различными значками. Действия Kirigami можно показывать несколькими способами, и они способны выполнять самые разные задачи.

Добавление обратных отсчётов

Приложение для обратного отсчёта довольно бесполезно без возможности добавлять обратные отсчёты. Создадим действие, которое позволит это сделать.

pageStack.initialPage: Kirigami.ScrollablePage {
 // Прочие свойства страницы…
 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: kountdownModel.append({
 name: "Kirigami Action added card!",
 description: "Congratulations, your Kirigami Action works!",
 date: 1000
 })
 }
 ]
 // …
}

Kirigami.Action размещается на главной странице из предыдущих руководств. При желании на страницу можно добавить другие действия (и даже вложить действия в действия!).

Квадратные скобки [], использованные выше, похожи на массивы JavaScript, то есть в них можно передать один или несколько элементов, разделённых запятой:

// Пример обычного массива компонентов в JavaScript:
variable: [ component1, component2 ]
// Передача массива действий Kirigami в QML:
actions: [ Kirigami.Action {}, Kirigami.Action {} ]

Свойства id и text должны быть знакомы по предыдущим руководствам. Однако унаследованное свойство Action.icon представляет интерес: это объект с несколькими свойствами, позволяющими показывать определённые значки для действий. К счастью, чтобы использовать значки KDE, достаточно указать свойство name для свойства icon — icon.name.

Просмотр доступных значков

Нажмите здесь, чтобы узнать, как проверить доступные значки в системе

Icon Explorer — приложение KDE, позволяющее просматривать все значки, которые можно использовать в приложении. Оно предоставляет ряд полезных возможностей: предварительный просмотр внешнего вида значков в различных установленных оформлениях, предварительный просмотр значков разных размеров и многое другое. Этот инструмент может пригодиться при выборе значков для приложения.

Многие значки KDE соответствуют спецификации именования значков FreeDesktop. Поэтому может оказаться полезным также обратиться к сайту проекта FreeDesktop, где перечислены все имена значков, совместимые с разными рабочими средами.

Обработчик сигнала onTriggered — самый важный. Именно это сделает наше действие при его использовании. Заметьте, что в примере используется метод kountdownModel.append модели kountdownModel, созданной в предыдущем руководстве. Этот метод позволяет добавить новый элемент в модель списка. Ему передаётся объект (обозначен фигурными скобками {}) с нужными свойствами для обратных отсчётов (name, description и заполнитель date).

При каждом нажатии кнопки «Add kountdown» в правом верхнем углу добавляется собственный обратный отсчёт.

Мобильная версия

Глобальная выдвижная панель

Следующий компонент — Kirigami.GlobalDrawer. Он показывается в виде меню-гамбургера. По умолчанию он открывает боковую панель, что особенно удобно на мобильных устройствах: чтобы её открыть, достаточно провести пальцем от края экрана. Глобальные выдвижные панели удобны для глобальной навигации и действий. Создадим простую глобальную выдвижную панель с кнопкой «Выход».

Kirigami.ApplicationWindow {
 id: root
 // Другие свойства окна…
 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
 // …
}

Здесь глобальная выдвижная панель размещается внутри окна приложения. Основное свойство, на которое следует обратить внимание, — GlobalDrawer.actions, представляющее собой массив компонентов Kirigami.Action. Это действие имеет подходящий значок и при срабатывании выполняет функцию Qt.quit(), закрывая приложение.

Поскольку глобальная выдвижная панель пока остаётся простой, свойство GlobalDrawer.isMenu задаётся значение true. Тогда глобальная выдвижная панель показывается как обычное меню приложения и занимает меньше места, чем стандартная выдвижная панель.

Глобальная выдвижная панель

Глобальная выдвижная панель как меню

Совет

На странице компонентов на основе действий этой документации приведены более подробные сведения о действиях Kirigami и о том, как их использовать.

Действия зависят от контекста

Компоненты Kirigami устроены так, что место, куда помещаются действия Kirigami, имеет значение. Как показано выше, если добавить действия в Kirigami.Page, Kirigami.ScrollablePage или любой другой производный компонент страницы, в настольном режиме они показываются в правой части заголовка, а в мобильном — внизу.

Аналогично, если добавить действия Kirigami в Kirigami.GlobalDrawer, они появятся в получившейся выдвижной панели или меню.

Другие примеры действий Kirigami, которые показываются по-разному в зависимости от родительского компонента:

Kirigami.ContextDrawer — Руководство по ContextDrawer
Kirigami.AbstractCard и производные от него — Руководство по карточкам
Kirigami.Dialog и производные — Руководство по диалогам
Kirigami.ActionToolBar — Руководство по ActionToolBar

Среди других компонентов Kirigami.

Наше приложение на данный момент

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 // Global drawer element with app-wide actions
 globalDrawer: Kirigami.GlobalDrawer {
 // Makes drawer a small menu rather than sliding pane
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 Layout.fillHeight: true
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: kountdownModel.append({
 name: "Kirigami Action added card!",
 description: "Congratulations, your Kirigami Action works!",
 date: 1000
 })
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

Docs: Добавление диалога

Mon, 01 Jan 0001 00:00:00 +0000

Делаем приложение полезным

Окно есть, карточки есть, действия есть. Однако по-прежнему нужно найти способ ввода имени, описания и даты по своему выбору.

Один из способов сделать это — создать новую страницу, на которой размещаются необходимые элементы ввода. Однако целая страница, отведённая под ввод имени, описания и даты, кажется несколько избыточной.

Вместо этого будет использоваться диалог.

Открытие диалога

pageStack.initialPage: Kirigami.ScrollablePage {
 // …
 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]
}

Сначала отредактируем действие из предыдущего руководства: это просто Kirigami.Action, вызывающее функцию open() диалога.

Диалог добавления обратных отсчётов

Добавляемый компонент — это Kirigami.Dialog. Диалоги появляются в центре окна и позволяют предоставить дополнительную информацию, относящуюся к текущему содержимому. Переместить их нельзя, но они подстраивают свой размер под окно.

Kirigami.ApplicationWindow {
 // …
 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // Компоновки форм помогают выравнивать и структурировать компоновку с несколькими полями
 // ввода
 Kirigami.FormLayout {
 // Текстовые поля позволяют вводить текст в узком поле ввода
 Controls.TextField {
 id: nameField
 // Добавляет надпись, привязанную к текстовому полю
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // Что делать после подтверждения ввода (то есть нажатия клавиши Enter). В этом
 // случае фокус перемещается на следующее поле.
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // Снова фокус перемещается на следующее поле
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D означает обязательную цифру от 1 до 9, 9 означает обязательную цифру от 0 до 9
 inputMask: "D999-99-99"
 // Здесь операция подтверждается так же, как при нажатии кнопки «ОК»
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // Здесь размещается логика диалога
 }
 // …
}

По умолчанию диалоги имеют header и footer, оба унаследованы от Controls.Dialog.

Заголовок по умолчанию содержит title и кнопку закрытия, которую можно отключить с помощью showCloseButton. Нижний колонтитул по умолчанию не содержит кнопок. Её можно переопределить с помощью standardButtons.

Сначала задаётся показ кнопок «ОК» и «Отмена», добавляются отступы и разумное значение preferredWidth. Предпочитаемая ширина — это ожидаемый размер диалога по умолчанию, который при необходимости может увеличиваться. Можно использовать стандартные Kirigami.Units, которые будут рассмотрены позже.

Далее следует Kirigami.FormLayout. В отличие от ColumnLayout, расположение его дочерних компонентов задаётся автоматически и по центру, а подписи необязательны. Как следует из названия, он предназначен для создания форм ввода.

Эти компоновки форм предназначены для работы с различными типами ввода, однако здесь используются простые поля Controls.Textfield, предоставляющие простые текстовые поля для ввода.

Созданы элементы Textfield, которые выполняют роль:

Поле ввода названия обратного отсчёта
Поле ввода описания обратного отсчёта
Поле ввода даты, до которой ведётся обратный отсчёт; дата должна быть указана в формате YYYY-MM-DD

В каждом из этих элементов Controls.Textfield задаётся свойство Kirigami.FormData.label, позволяющее определить для них надписи. Форма покажет правильные надписи слева от каждого из этих полей ввода текста.

Наконец, свойство onAccepted также задаётся для вызова метода forceActiveFocus() следующего поля; это переключит активное поле, когда пользователь нажмёт клавишу ENTER, что повышает удобство работы с формой.

Также для текстового поля даты задано свойство inputMask. Задание этому свойству значения D999-99-99 не позволяет пользователям вводить что-либо, что может нарушить работу приложения (например, текст), ограничивая ввод только цифрами, которые затем можно попытаться преобразовать в объект даты.

Когда пользовательский интерфейс диалога готов, необходимо изменить его поведение. Для этого потребуется три вещи:

Показывать кнопку «ОК» только тогда, когда заполнены обязательные поля
Добавлять вводимую информацию в модель
Очищать форму ввода

Kirigami.Dialog {
 // ... После инициализации Kirigami.Dialog требуется создать пользовательскую привязку, чтобы
 // кнопка «ОК» показывалась только при заполнении обязательных текстовых полей. Для этого
 // используется Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => — это стрелочная функция JavaScript
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // Привязка создана, но ещё требуется сделать кнопку недоступной для нажатия, пока поля не
 // заполнены
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
}

Первое, что нужно сделать, — создать привязку между свойством enabled кнопки «ОК» и проверкой того, заполнены ли поля; в этом случае привязку нужно создать с помощью Qt.binding() в JavaScript. По сути, строка:

button.enabled = Qt.binding( () => requiredFieldsFilled() );

аналогично привязкам QML, рассмотренным ранее, например в следующем псевдокоде:

enabled: requiredFieldsFilled()

Обработчик сигнала, срабатывающий при нажатии кнопки «ОК», — это onAccepted. Если обязательные поля заполнены, он остаётся пустым и ничего не делает; в противном случае он добавит введённые данные в модель и очистит диалог при следующем открытии.

Kirigami.Dialog {
 // … Проверяется, что поле nameField не пустое и что поле dateField (для которого задана маска
 // ввода) заполнено полностью
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

Для обязательного поля имени достаточно проверить, является ли текст поля пустой строкой. Для поля даты, поскольку у него есть маска ввода, вместо этого нужно использовать acceptableInput, которое становится истинным только после того, как поле заполнено целиком и содержит только допустимые символы.

Затем метод append() модели списка kountdownModel добавляет объект JavaScript, содержащий предоставленные свойства.

Наконец, текстовые поля очищаются присвоением их свойствам text пустой строки, после чего вызывается close().

После сохранения файлов и сборки приложения можно будет добавить собственные обратные отсчёты! Осталось внести последний штрих для улучшения интерфейса — удалить фиктивный обратный отсчёт из предыдущих руководств:

26
27
28


 ListModel {
 id: kountdownModel
 }

Во-вторых, теперь, когда есть настоящая дата, с которой можно работать, можно вычислить время до этой даты:

47
48
49
50


 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

И в-третьих, увеличьте размер окна, чтобы было больше места для новых карточек:

 9
10


 width: 600
 height: 400

Гораздо лучше.

Наше приложение на данный момент

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // Form layouts help align and structure a layout with several inputs
 Kirigami.FormLayout {
 // Textfields let you input text in a thin textbox
 Controls.TextField {
 id: nameField
 // Provides a label attached to the textfield
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // What to do after input is accepted (i.e. pressed Enter)
 // In this case, it moves the focus to the next field
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // Again, it moves the focus to the next field
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D means a required number between 1-9,
 // 9 means a required number between 0-9
 inputMask: "D999-99-99"
 // Here we confirm the operation just like
 // clicking the OK button
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // Once the Kirigami.Dialog is initialized,
 // we want to create a custom binding to only
 // make the Ok button visible if the required
 // text fields are filled.
 // For this we use Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => is a JavaScript arrow function
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // The binding is created, but we still need to make it
 // unclickable unless the fields are filled
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 // We check that the nameField is not empty and that the
 // dateField (which has an inputMask) is completely filled
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

Docs: Использование отдельных файлов в проекте на C++

Mon, 01 Jan 0001 00:00:00 +0000

Зачем и как

Впервые некоторые компоненты будут вынесены в отдельные файлы QML. Если продолжать добавлять всё в Main.qml, быстро станет трудно понять, что за что отвечает, и есть риск запутать код.

В этом руководстве код в Main.qml разделяется на Main.qml, AddDialog.qml и KountdownDelegate.qml.

Кроме того, даже при распределении кода между несколькими файлами QML количество файлов в реальных проектах может выйти из-под контроля. Обычное решение этой проблемы — логическое разделение файлов по разным папкам. Ниже кратко рассматриваются три распространённых подхода, встречающихся в реальных проектах, и реализуется один из них:

Хранение файлов QML вместе с файлами C++
Хранение файлов QML в другой папке в рамках одного модуля
Хранение файлов QML в другой папке в составе другого модуля

После разбиения между каждым файлом будет разделение ответственности, а детали реализации будут абстрагированы, что сделает код более читаемым.

Хранение файлов QML вместе с файлами C++

Он заключается в том, чтобы хранить файлы QML проекта вместе с файлами C++ в src/. Такая структура выглядит так:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml
├── AddDialog.qml
└── KountdownDelegate.qml

Это то, что было сделано ранее. В описанном выше случае достаточно продолжать добавлять файлы QML в существующий kirigami-tutorial/src/CMakeLists.txt. Логического разделения здесь нет вовсе, и как только в проекте становится больше пары файлов QML (а также файлов C++, создающих типы для использования в QML), папка быстро переполняется.

Хранение файлов QML в другой папке в рамках одного модуля

Это подразумевает хранение всех файлов QML в отдельной папке, обычно src/qml/. Такая структура выглядит так:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
└── qml/
├── Main.qml
├── AddDialog.qml
└── KountdownDelegate.qml

Такая структура очень распространена в проектах KDE, в основном чтобы избежать дополнительного файла CMakeLists.txt для папки src/qml/ и создания отдельного модуля. При этом способе файлы остаются в отдельной папке, но их также потребуется добавить в kirigami-tutorial/src/CMakeLists.txt. Тогда все созданные файлы QML будут относиться к тому же модулю QML, что и Main.qml.

На практике, как только в проекте становится больше десятка файлов QML, они не загромоздят папку src/, но загромоздят файл src/CMakeLists.txt. Станет сложно различать традиционные файлы C++ и файлы C++, в которых типы доступны для QML.

Это также нарушит принцип локальности (локальное размещение сведений о зависимостях), при котором описание зависимостей хранится в том же месте, что и сами зависимости.

Хранение файлов QML в другой папке другого модуля

Это подразумевает хранение всех файлов QML в отдельной папке с собственным CMakeLists.txt и отдельным модулем QML. Такая структура выглядит так:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml
└── components/
├── CMakeLists.txt
├── AddDialog.qml
└── KountdownDelegate.qml

Такая структура не так распространена в проектах KDE и требует написания дополнительного файла CMakeLists.txt, но при этом она наиболее гибкая. В нашем случае папка называется «components», поскольку из предыдущего файла Main.qml создаются два новых компонента QML, а сведения о них хранятся в kirigami-tutorial/src/components/CMakeLists.txt. Сам файл Main.qml остаётся в src/, поэтому, как и прежде, он автоматически используется при запуске исполняемого файла.

В дальнейшем можно будет создавать больше папок с несколькими файлами QML, сгруппированными по назначению, например «models» и «settings», а файлы C++ с типами, доступными для QML (например, модели), можно будет хранить вместе с другими файлами QML, где это целесообразно.

В этом руководстве будет использоваться эта структура.

Подготовка CMake для новых файлов

Сначала создайте файл kirigami-tutorial/src/components/CMakeLists.txt со следующим содержимым:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Создаётся новая цель с именем kirigami-hello-components, которая затем преобразуется в модуль QML с помощью ecm_add_qml_module() под именем импорта org.kde.tutorial.components, и добавляются соответствующие файлы QML.

Поскольку цель отличается от исполняемого файла, она будет работать как другой QML-модуль. В этом случае потребуется выполнить два действия: заставить её генерировать код с помощью GENERATE_PLUGIN_SOURCE, чтобы она работала как модуль Qt, и завершить её с помощью ecm_finalize_qml_module(). Затем она устанавливается точно так же, как в предыдущих уроках.

Требовалось использовать add_library(), чтобы можно было связать kirigami-hello-components с исполняемым файлом в вызове target_link_libraries() в kirigami-tutorial/src/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

Также необходимо использовать add_subdirectory(), чтобы CMake нашёл папку kirigami-tutorial/src/components/.

В предыдущих уроках не требовалось добавлять импорт org.kde.tutorial в Main.qml, поскольку он был не нужен: будучи точкой входа приложения, исполняемый файл всё равно сразу запускал бы этот файл. Так как компоненты находятся в отдельном модуле QML, в kirigami-tutorial/src/Main.qml необходимо добавить новый импорт — тот же, что был определён ранее, org.kde.tutorial.components:

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

// Остальная часть кода…

И можно приступать.

Разделение Main.qml

Вернёмся ещё раз к исходному файлу Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // Form layouts help align and structure a layout with several inputs
 Kirigami.FormLayout {
 // Textfields let you input text in a thin textbox
 Controls.TextField {
 id: nameField
 // Provides a label attached to the textfield
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // What to do after input is accepted (i.e. pressed Enter)
 // In this case, it moves the focus to the next field
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // Again, it moves the focus to the next field
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D means a required number between 1-9,
 // 9 means a required number between 0-9
 inputMask: "D999-99-99"
 // Here we confirm the operation just like
 // clicking the OK button
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // Once the Kirigami.Dialog is initialized,
 // we want to create a custom binding to only
 // make the Ok button visible if the required
 // text fields are filled.
 // For this we use Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => is a JavaScript arrow function
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // The binding is created, but we still need to make it
 // unclickable unless the fields are filled
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 // We check that the nameField is not empty and that the
 // dateField (which has an inputMask) is completely filled
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

Пользовательский делегат с id: kountdownDelegate можно полностью разделить, поскольку он уже обёрнут в тип Component QML. Компонент применяется, чтобы определить его, не создавая экземпляр; отдельные файлы QML работают так же.

Если код перенесён в отдельные файлы, то нет смысла оставлять его внутри Component: в отдельный файл можно вынести только Kirigami.AbstractCard. Вот полученный KountdownDelegate.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

Наш диалог с id: addDialog не заключён в Component и не является компонентом, видимым по умолчанию, поэтому код можно скопировать как есть в AddDialog.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

После разделения кода Main.qml становится намного короче:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

Теперь есть два дополнительных QML-файла, AddDialog.qml и KountdownDelegate, и нужно найти способ использовать их в Main.qml. Способ добавить содержимое новых файлов в Main.qml заключается в создании экземпляров этих файлов.

AddDialog.qml становится AddDialog {}:

31
32
33


 AddDialog {
 id: addDialog
 }

KountdownDelegate.qml становится KountdownDelegate {}:

47
48
49
50
51


 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }

В большинстве случаев компонент, имя которого начиналось с прописной буквы и после которого стояли скобки, представлял собой экземпляр компонента QML. Поэтому имена новых файлов QML должны начинаться с прописной буквы.

Соберите проект и запустите его — должно появиться работающее окно, которое ведёт себя точно так же, как и раньше, но код разделён на отдельные части, что значительно упрощает работу.

Docs: Следующие шаги

Mon, 01 Jan 0001 00:00:00 +0000

Что было создано

За последние несколько руководств было создано простое, но работоспособное приложение Kirigami, позволяющее добавлять, изменять и удалять отсчёты до даты. Попутно были изучены компоненты Kirigami и QtQuick, некоторые принципы работы QML, базовые компоновки приложения и многое другое. Совсем неплохо!

Теперь основы, из которых состоят многие популярные приложения KDE, усвоены. Возможно, возникает вопрос: что дальше?

Не стоит беспокоиться: подготовлены некоторые указания о том, куда можно двигаться дальше.

Участие в проектах KDE

Один из лучших способов улучшить навыки разработки — применять их на практике. Сообщество KDE приветливо и всегда ищет увлечённых разработчиков!

Есть несколько документов, которые помогут стать участником проекта. Рекомендуется также ознакомиться с другими страницами о разработке, которые помогут узнать больше о процессе разработки сообщества KDE. Также рекомендуется ознакомиться с документацией по экземпляру GitLab сообщества KDE под названием Invent, поскольку в процессе разработки, скорее всего, придётся с ним взаимодействовать. Сообщество KDE общается в основном через Matrix, и есть страница в вики сообщества, которая поможет настроить собственную учётную запись.

Примечание

При общении с другими участниками сообщества KDE соблюдайте Кодекс поведения.

Приобретённые навыки позволяют начать вносить вклад в проекты Kirigami. К счастью, многие из самых популярных приложений и компонентов KDE созданы на основе этого фреймворка. Ниже приведён список проектов, в которых можно помочь.

Проекты Kirigami для начинающих

Проект	Что это такое	Ссылки
Calindori	Удобное для сенсорного управления приложение-календарь, предназначенное для мобильных устройств.	Страница KDE Apps Страница KDE Invent
Koko	Программа просмотра изображений, предназначенная для настольных компьютеров и сенсорных устройств.	Страница KDE Apps Страница KDE Invent
Kontrast	Проверка контрастности цветов, сообщающая, доступны ли цветовые сочетания для людей с нарушениями цветового зрения.	Страница KDE Apps Страница KDE Invent
Licentia	Приложение для выбора лицензии, подходящей для проекта.	Страница KDE Apps Страница KDE Invent
Помощник первого запуска	Приветственное приложение для рабочего стола Plasma, позволяющее создавать новые страницы с помощью QML.	Страница KDE Invent

Более сложные проекты Kirigami

Проект	Что это такое	Ссылки
Discover	Приложение для поиска и установки приложений, игр и инструментов.	Страница KDE Apps Страница KDE Invent
Elisa	Музыкальный проигрыватель, стремящийся к простоте и удобству использования.	Домашняя страница Страница KDE Apps Страница вики сообщества KDE Страница KDE Invent
KDE Connect	Кроссплатформенное приложение, позволяющее устройствам обмениваться данными (например, телефону и компьютеру).	Домашняя страница Страница вики сообщества KDE Страница KDE Invent
Kongress	Сопутствующее приложение для участников конференции.	Страница KDE Invent
NeoChat	Клиент Matrix — децентрализованного протокола обмена мгновенными сообщениями.	Страница KDE Apps Страница KDE Invent

Дополнительные сведения

Ещё не совсем готовы? Это тоже нормально.

Многие из перечисленных выше проектов — бесценные учебные материалы. Можно изучить код, увидеть, как опытные разработчики создавали полнофункциональные приложения, и применить эти приёмы самостоятельно.

Если требуется более мягкий подход, также собраны некоторые ресурсы, которые могут оказаться полезными.

Бэкенд и C++

Хотя о QML было изучено немало, тема работы с кодом бэкенда почти не затрагивалась. Тем не менее это важнейший аспект разработки приложений KDE.

C++/Qt с Kirigami

В продвинутом разделе этой документации Kirigami есть несколько страниц, которые помогут приступить к работе:

Страница	Тема
Понимание CMakeLists	Всё о CMake и компиляции приложений.
Разбор main.cpp	Знакомство с центральным файлом C++, отвечающим за инициализацию приложения
Подключение логики к пользовательскому интерфейсу QML	Добавление расширенной функциональности в приложение Kirigami и её подключение к пользовательскому интерфейсу
Страница «О программе»	Добавление страницы «О программе» в интерфейс

Ресурсы по C++ для начинающих

Тем, кто впервые сталкивается с C++, в Интернете доступно множество ресурсов. Ниже приведены некоторые из них, которые могут быть полезны.

Ресурс	Тема
LearnCpp	Учебные материалы для освоения C++
cppreference	Справочный сайт по C++
Wikibooks C++	Подробный викиучебник с уроками и упражнениями по C++
W3Schools C++	Набор учебных материалов по C++ и других ресурсов для начинающих

Также предоставляется список постоянно обновляемых ресурсов для изучения C++ в разделе Дополнительные материалы.

Создание классических приложений KDE с помощью QtWidgets

Если предполагается работать над такими приложениями KDE, как Dolphin, Kontact или Kate, потребуется изучить QtWidgets, где применяется совершенно иной способ разработки пользовательских интерфейсов средствами Qt. Более сложные приложения KDE или приложения, следующие традиционному дизайну, обычно создаются с помощью QtWidgets.

С QtWidgets работать несколько сложнее, чем с QML (к тому же требуется гораздо больше кода на C++!). К счастью, в документации KDE есть набор руководств, которые помогут с ними освоиться.

Дополнительные сведения о QML и QtQuick

Проект Qt обширен, как и QML с QtQuick. Множество возможностей осталось за рамками руководства, но есть обширная документация, из которой можно почерпнуть дополнительные сведения.

Чтобы узнать, что делают конкретные компоненты, достаточно обратиться к официальной документации Qt по QML.
Если нужен более структурированный подход к обучению, отличной отправной точкой станет QMLBook.

Дополнительные сведения о Kirigami

В этой документации содержится гораздо больше сведений о Kirigami. Можно просмотреть некоторые страницы раздела «Компоненты», чтобы узнать больше о компонентах QML, которые Kirigami предоставляет для использования.

Рекомендуется также обратить внимание на Kirigami Gallery — приложение, созданное разработчиками KDE для демонстрации инструментов и возможностей Kirigami. В нём представлены как интерактивные примеры компонентов Kirigami, так и ссылки на исходный код этих примеров, позволяющие увидеть, как они созданы.

Возможности безграничны!

Не стоит пугаться всего материала на этой странице! Никто сразу не умеет создавать что-то вроде Plasma с нуля. Но KDE — не многомиллиардная компания с высоким порогом входа (здесь не проводят пятиэтапных собеседований по программированию!), и если человек доброжелателен, ему всегда рады.

Удачи!

Docs: Цвета и темы в Kirigami

Mon, 01 Jan 0001 00:00:00 +0000

В Kirigami используется цветовая палитра, следующая системным цветам, чтобы лучше интегрироваться с платформой, на которой выполняется приложение (например, Plasma Desktop, Plasma Mobile, GNOME, Android и т. д.).

Все компоненты QML Kirigami и QtQuick Controls уже должны по умолчанию следовать этой палитре, поэтому обычно этим элементам управления не требуется задавать собственные цвета.

Простые компоненты, такие как Rectangle, всегда следует окрашивать с помощью цветовой палитры, которую предоставляет Kirigami через присоединённое свойство Kirigami.Theme.

Жёстко заданных цветов в QML, таких как #32b2fa или red, обычно следует избегать; если действительно необходимы элементы с собственными цветами, это должна быть область, где используются только собственные цвета (обычно в области содержимого приложения и никогда в служебных областях, таких как панели инструментов или диалоги). Например, жёстко заданный цвет переднего плана black нельзя использовать поверх фона Kirigami.Theme.backgroundColor, поскольку, если в платформе используется тёмная цветовая схема, результат будет плохо контрастировать: чёрный на почти чёрном. Это проблема доступности, и этого следует избегать.

Примечание

Если всё же требуется использовать собственные цвета, воспользуйтесь Kontrast, чтобы убедиться, что выбранные цвета обладают достаточным контрастом и соответствуют рекомендациям WCAG.

Тема

Kirigami.Theme — присоединённое свойство, поэтому его можно использовать для любого элемента QML. Среди его свойств — все цвета, доступные в палитре, и указание того, какую палитру использовать, например свойство colorSet.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 height: 300
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Rectangle {
 anchors.centerIn: parent
 implicitHeight: 100
 implicitWidth: 200
 color: Kirigami.Theme.highlightColor
 }
 }
}

Kirigami Gallery содержит пример кода, демонстрирующий все цвета, доступные в Kirigami, с помощью Kirigami.Theme. Он охватывает все их состояния: если щёлкнуть за пределами окна, цвета переключаются в неактивное состояние, а если переключить систему на тёмную тему, тёмные варианты цветов должны показываться в реальном времени.

Компонент «Цвета» в Kirigami Gallery

Набор цветов

В зависимости от расположения элемента управления следует использовать разные наборы цветов: например, если в представлениях используется цветовая схема Breeze Light, обычный фон почти белый, а в других областях, таких как панели инструментов или диалоги, обычный цвет фона серый.

Если задать для элемента набор цветов, все его дочерние элементы автоматически рекурсивно его наследуют (если только свойство inherit не установлено явно в false — так всегда следует поступать, когда разработчик хочет принудительно задать определённый набор цветов), поэтому легко изменить цвета для всей иерархии элементов, не затрагивая сами элементы.

Kirigami.Theme поддерживает 5 различных наборов цветов:

View: набор цветов для представлений элементов, обычно самый светлый из всех (в светлых цветовых схемах)
Window: набор цветов для окон и служебных областей (это также набор цветов по умолчанию)
Button: набор цветов для кнопок
Selection: набор цветов для выделенных областей
Tooltip: набор цветов, используемый всплывающими подсказками
Complementary: набор цветов, дополняющий Window; обычно тёмный даже в светлых темах. Может использоваться для акцентирования небольших областей приложения

Ниже приведён пример, показывающий, как наследуются наборы цветов и как с их помощью различать разные компоненты. Для контраста цветов добавлена широкая рамка.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83


import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// The comments assume the system uses the Breeze color theme

Kirigami.ApplicationWindow {
 height: 500
 width: 800

 Rectangle {
 anchors.fill: parent
 border.width: 5

 // A gray color will be used, as the default color set is Window
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-black, as defined in the Window color set for light themes
 text: "Rectangle that uses default background color\nfrom the Window color set"
 padding: 100
 }
 Rectangle {
 anchors.bottom: parent.bottom
 border.width: 5
 width: parent.width
 height: Math.round(parent.height / 2)

 // Use the color set used for Views
 Kirigami.Theme.colorSet: Kirigami.Theme.View
 // Do not inherit from the parent
 Kirigami.Theme.inherit: false
 // This will be a near-white color in light themes
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 text: "Rectangle that does not inherit the default background color\nand uses the Theme.View color set"
 padding: 50

 }

 Rectangle {
 anchors.bottom: parent.bottom
 anchors.left: parent.left
 border.width: 5
 width: Math.round(parent.width / 2)
 height: Math.round(parent.height / 2)

 // This will be a near-white color too, as the color set
 // is inherited from the parent and will be View
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-black, as defined in the View color set for light themes
 text: "Rectangle that inherits the Theme.View color set"
 anchors.centerIn: parent
 }
 }

 Rectangle {
 anchors.bottom: parent.bottom
 anchors.right: parent.right
 border.width: 5
 width: Math.round(parent.width / 2)
 height: Math.round(parent.height / 2)

 // Use the Complementary set
 Kirigami.Theme.colorSet: Kirigami.Theme.Complementary
 // Do not inherit from the parent
 Kirigami.Theme.inherit: false
 // This will be near-black as the background color
 // of the Complementary color set is dark in light themes
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-white, as defined in the Complementary color set for light themes
 text: "Rectangle that does not inherit the Theme.View\nand uses Theme.Complementary instead"
 anchors.centerIn: parent
 }
 }
 }
 }
}

Различия наборов цветов в Breeze

Различия наборов цветов в тёмном варианте Breeze

Использование пользовательских цветов

Хотя жёстко заданных цветов рекомендуется избегать, Kirigami предлагает более удобный для сопровождения способ назначить элементу и всем его дочерним элементам собственную жёстко заданную палитру, что позволяет определить такие собственные цвета в одном месте и только в нём:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Custom colors"
 height: 300
 width: 300

 Rectangle {
 anchors.fill: parent
 Kirigami.Theme.inherit: false
 // Примечание: независимо от используемого набора цветов рекомендуется заменить все
 // доступные цвета в Theme, чтобы избежать плохого контраста цветов.

 Kirigami.Theme.colorSet: Kirigami.Theme.Window
 Kirigami.Theme.backgroundColor: "#b9d795"
 Kirigami.Theme.textColor: "#465c2b"
 Kirigami.Theme.highlightColor: "#89e51c"
 // Переопределите все остальные цвета по своему усмотрению

 // Это будет "#b9d795"
 color: Kirigami.Theme.backgroundColor

 Rectangle {
 // Это будет "#465c2b"
 anchors.centerIn: parent
 height: Math.round(parent.height / 2)
 width: Math.round(parent.width / 2)
 color: Kirigami.Theme.textColor
 }
 }
}

Пример с пользовательскими цветами

Docs: Типографика

Mon, 01 Jan 0001 00:00:00 +0000

Для демонстрации в этом руководстве используется AbstractCard, чтобы примеры текста были нагляднее. Более удачный способ добиться того же результата — использовать FormCard из Kirigami Addons.

Заголовки

Kirigami предоставляет Heading, который можно использовать для заголовков страниц или разделов.

import QtQuick
import QtQuick.Layouts
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Kirigami Heading"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 anchors.fill: parent
 Kirigami.Heading {
 text: "Heading level 1"
 level: 1
 }
 Kirigami.Heading {
 text: "Heading level 2"
 level: 2
 }
 Kirigami.Heading {
 text: "Heading level 3"
 level: 3
 }
 Kirigami.Heading {
 text: "Heading level 4"
 level: 4
 }
 Kirigami.Heading {
 text: "Heading level 5"
 level: 5
 }
 }
 }
 }
}

Надписи

Текстовые элементы должны использовать компонент Label из QtQuick Controls 2.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Label"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: Controls.Label {
 text: "My text"
 }
 }
 }
}

Выравнивание текста

Для выравнивания текстовых элементов используются свойства horizontalAlignment и verticalAlignment.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Horizontal Center"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignHCenter
 text: "Welcome to my application"
 wrapMode: Text.Wrap
 }
 Controls.Label {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignHCenter
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.Wrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Horizontal Align Right"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignRight
 text: "Welcome to my application"
 wrapMode: Text.Wrap
 }
 Controls.Label {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignRight
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.Wrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Bottom and Top"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignBottom
 text: "Welcome to my application"
 wrapMode: Text.WordWrap
 }
 Controls.Label {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignTop
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.WordWrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Top and Bottom"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignTop
 text: "Welcome to my application"
 wrapMode: Text.WordWrap
 }
 Controls.Label {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignBottom
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.WordWrap
 }
 }
 }
 }
}

Текст с форматированием

QML позволяет показывать (и редактировать) форматированный текст. Управлять поведением можно с помощью свойства textFormat.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Label with rich text"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: Controls.Label {
 text: "<p><strong>List of fruits to purchase</strong></p>
 <ul>
 <li>Apple</li>
 <li>Cherry</li>
 <li>Orange</li>
 <li><del>Banana</del></li>
 </ul>
 <p>Kris already got some bananas yesterday.</p>"
 }
 }
 }
}

Тема

Размер шрифта Kirigami.Theme доступен в приложении как Kirigami.Theme.defaultFont.pointSize.

Docs: Компоненты на основе действий

Mon, 01 Jan 0001 00:00:00 +0000

Действия

Kirigami.Action — это действие, на которое можно нажать; его внешний вид зависит от того, куда оно добавлено. Обычно это кнопка со значком и текстом.

С их помощью можно снабдить приложения легко доступными действиями, необходимыми для их работы.

Примечание

Действия Kirigami наследуются от QtQuick.Controls.Action, и им можно назначить комбинации клавиш.

Как и действия QtQuick Controls, их можно назначать пунктам меню и кнопкам панели инструментов, а также многим другим компонентам Kirigami.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 id: copyAction
 text: i18n("Copy")
 icon.name: "edit-copy"
 shortcut: StandardKey.Copy
 onTriggered: {
 // …
 }
}

Примечание

Свойство icon.name принимает имена общесистемных значков в соответствии со спецификацией FreeDesktop. Эти значки и их имена можно просмотреть в приложении CuttleFish из KDE, входящем в состав plasma-sdk, или на странице спецификации именования значков FreeDesktop.

Одна из возможностей, которые действия Kirigami предоставляют в дополнение к действиям QtQuick, — вложение действий.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 text: "View"
 icon.name: "view-list-icons"
 Kirigami.Action {
 text: "action 1"
 }
 Kirigami.Action {
 text: "action 2"
 }
 Kirigami.Action {
 text: "action 3"
 }
}

Ещё одна возможность действий Kirigami — предоставлять элементам, использующим действия, различные подсказки о том, как им следует показывать действие. За это в первую очередь отвечают свойства displayHint и displayComponent.

Элемент будет учитывать эти свойства, если это возможно. Например, следующее действие будет показано как TextField, при этом элемент будет стараться как можно дольше оставаться видимым.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 text: "Search"
 icon.name: "search"

 displayComponent: TextField { }

 displayHint: Kirigami.DisplayHints.KeepVisible
}

Использование действий в других компонентах

Как упоминалось в вводном руководстве по действиям, действия Kirigami являются контекстными, то есть они появляются в разных местах в зависимости от того, куда их поместить. Кроме того, они имеют различные представления для настольных компьютеров и мобильных устройств.

Страница

В настольном режиме Kirigami.Page показывает действия справа от верхнего заголовка, а в мобильном — в нижнем колонтитуле.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 width: 600
 height: 600

 globalDrawer: Kirigami.GlobalDrawer {}
 contextDrawer: Kirigami.ContextDrawer {}

 pageStack.initialPage: Kirigami.Page {
 title: "Demo"

 actions: [
 Kirigami.Action {
 icon.name: "go-home"
 onTriggered: showPassiveNotification("Main action triggered")
 },
 Kirigami.Action {
 icon.name: "go-previous"
 onTriggered: showPassiveNotification("Left action triggered")
 },
 Kirigami.Action {
 icon.name: "go-next"
 onTriggered: showPassiveNotification("Right action triggered")
 },
 Kirigami.Action {
 text: "Contextual Action 1"
 icon.name: "bookmarks"
 onTriggered: showPassiveNotification("Contextual action 1 clicked")
 },
 Kirigami.Action {
 text: "Contextual Action 2"
 icon.name: "folder"
 enabled: false
 }
 ]
 }
}

Действия страницы на рабочем столе

Действия страницы на мобильном устройстве

Глобальная выдвижная панель

Kirigami.GlobalDrawer — это боковая панель в стиле меню, обеспечивающая навигацию по приложению на основе действий. Здесь вложенные действия оказываются полезны, поскольку позволяют создавать вложенную навигацию:

import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 globalDrawer: Kirigami.GlobalDrawer {
 title: "Demo"
 titleIcon: "applications-graphics"
 actions: [
 Kirigami.Action {
 text: "View"
 icon.name: "view-list-icons"
 Kirigami.Action {
 text: "View Action 1"
 onTriggered: showPassiveNotification("View Action 1 clicked")
 }
 Kirigami.Action {
 text: "View Action 2"
 onTriggered: showPassiveNotification("View Action 2 clicked")
 }
 },
 Kirigami.Action {
 text: "Action 1"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Action 2"
 onTriggered: showPassiveNotification("Action 2 clicked")
 }
 ]
 }
 //…
}

Действия глобальной выдвижной панели на рабочем столе

Подробнее о глобальных выдвижных панелях можно прочитать на странице документации по выдвижным панелям.

Контекстная выдвижная панель

Kirigami.ContextDrawer состоит из дополнительного набора действий, скрытых за меню с тремя точками в правом верхнем углу в настольном режиме или в правом нижнем углу в мобильном режиме, если не хватает места. Он используется для показа действий, относящихся только к определённой странице. Подробнее о них можно прочитать в руководстве Kirigami Drawers.

Текстовые поля действия

Kirigami.ActionTextField используется для добавления к текстовому полю контекстных действий, например для очистки текста или поиска по нему.

Kirigami.ActionTextField {
 id: searchField
 rightActions: [
 Kirigami.Action {
 icon.name: "edit-clear"
 visible: searchField.text !== ""
 onTriggered: {
 searchField.text = ""
 searchField.accepted()
 }
 }
 ]
}

В этом примере создаётся кнопка «Очистить» для поля поиска, которая показывается только при вводе текста.

Примечание

Напрямую использовать ActionTextField следует редко. SearchField и PasswordField оба наследуются от ActionTextField и, вероятно, охватывают нужный сценарий использования.

Элемент списка со смахиванием

Kirigami.SwipeListItem — это делегат, предназначенный для поддержки дополнительных действий. При использовании мыши его действия показываются всегда. На сенсорном устройстве их можно показать, перетащив элемент за маркер. На следующих рисунках это значки справа.

ListView {
 model: myModel
 delegate: SwipeListItem {
 Controls.Label {
 text: model.text
 }
 actions: [
 Action {
 icon.name: "document-decrypt"
 onTriggered: print("Action 1 clicked")
 },
 Action {
 icon.name: model.action2Icon
 onTriggered: //сделать что-то
 }
 ]
 }
}

SwipeListItem на компьютере

SwipeListItem на мобильном устройстве

Панель действий

Kirigami.ActionToolBar — это панель инструментов, создаваемая из списка действий. По умолчанию каждое действие, помещающееся на панели инструментов, показывается кнопкой ToolButton, а не помещающиеся перемещаются в меню в конце панели инструментов.

Как и ActionTextField, ActionToolBar можно не использовать напрямую, поскольку он применяется в заголовках страниц и карточках для показа действий.

import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 width: 350
 height: 350
 header: Kirigami.ActionToolBar {
 actions: [
 Kirigami.Action {
 text: i18n("View Action 1")
 onTriggered: showPassiveNotification(i18n("View Action 1 clicked"))
 },
 Kirigami.Action {
 text: i18n("View Action 2")
 onTriggered: showPassiveNotification(i18n("View Action 2 clicked"))
 },
 Kirigami.Action {
 text: i18n("Action 1")
 onTriggered: showPassiveNotification(i18n("Action 1 clicked"))
 },
 Kirigami.Action {
 text: i18n("Action 2")
 onTriggered: showPassiveNotification(i18n("Action 2 clicked"))
 }
 ]
 }
}

Горизонтальная панель инструментов, показываемая в верхней части приложения

Подробнее о компонентах ActionToolBar можно прочитать на отдельной странице документации.

Карточки

Kirigami.Card используется для совместного показа набора сведений или действий. Эти действия можно добавить в группу actions, подобно предыдущим компонентам.

Kirigami.Card {
 actions: [
 Kirigami.Action {
 text: qsTr("Action1")
 icon.name: "add-placemark"
 },
 Kirigami.Action {
 text: qsTr("Action2")
 icon.name: "address-book-new-symbolic"
 },
 // …
 ]
 banner {
 source: "../banner.jpg"
 title: "Title Alignment"
 titleAlignment: Qt.AlignLeft | Qt.AlignBottom
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
}

Подробнее о компоненте Cards можно прочитать на странице компонента.

Docs: Стеки страниц (page rows и page stacks)

Mon, 01 Jan 0001 00:00:00 +0000

Ряд страниц

Ранее уже отмечалось, что одним из основных компонентов окна Kirigami является Kirigami.Page. Одна страница занимает весь экран приложения либо показывается одновременно с другими страницами, если есть место.

Когда страница добавляется или помещается в стек, она появляется справа от существующих страниц, образуя ряд. Управлять этим рядом страниц можно с помощью метко названного Kirigami.PageRow.

Минимальный ряд страниц с одной страницей может выглядеть так:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Single Page"
 width: 500
 height: 200

 Kirigami.PageRow {
 anchors.fill: parent

 Kirigami.Page {
 id: mainPage
 anchors.fill: parent
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 }
 }
 }
}

Одна страница светло-синего цвета, показывающая размеры страницы

Здесь можно внести два улучшения. Первое: с помощью initialPage можно и задать mainPage в качестве первой страницы, появляющейся в стеке страниц, и поручить управление её размерами стеку страниц вместо ручного задания якорей, позиционеров или компоновок. Второе — добавить панель инструментов, которую можно задать, определив стиль панели инструментов с помощью globalToolBar.style. Можно выбрать один из нескольких стилей, но пока остановимся на Kirigami.ApplicationHeaderStyle.Auto.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "With globalToolBar and initialPage"
 width: 500
 height: 200
 Kirigami.PageRow {
 anchors.fill: parent
 globalToolBar.style: Kirigami.ApplicationHeaderStyle.Auto
 initialPage: Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 }
 }
 }
}

Одна страница с панелью инструментов и светло-синим цветом, показывающим размеры страницы

Добавить страницы в стек страниц можно только двумя способами: задав её свойство initialPage (которое может дополнительно принимать массив страниц) или использовав push(). Чтобы удалить страницу из стека страниц, используйте pop(), а для перехода между страницами можно использовать goBack() или goForward().

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Multiple pages in a row"
 width: 700
 height: 300
 Kirigami.PageRow {
 id: mainRow
 anchors.fill: parent
 globalToolBar.style: Kirigami.ApplicationHeaderStyle.Auto
 initialPage: Kirigami.Page {
 id: firstPage
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 Controls.Button {
 anchors.centerIn: parent
 text: "Push!"
 onClicked: mainRow.push(secondPage)
 }
 }
 }

 Component {
 id: secondPage
 Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightgreen"
 Controls.Button {
 anchors.centerIn: parent
 text: "Pop!"
 onClicked: mainRow.pop()
 }
 }
 }
 }
 }
}

Начальная страница со светло-синим цветом

После нажатия кнопки «Push!» появляется вторая страница светло-зелёного цвета

Стек страниц приложения

Если Kirigami.PageRow с панелью инструментов выглядит знакомо, то лишь потому, что он уже встречался ранее. ApplicationWindow.pageStack — не что иное, как очень удобный глобальный стек страниц. Все функции, доступные в PageRow, доступны и в pageStack.

Предыдущий пример можно значительно сократить с помощью pageStack, а дополнительным преимуществом станут действия навигации:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Using the pageStack"
 width: 500
 height: 200
 pageStack.initialPage: Kirigami.Page {
 id: firstPage
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 Controls.Button {
 anchors.centerIn: parent
 text: "Push!"
 onClicked: pageStack.push(secondPage)
 }
 }
 }
 Component {
 id: secondPage
 Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightgreen"
 Controls.Button {
 anchors.centerIn: parent
 text: "Pop!"
 onClicked: pageStack.pop()
 }
 }
 }
 }
}

Обычно следует использовать pageStack, а не реализовывать собственный PageRow, особенно когда приложение разрастается и компоненты требуется размещать в отдельных файлах. Если окно создаётся в Main.qml с помощью Kirigami.ApplicationWindow, компонент, находящийся в другом файле, всё равно может напрямую обратиться к глобальному pageStack посредством вызова applicationWindow():

// Main.qml
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Pushing a Page from a different QML file"
 width: 700
 height: 400
 pageStack.initialPage: BasicPage {}
}

// BasicPage.qml
import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Page {
 Controls.Button {
 anchors.centerIn: parent
 text: "This pushes page1 from BasicPage\ninto the pageStack from Main.qml!"
 onClicked: {
 applicationWindow().pageStack.push(page1)
 }
 Component {
 id: page1
 Kirigami.Page {
 Controls.Label {
 anchors.centerIn: parent
 text: "page1 was pushed!"
 }
 }
 }
 }
}

Добавление новой страницы при нажатии кнопки с помощью applicationWindow

Docs: Прокручиваемые страницы и списки

Mon, 01 Jan 0001 00:00:00 +0000

Kirigami.ScrollablePage

Kirigami.ScrollablePage — страница, содержащая прокручиваемое содержимое, например ListView. Прокрутка и индикаторы прокрутки управляются автоматически.

Kirigami.ScrollablePage {
 id: root
 //Прямоугольник автоматически станет прокручиваемым
 Rectangle {
 width: root.width
 height: 99999
 }
}

Во всём остальном прокручиваемая страница ничем не отличается от обычной.

Предупреждение

Не помещайте ScrollView внутрь Kirigami.ScrollablePage: дочерние элементы Kirigami.ScrollablePage уже находятся внутри ScrollView.

ListView в ScrollablePage

Когда прямые дочерние элементы Kirigami.ScrollablePage выходят по вертикали за пределы размера самой страницы, у правого края страницы появляется полоса прокрутки, и страница становится прокручиваемой.

Две прокручиваемые страницы, каждая из которых содержит ListView с собственным содержимым (снимок экрана NeoChat)

Часто в Kirigami.ScrollablePage содержится несколько дочерних элементов, и расположить их бывает непросто — особенно в сочетании с ListView.

Для невизуальных компонентов их размещение внутри компонента ListView не изменит внешний вид страницы, поэтому их можно переместить в область видимости списка. То же относится к элементам, привязанным к центру страницы, например к сообщениям-заполнителям для пустых списков.
Для других элементов, возможно, имеет смысл переместить их в заголовок или нижний колонтитул Kirigami.ScrollablePage. Часто это относится к строкам поиска.

PlaceholderMessage

Есть возможность добавить Kirigami.PlaceholderMessage с инструкциями на случай, если список пуст.

Kirigami.ScrollablePage {
 ListView {
 id: listView
 Kirigami.PlaceholderMessage {
 anchors.centerIn: parent
 width: parent.width - (Kirigami.Units.largeSpacing * 4)
 visible: listView.count === 0
 text: i18n("No data found")
 helpfulAction: Kirigami.Action {
 text: i18n("Load data")
 // Больше кода…
 }
 }
 model: // Код модели…
 }
}

Поиск в ListView

Поле поиска часто добавляется на Kirigami.ScrollablePage, чтобы фильтровать ListView. Для этого можно изменить titleDelegate по умолчанию так, чтобы вместо него использовался Kirigami.SearchField.

Kirigami.ScrollablePage {
 titleDelegate: Kirigami.SearchField {
 Layout.topMargin: Kirigami.Units.smallSpacing
 Layout.bottomMargin: Kirigami.Units.smallSpacing
 Layout.fillHeight: true
 Layout.fillWidth: true
 onTextChanged: mySortFilterModel.filterText = text
 KeyNavigation.tab: listView
 }

 ListView {
 id: listView
 // Остальная часть кода представления списка…
 }
}

Подсказка

Можно использовать KSortFilterProxyModel из KItemModel, чтобы легко добавить возможность фильтрации непосредственно в QML без необходимости писать код на C++.

Потяните для обновления

Ещё одна функция, предоставляемая этим компонентом, — действие «потянуть для обновления». Чтобы воспользоваться им, включите его следующим образом:

Kirigami.ScrollablePage {
 id: view
 supportsRefreshing: true
 onRefreshingChanged: {
 if (refreshing) {
 myModel.refresh();
 }
 }
 ListView {
 // ПРИМЕЧАНИЕ. MyModel не входит в состав компонентов — это лишь пример того, как его можно
 // использовать вместе с логикой приложения, которая обновляет модель списка и подаёт сигнал
 // по завершении.
 model: MyModel {
 onRefreshDone: view.refreshing = false;
 }
 delegate: BasicListItem {}
 }
}

Потянув вниз, можно также включить специальный режим с увеличенным верхним отступом, упрощающий использование приложения одной рукой.

Docs: Карточки

Mon, 01 Jan 0001 00:00:00 +0000

Типы Kirigami AbstractCard и Card используются для реализации популярного компонента карточки, применяемого на многих мобильных и веб-платформах. Карточки позволяют показать набор сведений или действий в привлекательной и выразительной форме.

Kirigami также предлагает три вида представлений и позиционеров, помогающих создавать красивые и адаптивные компоновки для показа карточек.

Абстрактная карточка

Kirigami.AbstractCard — простейший тип карточки. Это просто прямоугольник с тенью, в который можно поместить любой Item. Кроме того, свойствам header и footer можно назначить элементы. В этом случае в роли header выступает Kirigami.Heading, а в роли contentItem карточки — Controls.Label.

Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: qsTr("AbstractCard")
 level: 2
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "..."
 }
}

Карточка

Kirigami.Card наследуется от AbstractCard и предоставляет больше возможностей без дополнительной настройки. Карточки наследуют те же header и footer от Abstract Card, но вместо них рекомендуется использовать banner и набор объектов Kirigami.Action в группе actions.

Kirigami.Card {
 actions: [
 Kirigami.Action {
 text: qsTr("Action1")
 icon.name: "add-placemark"
 },
 Kirigami.Action {
 text: qsTr("Action2")
 icon.name: "address-book-new-symbolic"
 },
 // …
 ]
 banner {
 source: "../banner.jpg"
 title: "Title Alignment"
 // Заголовок можно разместить в баннере
 titleAlignment: Qt.AlignLeft | Qt.AlignBottom
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
}

Компоновка карточек

Kirigami.CardsLayout наиболее полезен, когда показываемые карточки либо не создаются моделью, либо создаются моделью, которая всегда содержит очень мало элементов. Они показываются в виде сетки из двух столбцов, которая остаётся по центру, если приложение очень широкое, или превращается в один столбец, если для двух столбцов не хватает места, например на экране мобильного телефона.

Примечание

CardsListView лучше подходит для больших моделей.

Важно

CardsLayout всегда должен находиться внутри ColumnLayout.

Карточку можно при желании расположить горизонтально. В этом случае её ширина будет больше высоты, и её лучше размещать в ColumnLayout. Если её всё же нужно поместить в CardsLayout, то по умолчанию свойство maximumColumns будет иметь значение 2.

ColumnLayout {
 Kirigami.CardsLayout {
 Kirigami.Card {
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text2"
 }
 }
 Kirigami.AbstractCard {
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
 }
 Kirigami.Card {
 headerOrientation: Qt.Horizontal
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text2"
 }
 }
 }
}

CardsListView

Kirigami.CardsListView — это представление списка, которое можно использовать с компонентами AbstractCard.

CardsListView растягивает дочерние карточки до собственной ширины. Поэтому этот компонент следует использовать только с карточками, которые хорошо выглядят при любом размере по горизонтали. Использование внутри него компонента Card не рекомендуется, если только его свойство headerOrientation не имеет значения Qt.Horizontal.

Kirigami.CardsListView {
 id: view
 model: 100

 delegate: Kirigami.AbstractCard {
 //Примечание: никогда не назначать Layout в качестве contentItem — это приведёт к
 //циклическим привязкам.
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 //ВАЖНО: никогда не задавайте нижнее поле
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: width > Kirigami.Units.gridUnit * 20 ? 4 : 2
 Kirigami.Icon {
 source: "applications-graphics"
 Layout.fillHeight: true
 Layout.maximumHeight: Kirigami.Units.iconSizes.huge
 Layout.preferredWidth: height
 }
 Kirigami.Heading {
 level: 2
 text: qsTr("Product ")+ modelData
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: qsTr("Install")
 }
 }
 }
 }
}

Docs: Выдвижные панели

Mon, 01 Jan 0001 00:00:00 +0000

Выдвижные панели (drawers) — это панели, выдвигающиеся из боковых сторон окна приложения. Их можно наполнить интерактивными элементами, такими как действия Kirigami, кнопки, текст и многое другое.

Выдвижные панели бывают разных типов, форм и видов. На этой странице рассматривается каждый тип и даётся обзор их характеристик.

Глобальная выдвижная панель

Глобальная выдвижная панель — стандартный элемент мобильных приложений KDE, иногда она встречается и в их настольных версиях. Она содержит главное меню приложения: сюда входят функции, не относящиеся к текущей странице, но важные для общей навигации или взаимодействия внутри приложения.

Активируется нажатием меню-гамбургера или проведением пальца от левого края до середины экрана в режиме «Слева направо» либо от правого края в режиме «Справа налево».

Компоненты Kirigami.GlobalDrawer используются для создания таких панелей. Они задаются в свойстве globalDrawer окна Kirigami.ApplicationWindow, которое служит основой приложения Kirigami.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page { /* Page code here... */ }

 globalDrawer: Kirigami.GlobalDrawer {
 title: "Global Drawer"
 titleIcon: "applications-graphics"
 actions: [
 Kirigami.Action {
 text: "Kirigami Action 1"
 icon.name: "user-home-symbolic"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Kirigami Action 2"
 icon.name: "settings-configure-symbolic"
 onTriggered: showPassiveNotification("Action 2 clicked")
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
}

Примечание

Свойство titleIcon принимает имена общесистемных значков в соответствии со спецификацией FreeDesktop. Эти значки и их имена можно просмотреть в приложении CuttleFish из KDE, входящем в состав plasma-sdk, или на странице спецификации именования значков FreeDesktop.

Заголовок

Заголовки позволяют разместить закреплённые компоненты в верхней части глобальной выдвижной панели. Компоненты заголовка остаются на месте, даже если глобальная выдвижная панель содержит вложенные действия Kirigami, заменяющие текущий слой на глобальной выдвижной панели.

Выбранный компонент заголовка задаётся свойством header глобальной выдвижной панели, и он заменяет заголовок глобальной выдвижной панели. Это удобно, например, для добавления Kirigami.SearchField:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page { /* Page code here... */ }

 globalDrawer: Kirigami.GlobalDrawer {
 title: "Global Drawer with searchfield (not visible)"

 header: Kirigami.SearchField {
 id: searchField
 }

 actions: [
 Kirigami.Action {
 text: "Kirigami Action 1"
 icon.name: "user-home-symbolic"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Kirigami Action 2"
 icon.name: "settings-configure-symbolic"
 onTriggered: showPassiveNotification("Action 2 clicked")
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
}

Теперь глобальная выдвижная панель показывает компонент строки поиска, заданный в качестве заголовка.

Адаптация для рабочего стола

Хотя глобальные выдвижные панели в стиле панели могут быть полезны в мобильной среде, на рабочем столе они могут оказаться слишком большими, особенно если в приложении мало действий.

К счастью, глобальные выдвижные панели Kirigami имеют свойство isMenu. Если задать ему значение true, они превращаются в более традиционные меню, но только в настольном режиме.

Примечание

В этом режиме меню заголовки и баннеры не показываются.

globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true

 actions: [
 // Здесь действия Kirigami…
 ]
}

Глобальная выдвижная панель в режиме меню, без заголовка и баннера

Контекстные выдвижные панели

В то время как Kirigami.GlobalDrawer показывает глобальные действия, доступные во всём приложении, Kirigami.ContextDrawer следует использовать для показа действий, относящихся только к определённым контекстам. Обычно он используется на отдельных страницах.

Контекстная выдвижная панель ведёт себя по-разному в зависимости от того, используется ли она на мобильной платформе или на рабочем столе.

На рабочем столе, когда в окне достаточно места, контекстные действия показываются как часть группы actions на верхней панели инструментов. Если места мало, например на мобильном устройстве или в узком окне, контекстные действия скрываются за меню-гамбургером справа. Это отличается от других действий в группе actions, а именно actions.main, actions.left и actions.right: они не скрываются в окнах с ограниченным пространством, а сворачиваются в свои значки.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 height: 600
 width: 1200
 minimumWidth: 500

 globalDrawer: Kirigami.GlobalDrawer {}
 contextDrawer: Kirigami.ContextDrawer {}

 pageStack.initialPage: [ emptyPage, contextDrawerPage ]

 Kirigami.Page {
 title: "Empty page"
 id: emptyPage
 }

 Kirigami.Page {
 id: contextDrawerPage
 title: "Context Drawer page"

 actions: [
 Kirigami.Action {
 icon.name: "media-record"
 },
 Kirigami.Action {
 icon.name: "arrow-left"
 },
 Kirigami.Action {
 icon.name: "arrow-right"
 },
 Kirigami.Action {
 text: "Contextual Action 1"
 icon.name: "media-playback-start"
 },
 Kirigami.Action {
 text: "Contextual Action 2"
 icon.name: "media-playback-stop"
 }
 ]
 }
}

Контекстная выдвижная панель со скрытыми контекстными действиями

Контекстная выдвижная панель, показывающая все контекстные действия

В мобильном режиме выдвижная панель всегда состоит из действий, скрытых за меню-гамбургером. Активируется нажатием меню-гамбургера или проведением пальца от правого края до середины экрана в режиме «Слева направо» либо от левого края в режиме «Справа налево».

Тот же пример, что и выше, в мобильном режиме

Открытая контекстная выдвижная панель в мобильном режиме

Модальные и встроенные выдвижные панели

Kirigami предлагает два дополнительных типа панелей: модальные и встроенные. Они довольно похожи друг на друга: обе занимают всю ширину или высоту приложения и могут размещаться по краям окна приложения. Однако на действия пользователя они реагируют по-разному.

Модальные выдвижные панели по умолчанию скрыты и затемняют остальную часть приложения, а закрываются при щелчке по затемнённой области.
Встроенные выдвижные панели показываются по умолчанию, позволяют продолжать взаимодействие с остальной частью приложения, не закрываясь, и не затемняют другие области.

Этот тип выдвижной панели не имеет жёсткой структуры и гибок, но обычно его стоит использовать, когда нужно, чтобы небольшой список параметров появлялся при длительном нажатии или щелчке правой кнопкой мыши.

Эти две выдвижные панели так похожи потому, что на деле реализуются с помощью одного и того же компонента Kirigami: Kirigami.OverlayDrawer. Вот несколько важных унаследованных свойств этого компонента, которые следует учитывать:

Popup.modal определяет, будет ли выдвижная панель модальной или встроенной, в зависимости от логического значения.
Drawer.edge определяет, с какого края окна приложения появится выдвижная панель; варианты этого свойства входят в перечисление Edge, а именно Qt.TopEdge, Qt.RightEdge, Qt.BottomEdge и Qt.LeftEdge.
Popup.contentItem содержит компонент, который образует содержимое выдвижной панели.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 400
 height: 600
 pageStack.initialPage: Kirigami.Page {
 title: "OverlayDrawer at the bottom"
 actions: [
 Kirigami.Action {
 text: "Open bottomDrawer"
 onTriggered: bottomDrawer.open()
 }
 ]
 Kirigami.OverlayDrawer {
 id: bottomDrawer
 edge: Qt.BottomEdge
 // Установите для свойства modal значение false, чтобы эта выдвижная панель стала
 // встроенной!
 modal: true

 contentItem: RowLayout {
 Controls.Label {
 Layout.fillWidth: true
 text: "Say hello to my little drawer!"
 }
 Controls.Button {
 text: "Close"
 onClicked: bottomDrawer.close()
 }
 }
 }
 }
}

Модальная выдвижная панель не видна

Модальная выдвижная панель у нижнего края экрана

Docs: Чипы

Mon, 01 Jan 0001 00:00:00 +0000

Компоненты Kirigami.Chip — небольшие элементы, унаследованные от AbstractButton, которые используются для показа общих свойств или фильтров чего-либо. Как правило, это текстовые элементы, с которыми также можно взаимодействовать; они имеют необязательную кнопку удаления.

Начало работы

Чипы легко добавляются с помощью компонента Kirigami.Chip. Присвоение строки унаследованному полю AbstractButton.text задаёт имя чипа.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Chips"

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.FormLayout {
 anchors.fill: parent
 Kirigami.Chip {
 text: "Chip 1"
 }
 Kirigami.Chip {
 text: "Chip 2"
 }
 Kirigami.Chip {
 text: "Chip 3"
 }
 }
 }
}

С использованием Repeater (рекомендуется)

Так как чипы предназначены для многократного использования, скорее всего, потребуется применить какую-либо структуру данных списка и перебирать их для показа чипов. Для этого нужны компоненты ListModel и Repeater.

ListModel используется как хранилище для чипов. Чтобы заполнить ListModel (а следовательно, и чипы), объявляется пара компонентов ListElement, содержащих поле с именем text. Строку, заданную здесь, можно использовать в качестве значения поля text для каждого повторяющегося чипа.

Repeater используется для показа чипов. Сначала нужно присвоить полю model компонента Repeater наш ListModel или создать ListModel внутри Repeater. Затем внутри Repeater объявляется компонент Kirigami.Chip, а его поле text заполняется данными элемента с помощью свойства modelData.

Kirigami.ApplicationWindow {
 id: root
 title: "Chips"

 ListModel {
 id: chips

 ListElement { text: "Chip 1" }
 ListElement { text: "Chip 2" }
 ListElement { text: "Chip 3" }
 }

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.FormLayout {
 anchors.fill: parent
 Repeater {
 Layout.fillWidth: true
 model: chips

 Kirigami.Chip {
 id: chip
 text: modelData
 }
 }
 }
 }
}

Примечание

Данные можно динамически добавлять в ListModel и удалять из неё, а Repeater автоматически внесёт эти изменения. Однако простое изменение конкретного элемента из Repeater или ListModel не влияет на другой и требует изменения обоих, если не используется что-то наподобие QAbstractListModel. Дополнительные сведения см. в разделе Пример приложения.

Пример приложения

В приведённом ниже примере приложения показано, как использовать чипы в таких программах, как списки задач.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root
 title: "Chips"

 ListModel {
 id: chips

 ListElement { text: "Chip 1" }
 ListElement { text: "Chip 2" }
 ListElement { text: "Chip 3" }
 }

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.OverlaySheet {
 id: editChipPrompt

 property var chip;
 property var index;

 header: Kirigami.Heading {
 text: "Edit Chip"
 }

 footer: DialogButtonBox {
 standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel
 onAccepted: {
 // Both the data from the Repeater and ListModel must be
 // edited in order to update both.
 editChipPrompt.chip.text = editTextField.text;
 chips.setProperty(editChipPrompt.index, "text", editTextField.text);
 editChipPrompt.close();
 }
 onRejected: {
 editChipPrompt.close();
 }
 }

 TextField {
 id: editTextField
 }
 }

 Kirigami.FormLayout {
 anchors.fill: parent
 TextField {
 id: insertTextField
 Kirigami.FormData.label: "Item:"
 onAccepted: chips.append({ text: insertTextField.text })
 }
 // Wrapped in ColumnLayout to prevent binding loops.
 ColumnLayout {
 Layout.alignment: Qt.AlignHCenter
 Repeater {
 model: chips

 Kirigami.Chip {
 id: chip
 text: modelData
 onClicked: {
 editTextField.text = modelData;
 editChipPrompt.chip = chip;
 editChipPrompt.index = index;
 editChipPrompt.open();
 }
 onRemoved: chips.remove(index)
 }
 }
 }
 }
 }
}

Docs: Типы диалогов

Mon, 01 Jan 0001 00:00:00 +0000

Kirigami.Dialog — простой компонент, который можно использовать для дополнения содержимого, показываемого на странице приложения. Он позволяет показывать неинтерактивное содержимое (только текст) и интерактивное содержимое (формы, списки и кнопки).

Их можно закрыть щелчком или касанием вне их области либо нажатием кнопки закрытия в заголовке.

Изолированные среды

Это работает без дополнительной настройки для всех диалогов Kirigami в изолированных средах (например, Flatpak) через XDG Desktop Portals. При работе в изолированной среде подходящий механизм порталов используется автоматически, что позволяет получать доступ с одобрения пользователя без ручной обработки D-Bus.

Диалог

Для создания пользовательских диалогов используется стандартный Kirigami.Dialog. Их очень легко расширять:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Dialog"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: "Show dialog"
 onTriggered: dialog.open()
 }

 Kirigami.Dialog {
 id: dialog
 title: "A simple dialog"
 padding: Kirigami.Units.largeSpacing
 showCloseButton: false
 standardButtons: Kirigami.Dialog.NoButton
 flatFooterButtons: false
 Controls.Label {
 text: "A generic, easy to make dialog!"
 }
 customFooterActions: Kirigami.Action {
 text: "Copy"
 icon.name: "clipboard"
 }
 }
 }
}

Как показано в вводном руководстве по диалогам, можно также перехватить standardButton(button), чтобы назначить ему некоторое поведение, например привязку для включения только при определённых условиях.

Этот тип диалога универсален, подходит для большинства сценариев использования и хорошо работает со сложным интерактивным содержимым (особенно с представлениями):

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Scrollable Dialog"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: scrollableDialog.title
 onTriggered: scrollableDialog.open()
 }

 Kirigami.Dialog {
 id: scrollableDialog
 title: i18n("Select Number")

 ListView {
 id: listView
 // Подсказки по размерам диалога
 implicitWidth: Kirigami.Units.gridUnit * 16
 implicitHeight: Kirigami.Units.gridUnit * 16

 model: 20
 delegate: Controls.RadioDelegate {
 topPadding: Kirigami.Units.smallSpacing * 2
 bottomPadding: Kirigami.Units.smallSpacing * 2
 implicitWidth: listView.width
 text: modelData
 }
 }
 }

 }
}

Однако в большинстве случаев, вероятно, потребуется использовать один из производных типов диалогов: Kirigami.PromptDialog или Kirigami.MenuDialog.

Диалог запроса

Kirigami.PromptDialog — это, по сути, диалог со встроенной надписью и значением contentPadding по умолчанию, которое служит для запроса у пользователя некоторых сведений. Этот тип диалога предназначен только для простых запросов с ответом «да» или «нет» либо краткого ввода данных пользователем.

Его основное свойство — Kirigami.Dialog.subtitle, в которое добавляется текст. Если в качестве дочернего компонента диалога запроса добавить любой компонент QML, вместо подзаголовка будет показан этот компонент.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "PromptDialog"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: promptDialog.title
 onTriggered: promptDialog.open()
 }

 Kirigami.PromptDialog {
 id: promptDialog
 title: i18n("Delete file")
 subtitle: i18n("Are you sure you'd like to delete this file?")

 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: console.info("File deleted")
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "PromptDialog with a textfield"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: textPromptDialog.title
 onTriggered: textPromptDialog.open()
 }

 Kirigami.PromptDialog {
 id: textPromptDialog
 title: "New Folder"

 standardButtons: Kirigami.Dialog.NoButton
 customFooterActions: [
 Kirigami.Action {
 text: "Create Folder"
 icon.name: "dialog-ok"
 onTriggered: {
 showPassiveNotification("Created");
 textPromptDialog.close();
 }
 },
 Kirigami.Action {
 text: "Cancel"
 icon.name: "dialog-cancel"
 onTriggered: {
 textPromptDialog.close();
 }
 }
 ]
 ColumnLayout {
 Controls.TextField {
 Layout.fillWidth: true
 placeholderText: "Folder name…"
 }
 }
 }
 }
}

Диалог меню

Kirigami.MenuDialog — специализированный диалог, предназначенное для вывода списка доступных для нажатия параметров с помощью свойства actions.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "MenuDialog"
 width: 400
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: menuDialog.title
 onTriggered: menuDialog.open()
 }

 Kirigami.MenuDialog {
 id: menuDialog
 title: i18n("Track options")
 showCloseButton: false

 actions: [
 Kirigami.Action {
 icon.name: "media-playback-start"
 text: i18n("Play")
 tooltip: i18n("Start playback of the selected track")
 },
 Kirigami.Action {
 enabled: false
 icon.name: "document-open-folder"
 text: i18n("Show in folder")
 tooltip: i18n("Show the file for this song in the file manager")
 },
 Kirigami.Action {
 icon.name: "documentinfo"
 text: i18n("View details")
 tooltip: i18n("Show track metadata")
 },
 Kirigami.Action {
 icon.name: "list-add"
 text: i18n("Play next")
 tooltip: i18n("Add the track to the queue, right after the current track")
 },
 Kirigami.Action {
 icon.name: "list-add"
 text: i18n("Add to queue")
 tooltip: i18n("Enqueue current track")
 }
 ]
 }
 }
}

Docs: Элементы управления и интерактивные элементы

Mon, 01 Jan 0001 00:00:00 +0000

Kirigami использует широкий выбор различных интерактивных элементов Qt, которые можно применять в приложениях. У каждого типа немного различаются стили взаимодействия, визуальные стили и функциональность. Использование подходящего типа элемента управления в приложении помогает сделать пользовательский интерфейс более отзывчивым и интуитивно понятным.

Кнопки

В приложениях Kirigami используется Button из QtQuick Controls. Работа с ними довольно проста: задаётся свойство text, а действие, которое должно выполняться, задаётся свойством onClicked.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Button"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Button {
 Layout.alignment: Qt.AlignCenter
 text: "Beep!"
 onClicked: showPassiveNotification("Boop!")
 }
 }
 }
}

Переключаемые кнопки

Поведение кнопок можно изменить, сделав их переключаемыми: в этом режиме они остаются нажатыми, пока по ним не щёлкнуть ещё раз. Этот режим включается присвоением свойству checkable значения true; кнопки можно также включить по умолчанию, присвоив свойству checked значение true.

Наиболее полно использовать переключаемые кнопки позволяет обработчик сигнала onCheckedChanged, который создаётся автоматически из сигнала checked. Он работает аналогично onClicked, но назначенное действие выполняется при изменении состояния кнопки. Это логическое свойство, которое пригодится в отдельных случаях.

В этом примере видимость встроенной выдвижной панели задаётся в зависимости от состояния переключаемой кнопки:

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Button (toggleable version)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Button {
 Layout.alignment: Qt.AlignCenter
 text: "Hide inline drawer"
 checkable: true
 checked: true
 onCheckedChanged: myDrawer.visible = checked
 }

 Kirigami.OverlayDrawer {
 id: myDrawer
 edge: Qt.BottomEdge
 modal: false

 contentItem: Controls.Label {
 text: "Peekaboo!"
 }
 }
 }
 }
}

Примечание

В KDE Plasma со стандартным оформлением Breeze бывает сложно определить, включена ли кнопка-переключатель, поскольку при нажатии кнопки окрашиваются в синий цвет. Учитывайте это при создании приложения: возможно, другой элемент управления окажется удобнее для пользователя.

Кнопки панели инструментов

Существует особый тип кнопок, предназначенный для использования на панелях инструментов, — Controls.ToolButton. Наиболее очевидное отличие от обычной Button — оформление, причём кнопки панели инструментов плоские (хотя это можно изменить логическим свойством flat).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.ToolButton"
 width: 600
 height: 600

 header: Controls.ToolBar {
 RowLayout {
 anchors.fill: parent
 Controls.ToolButton {
 icon.name: "application-menu-symbolic"
 onClicked: showPassiveNotification("Kirigami Pages and Actions are better!")
 }
 Controls.Label {
 text: "Global ToolBar"
 horizontalAlignment: Qt.AlignHCenter
 verticalAlignment: Qt.AlignVCenter
 Layout.fillWidth: true
 }
 Controls.ToolButton {
 text: "Beep!"
 onClicked: showPassiveNotification("ToolButton boop!")
 }
 }
 }
}

Элементы выбора

Элементы выбора позволяют сделать выбор или указать параметр. Разные типы лучше всего подходят для разных ситуаций.

Флажки

Controls.CheckBox предназначен для параметров, выбор которых не является взаимоисключающим и у каждого из которых есть явная альтернатива.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.CheckBox"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.CheckBox {
 Layout.alignment: Qt.AlignHCenter
 text: "This checkbox is checked!"
 checked: true
 }
 Controls.CheckBox {
 Layout.alignment: Qt.AlignHCenter
 text: "This checkbox is not checked!"
 checked: false
 }
 }
 }
}

Как видно, пользоваться ими просто. Свойство checked хранит логическое значение, определяющее, включены ли они.

Радиокнопки

Controls.RadioButton предназначен для ситуаций, когда требуется выбрать один вариант из нескольких.

Радиокнопки по умолчанию взаимоисключающие: в одном родительском элементе можно выбрать только одну радиокнопку.

Как и флажки, их можно по умолчанию включить или выключить с помощью свойства checked.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.RadioButton"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {

 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.RadioButton {
 Layout.alignment: Qt.AlignCenter
 text: "Tick!"
 checked: true
 }
 Controls.RadioButton {
 Layout.alignment: Qt.AlignCenter
 text: "Tock!"
 checked: false
 }
 }
 }
}

Переключатели

На настольном компьютере для изменения параметров обычно требуется изменить параметр, а затем применить его нажатием кнопки «Применить» или «ОК». На мобильных устройствах вместо этого можно использовать Controls.Switch.

Переключатели можно переключать между включённым и выключенным состояниями. Переключить их можно щелчком или касанием, а также перетаскиванием в положение «включено» или «выключено». Как и раньше, с помощью свойства checked можно сделать переключатели включёнными или выключенными по умолчанию.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Switch"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Switch {
 Layout.alignment: Qt.AlignCenter
 text: "Switchy"
 checked: true
 }
 Controls.Switch {
 Layout.alignment: Qt.AlignCenter
 text: "Swootchy"
 checked: false
 }
 }
 }
}

Ползунки

Ползунки позволяют выбирать определённые значения, перемещая ручку по дорожке. Существует несколько типов, из которых можно выбрать подходящий в зависимости от значений, которые должны выбирать пользователи в приложении.

Стандартные ползунки и ползунки с отметками

Стандартный Controls.Slider позволяет очень точно управлять выбором нужного значения.

В режиме «Слева направо» ползунки в горизонтальной ориентации перемещаются слева направо для увеличения значения, а в режиме «Справа налево» — в обратном направлении. В обоих режимах ползунки в вертикальной ориентации перемещаются снизу вверх.

Цветовая заливка служит наглядным показателем того, насколько велико выбираемое значение.

Следует обратить внимание на несколько важных свойств ползунков:

value: содержит значение, на котором расположена ручка; его также можно задать вручную, чтобы указать начальное значение по умолчанию
to: определяет диапазон ползунка, задавая максимальное значение, до которого он может доходить
orientation: позволяет задать вертикальную ориентацию ползунка с помощью Qt.Vertical

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Slider"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Slider {
 id: normalSlider
 Layout.alignment: Qt.AlignHCenter
 Layout.fillHeight: true
 orientation: Qt.Vertical
 value: 60
 to: 100
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 text: Math.round(normalSlider.value)
 }
 }
 }
}

Ещё одно полезное свойство — stepSize. Присвоение ему числового значения позволяет создать ползунок, который привязывается к значениям, кратным указанному stepSize, причём эти кратные значения отмечаются делениями. Так, если присвоить этому свойству значение 2.0, то при перетаскивании ручки ползунка можно будет выбрать только 0.0, 2.0, 4.0 и т. д. вплоть до значения, указанного в свойстве to.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Slider (with steps)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Slider {
 id: tickmarkedSlider
 Layout.alignment: Qt.AlignHCenter
 Layout.fillWidth: true
 orientation: Qt.Horizontal
 snapMode: Controls.Slider.SnapAlways
 value: 6.0
 to: 10.0
 stepSize: 2.0
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 text: tickmarkedSlider.value
 }
 }
 }
}

Ползунки диапазона

QtQuick Controls также предоставляет Controls.RangeSliders. У них две ручки, что позволяет задать диапазон чисел между ними.

Следует помнить о двух новых свойствах: first.value и second.value, которые хранят значения двух ручек. Как и свойство value стандартных ползунков, их можно задать заранее.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.RangeSlider"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.RangeSlider {
 id: rangeSlider
 Layout.alignment: Qt.AlignHCenter
 to: 10.0
 first.value: 2.0
 second.value: 8.0
 stepSize: 1.0
 snapMode: Controls.Slider.SnapAlways
 }
 RowLayout {
 Layout.alignment: Qt.AlignHCenter
 Layout.fillWidth: true
 Controls.Label {
 Layout.fillWidth: true
 text: "The slider's first value is: " + Math.round(rangeSlider.first.value)
 }
 Controls.Label {
 Layout.fillWidth: true
 text: "The slider's second value is: " + Math.round(rangeSlider.second.value)
 }
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 font.bold: true
 text: "Is the selected range between 2 and 8?"
 }
 Controls.Button {
 Layout.alignment: Qt.AlignHCenter
 icon.name: {
 if (rangeSlider.first.value >= 2 && rangeSlider.second.value <= 8)
 return "emblem-checked"
 else
 return "emblem-error"
 }
 }
 }
 }
}

Docs: Компоновки форм

Mon, 01 Jan 0001 00:00:00 +0000

Компоненты Kirigami.FormLayout упрощают создание форм, соответствующих Рекомендациям по человеко-машинному интерфейсу KDE. Они оптимальны для диалогов параметров и больших групп связанных между собой элементов управления и полей ввода.

Если места достаточно, компоновки форм занимают два столбца. Левый столбец занимают надписи, заданные для дочерних компонентов формы, а правый — сами дочерние компоненты. В окнах с ограниченным пространством (или на мобильных устройствах) формы состоят из одного вертикального столбца, в котором надписи дочерних компонентов размещаются над соответствующими компонентами.

Простая форма

Компоненты Kirigami.FormLayout по своему использованию аналогичны компонентам QtQuick Layout, таким как ColumnLayout или RowLayout. Дочерние компоненты автоматически упорядочиваются в соответствии с размером, доступным компоновке формы.

У дочерних компонентов Kirigami.FormLayout есть свойство Kirigami.FormData.label. Это свойство позволяет задать надпись, которая будет показываться для соответствующего дочернего компонента.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 pageStack.initialPage: Kirigami.Page {

 Kirigami.FormLayout {
 anchors.fill: parent

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
 }
 }
}

Простая компоновка формы в режиме рабочего стола

Разделы и разделители

Компоновки форм также можно разделять на разделы. Указать, где начинается раздел, так же просто, как установить для дочернего компонента свойство Kirigami.FormData.isSection в значение true. Это добавит компоненту дополнительный отступ сверху, обозначающий начало нового раздела.

Компоненты Kirigami.Separator лучше всего подходят для начала новых разделов. Разделители служат для рисования тонкой горизонтальной линии, обозначающей конец раздела. Если линия между разделами не нужна, можно использовать свойство стандартного элемента QML Item. Либо можно использовать свойство Kirigami.FormData.isSection любого другого компонента.

Однако это не рекомендуется. В компонентах, у которых для Kirigami.FormData.isSection задано значение true, текст надписи, указанный в свойстве Kirigami.FormData.label этого компонента, показывается как текст заголовка раздела.

Предупреждение

Это относится не ко всем компонентам, поэтому рекомендуется использовать компоненты Kirigami.Separator или Item там, где предполагается использовать текст заголовка.

Этот текст заголовка крупнее обычного текста надписи и служит наглядным ориентиром, поясняющим назначение раздела компоновки формы.

Kirigami.FormLayout {
 anchors.fill: parent

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
 Kirigami.Separator {
 Kirigami.FormData.isSection: true
 Kirigami.FormData.label: "New Section!"
 }
 ColumnLayout {
 Kirigami.FormData.label: "Radio buttons"
 Controls.RadioButton {
 text: "Radio 1"
 checked: true
 }
 Controls.RadioButton {
 text: "Radio 2"
 }
 Controls.RadioButton {
 text: "Radio 3"
 }
 }
 Item {
 Kirigami.FormData.isSection: true
 Kirigami.FormData.label: "Another Section! (lineless though)"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 4:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 5:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 5:"
 }
}

Компоновка формы с разделами

Принудительное применение компоновки рабочего стола или мобильного устройства

Если требуется, чтобы компоновка формы оставалась неизменной независимо от окружения приложения, можно использовать свойство wideMode компонента Kirigami.FormLayout:

Если задано значение true, компоновка формы будет построена как широкоэкранная (двухколоночная), оптимизированная для рабочего стола
Если задано значение false, компоновка формы будет построена как мобильная (в один столбец)

Kirigami.FormLayout {
 anchors.fill: parent
 wideMode: false

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
}

Компоновка формы с принудительной мобильной компоновкой

Выравнивание меток

Иногда требуется назначить надпись компонентам, занимающим более одной строки, или списку компонентов. Это можно сделать, поместив Kirigami.FormData.label в ColumnLayout, как можно было заметить в разделе Разделы и разделители. По умолчанию надпись располагается по вертикальному центру компоновки, что не всегда желательно. Это можно изменить с помощью Kirigami.FormData.labelAlignment.

Kirigami.FormLayout {
 anchors.fill: parent

 ColumnLayout {
 Kirigami.FormData.label: "This is a label:"
 Kirigami.FormData.labelAlignment: Qt.AlignTop

 Controls.Label {
 text: "This is some rather long text \nthat should elide to multiple lines \nto show how the label gets aligned."
 elide: Text.elideLeft
 }
 }
}

Компоновка формы с надписью, выровненной по верхнему краю

Настройка выравнивания меток особенно удобна для управления компонентами или списками компонентов, размер которых заранее неизвестен. Отличный пример этого — Elisa:

Надпись Comment выравнивается по верхнему краю, только если связанный с ней компонент занимает больше одной строки.

Нечто подобное можно сделать с помощью тернарного оператора JavaScript:

Kirigami.FormLayout {
 anchors.fill: parent

 ColumnLayout {
 Kirigami.FormData.label: "This is a label:"
 Kirigami.FormData.labelAlignment: labelText.text.lineCount > 1 ? Qt.AlignTop : Qt.AlignVCenter

 Controls.Label {
 id: labelText
 text: "This is some rather long text \nthat should elide to a new line \nso it appears below the Form Label."
 elide: Text.elideLeft
 }
 }
}

Docs: Встроенные сообщения

Mon, 01 Jan 0001 00:00:00 +0000

Встроенные сообщения позволяют сразу уведомить пользователей о том, что произошло во время работы с приложением.

Простое встроенное сообщение

У компонентов Kirigami.InlineMessage есть два важных свойства, которые следует учитывать:

visible: по умолчанию для него задано значение false, поэтому сообщение показывается только тогда, когда это явно требуется. Это можно изменить, присвоив ему значение true. Когда скрытое встроенное сообщение становится видимым, воспроизводится приятная анимация.
text: здесь задаётся текст встроенного сообщения.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Page {

 ColumnLayout {
 Kirigami.InlineMessage {
 id: inlineMessage
 Layout.fillWidth: true
 text: "Hello! I am a siiiiiiimple lil' inline message!"
 }

 Controls.Button {
 text: "Show inline message!"
 onClicked: inlineMessage.visible = !inlineMessage.visible
 }
 }
}

Различные типы

Обычные встроенные сообщения похожи на приведённые выше: у них синий фон и значок по умолчанию. Это можно изменить с помощью свойства type, которое позволяет задать другой тип встроенного сообщения. Доступны четыре типа:

Информация (Kirigami.MessageType.Information): используется по умолчанию. Имеет синий фон, значок «i» и служит для сообщения о результате или передачи пользователю общих сведений. Задавать его вручную не требуется.
Положительное (Kirigami.MessageType.Positive): имеет зелёный фон и значок галочки, и указывает, что всё прошло хорошо.
Предупреждение (Kirigami.MessageType.Warning): имеет оранжевый фон, значок с восклицательным знаком и позволяет предупредить пользователя о том, на что следует обратить внимание.
Ошибка (Kirigami.MessageType.Error): имеет красный фон, значок с крестом и позволяет сообщить пользователю о том, что что-то пошло не так.

ColumnLayout {

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hello! Let me tell you something interesting!"
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hey! Let me tell you something positive!"
 type: Kirigami.MessageType.Positive
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hmm... You should keep this in mind!"
 type: Kirigami.MessageType.Warning
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Argh!!! Something went wrong!!"
 type: Kirigami.MessageType.Error
 visible: true
 }

}

Настройка текста и значков

Встроенные сообщения поддерживают форматированный текст, который можно задать с помощью простой разметки в стиле HTML. Это позволяет добавить форматирование к тексту встроенного сообщения или даже, при желании, включить внешнюю веб-ссылку.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 // Примечание: если в строке используются кавычки, их придётся экранировать!
 text: "Check out <a href=\"https://kde.org\">KDE's website!<a/>"
 onLinkActivated: Qt.openUrlExternally(link)
 visible: true
}

Значок, показываемый в левом верхнем углу сообщения, можно также настроить, указав имя общесистемного значка для свойства icon.source. Эти имена значков должны соответствовать значкам, установленным в системе; чтобы просмотреть и найти доступные в системе значки и узнать их имена, можно воспользоваться таким приложением, как Cuttlefish из состава plasma-sdk.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Look at me! I look SPECIAL!"
 icon.source: "actor"
 visible: true
}

Использование действий во встроенных сообщениях

Если встроенные сообщения должны быть интерактивными, к ним можно прикрепить действия Kirigami. Как и со страницами, это делается присвоением свойству InlineMessage.actions значения Kirigami.Action либо массива, содержащего компоненты Kirigami.Action.

ColumnLayout {

 Kirigami.InlineMessage {
 id: actionsMessage
 Layout.fillWidth: true
 visible: true

 readonly property string initialText: "Something is hiding around here..."
 text: initialText

 actions: [
 Kirigami.Action {
 enabled: actionsMessage.text == actionsMessage.initialText
 text: qsTr("Add text")
 icon.name: "list-add"
 onTriggered: {
 actionsMessage.text = actionsMessage.initialText + " Peekaboo!";
 }
 },
 Kirigami.Action {
 enabled: actionsMessage.text != actionsMessage.initialText
 text: qsTr("Reset text")
 icon.name: "list-remove"
 onTriggered: actionsMessage.text = actionsMessage.initialText
 }
 ]
 }
}

Кнопки закрытия

Встроенные сообщения содержат кнопку закрытия, позволяющую легко их закрыть.

По умолчанию эта кнопка закрытия скрыта, но это можно изменить, присвоив свойству showCloseButton значение true.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Please don't dismiss me..."
 showCloseButton: true
 visible: true
}

Docs: Панели действий

Mon, 01 Jan 0001 00:00:00 +0000

Хотя страницы Kirigami позволяют легко разместить набор действий в заголовке страницы, иногда требуется более гибкое решение.

Kirigami предоставляет компонент Kirigami.ActionToolBar. Он принимает список объектов Kirigami.Action и показывает столько из них, сколько возможно, а для не помещающихся предоставляет меню переполнения. ActionToolBar динамичен и перемещает действия в меню переполнения и обратно в зависимости от доступного размера.

Примечание

На этой странице предполагается знакомство с объектами Kirigami.Action. Если нет, узнать о них всё можно в нашем руководстве для начинающих или на странице документации, посвящённой им.

Создание первой панели действий

Компоновка и расположение вашей Kirigami.ActionToolBar полностью зависят от вас, однако ради удобства пользователя обычно лучше придерживаться соглашений пользовательского интерфейса: размещать панель инструментов в верхней или нижней части страницы и растягивать её по ширине.

Как и большинство других компонентов, содержащих действия, Kirigami.ActionToolBar имеет свойство actions. Этому свойству можно назначить массив компонентов Kirigami.Action.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 title: "ActionToolBar App"
 width: 600
 height: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.ActionToolBar {
 anchors.left: parent.left
 anchors.right: parent.right

 actions: [
 Kirigami.Action {
 text: "Beep"
 icon.name: "notifications"
 onTriggered: showPassiveNotification("BEEP!")
 },
 Kirigami.Action {
 text: "Action Menu"
 icon.name: "overflow-menu"

 Kirigami.Action {
 text: "Deet";
 icon.name: "notifications"
 onTriggered: showPassiveNotification("DEET!")
 }
 Kirigami.Action {
 text: "Doot";
 icon.name: "notifications"
 onTriggered: showPassiveNotification("DOOT!")
 }
 },
 Kirigami.Action {
 icon.name: "search"
 displayComponent: Kirigami.SearchField { }
 }
 ]
 }
 }
}

Панель действий с достаточным местом для всех дочерних элементов

Панель действий с меню переполнения, содержащим дочерние элементы

Выравнивание

По умолчанию действия в Kirigami.ActionToolBar выравниваются по левому краю. Это подходит не во всех случаях. К счастью, это можно изменить с помощью свойства alignment. Этому свойству можно задать ряд значений, но наиболее важны три: Qt.AlignLeft, Qt.AlignCenter и Qt.AlignRight (они отвечают за выравнивание по горизонтали).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 title: "ActionToolBar App"
 width: 600
 height: 400

 pageStack.initialPage: Kirigami.Page {
 Controls.GroupBox {
 anchors.left: parent.left
 anchors.right: parent.right

 Kirigami.ActionToolBar {
 anchors.fill: parent

 alignment: Qt.AlignCenter

 actions: [
 Kirigami.Action {
 text: "Beep"
 icon.name: "notifications"
 onTriggered: showPassiveNotification("BEEP!")
 }
 ]
 }
 }
 }
}

Docs: Индикаторы выполнения и занятости

Mon, 01 Jan 0001 00:00:00 +0000

Когда приложение выполняет действие, занимающее заметное время, следует использовать визуальный элемент, сообщающий пользователю о том, что в фоне что-то происходит.

QtQuick Controls предоставляет два полезных компонента, которые можно использовать для этого.

Индикатор выполнения

Controls.ProgressBar — компонент, позволяющий легко включить в приложение индикаторы выполнения. Потребуется использовать четыре основных свойства:

from: минимальное значение, соответствующее началу индикатора выполнения
to: максимальное значение, соответствующее концу индикатора выполнения
value: текущее значение выполняемого действия (например, загружено 50%)
indeterminate: если у выполняющегося в данный момент действия нет чёткого значения хода выполнения, этому свойству можно присвоить значение true, чтобы показать пользователю, что что-то происходит, но ход выполнения пока неясен (впрочем, скоро прояснится).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Progressbar App"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.ProgressBar {
 Layout.fillWidth: true
 from: 0
 to: 100
 value: 50
 indeterminate: false
 }
 Controls.ProgressBar {
 Layout.fillWidth: true
 from: 0
 to: 100
 // value: 50
 indeterminate: true
 }
 }
 }
}

Сверху: индикатор выполнения на 50 %; снизу: неопределённый индикатор выполнения

Индикатор занятости

Если время загрузки невелико или измерить прогресс невозможно, можно вместо этого использовать Controls.BusyIndicator. Этот компонент предоставляет простой вращающийся индикатор, показывающий пользователю, что что-то происходит.

Чтобы остановить индикатор, задайте свойству running значение false, в этом случае .

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Progressbar App"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 actions: [
 Kirigami.Action {
 text: "Toggle busy indicator"
 onTriggered: indicator.running ? indicator.running = false : indicator.running = true
 }
 ]
 Controls.BusyIndicator {
 id: indicator
 anchors.centerIn: parent
 }
 }
}

Docs: Представления списков

Mon, 01 Jan 0001 00:00:00 +0000

Представления списков помогают привлекательно показывать объекты из модели. Чтобы использовать представление списка, нужно помнить о трёх вещах:

Модель, содержащая данные, которые должно показывать представление списка
Делегат, который определяет, как будет показываться каждый элемент модели
Само представление списка, которое будет показывать сведения из модели в соответствии с делегатом

Для получения дополнительных разъяснений в документации Qt есть подробная страница по этой теме.

Основы моделей и представлений

Следует обратить внимание на два важных свойства представления списка:

model, принимающее данные или id объекта, который хранит эти данные
delegate, принимающее компонент, который будет использоваться для показа данных в модели

Модель не видна, так как содержит только данные. Обычно делегат заключается в Component для повторного использования: он служит образцом для создания экземпляра каждого делегата.

Ниже приведён пример, содержащий ровно одно представление списка, одну модель и один делегат, с использованием Kirigami.SubtitleDelegate:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

И точно такой же пример, но встроенный:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products (inline)"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 delegate: Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

Понимание моделей

Модель содержит данные, которые будут использоваться для заполнения представления списка. Разные способы использования моделей предполагают разные способы доступа к данным:

Способ использования	Получение доступа	Когда использовать
Модели Qt с несколькими ролями	model.index, model.somerole	В большинстве случаев
Модели Qt с одной ролью	model.index, model.somerole, model.modelData	В большинстве случаев — для прототипирования
Модель массива JavaScript	model.index, model.modelData	Для прототипирования
Модель целых чисел	model.index, model.modelData	Для прототипирования

Прочитать о других способах использования моделей можно в документации Qt.

В таблице выше под «моделями Qt» подразумеваются как модели, специфичные для C++, например QAbstractListModel, так и модели, специфичные для QML, например ListModel. На этой странице руководства рассматриваются только модели, специфичные для QML. Далее приводится руководство по подключению моделей C++ к QML с помощью QAbstractListModel.

Свойство model.index доступно каждой модели и содержит индекс (позицию) каждого делегата. Для удобства его можно сократить до index.

Свойство model.somerole, упомянутое выше, — всего лишь заполнитель, а не конкретное свойство из QML: somerole может быть любой ролью, определённой моделью. В первом примере кода на этой странице, показанном над таблицей, модель plasmaProductsModel имеет роли product и target, к которым можно обратиться с помощью model.product и model.target соответственно.

Как model.index можно сократить до index, так и каждое свойство model.somerole для удобства можно сократить до somerole (например, product), но рекомендуется превратить их в обязательные свойства:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products (shortened with required properties)"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string product
 required property string target
 required property int index
 text: `${product} is KDE software developed for ${target} stored at index ${index} of this list`
 }
 }
 }
}

Кроме того, если модель содержит только одну роль или не содержит ролей вовсе, её данные также доступны через свойство model.modelData, которое можно сократить до modelData (в этом случае оно также должно быть обязательным свойством):

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami


Kirigami.ApplicationWindow {
 title: "List of KDE software"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: kdeSoftwareModel
 delegate: listDelegate
 }
 ListModel {
 id: kdeSoftwareModel
 ListElement { software: "Dolphin" }
 ListElement { software: "Discover" }
 ListElement { software: "KHelpCenter" }
 ListElement { software: "KCalc" }
 ListElement { software: "Ark" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: modelData // Это соответствует model.software
 }
 }
 }
}

Для сравнения, вот как выглядел бы приведённый выше код с массивом JavaScript, без роли:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of KDE software (as JS array)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: ["Dolphin", "Discover", "KHelpCenter", "KCalc", "Ark"]
 delegate: listDelegate
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: modelData
 }
 }
 }
}

Использование целого числа в качестве модели может быть полезно в очень специфичных случаях, а именно при прототипировании и тестировании:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Simple list of indexes"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: 30
 delegate: listDelegate
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: `This delegate's index is: ${modelData}`
 }
 }
 }
}

Понимание представлений и делегатов

Вернёмся к исходному примеру:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 // anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

В отличие от модели (которая лишь содержит данные) и делегата Component (который появляется только при создании экземпляра), представление — это визуальный компонент, создаваемый сразу, поэтому ему нужно либо задать размеры, либо использовать привязки или компоновки.

Поскольку представления обычно представляют собой списки содержимого, которое пользователь хотел бы прокручивать, при добавлении их в Kirigami.ScrollablePage представления становятся основным содержимым с небольшими отступами вокруг, и нет необходимости заставлять их заполнять страницу. Если представление добавлено в простую Kirigami.Page, потребуется правильно задать его размеры, прежде чем оно появится. Иными словами: на прокручиваемой странице выше anchors.fill: parent не требуется; если бы использовалась простая страница, она была бы необходима.

Существует несколько API представлений, которые можно использовать: одни из Qt, другие из Kirigami. Ниже перечислены наиболее часто используемые из них:

ListView в Qt
GridView из Qt
TableView в Qt
TreeView из Qt
CardsListView в Kirigami
ColumnView в Kirigami

С другой стороны, у делегата всегда должны быть заданы размеры. Обычно его размеры задаются так, чтобы он занимал всю ширину представления и только её.

Типичные ошибки

Из вышесказанного следует, что делегаты не должны иметь нижние привязки, поскольку делегату не требуется та же высота, что и у представления. Иными словами, скорее всего, никогда не потребуется использовать anchors.fill: parent.

Кроме того, хотя размеры можно задать с помощью родительского элемента и привязок, в качестве которого обычно выступает contentItem представления, как показано ниже:

Controls.ItemDelegate {
 anchors.left: parent.left
 anchors.right: parent.right
 text: // …
}

Не гарантируется, что родительским элементом делегата будет представление, поэтому этого следует избегать. Вместо этого используйте присоединённое свойство ListView.view, чтобы указать на родительское представление делегата:

Controls.ItemDelegate {
 width: ListView.view.width
 text: // …
}

Чаще всего делегат используется внутри Component, который не создаёт экземпляр делегата сразу. При построении представления делегат применяется как шаблон для создания каждого элемента представления.

Хотя собственные компоненты для использования в качестве делегатов можно создавать и без специальных API Qt для делегатов (например, Layout, содержащий несколько элементов), QtQuick Controls всё же предоставляет API делегатов, которые проще в использовании:

ItemDelegate (делегаты, содержащие только текст)
CheckDelegate (делегаты с флажком)
RadioDelegate (делегаты с радиокнопкой)
SwitchDelegate (делегаты с переключателем)
SwipeDelegate (делегаты с поддержкой смахивания)

По возможности следует отдавать предпочтение исходным делегатам Qt.

Помимо этих делегатов Qt, Kirigami предоставляет собственные аналоги с дополнительной функциональностью подзаголовков и значков:

API, оканчивающийся на «Delegate», можно назначить непосредственным делегатом представления — как и в предыдущих примерах, где использовался Controls.ItemDelegate:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.kirigami.delegates as KD

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 KD.CheckSubtitleDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target}.`
 subtitle: `This delegate is stored at index ${model.index} of this list`
 icon.name: "kde"
 }
 }
 }
}

Предполагается, что как TitleSubtitle, так и IconTitleSubtitle применяются для переопределения contentItem делегата Qt, например:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.kirigami.delegates as KD

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 // anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target}.`
 contentItem: KD.IconTitleSubtitle {
 title: parent.text
 subtitle: `This delegate is stored at index ${model.index} of this list`
 icon.name: "kde"
 }
 }
 }
 }
}

Практический пример использования делегатов Kirigami приведён в файле ListItemTest в репозитории Kirigami.

Docs: Понимание CMakeLists

Mon, 01 Jan 0001 00:00:00 +0000

CMake

Во вводном руководстве в качестве системы сборки приложения использовался CMake, однако подробно был рассмотрен лишь один из файлов CMakeLists.txt. Здесь немного подробнее разбирается, как он работает.

CMake полезен, поскольку позволяет автоматизировать большую часть действий, которые необходимо выполнить перед компиляцией.

Корневой файл CMakeLists.txt

Возможно, этот файл CMakeLists.txt уже встречался в первом руководстве:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

Первая строка, cmake_minimum_required(), задаёт версию CMake, которая будет использоваться.

После этого project(kirigami-tutorial) задаёт имя проекта.

Затем идёт раздел, в котором с помощью extra-cmake-modules подключается ряд необходимых параметров CMake и KDE. Они предоставляют набор полезных утилит:

KDEInstallDirs предоставляет удобные переменные, такие как ${KDE_INSTALL_TARGETS_DEFAULT_ARGS}, ${KDE_INSTALL_QMLDIR}, ${KDE_INSTALL_BINDIR} и ${KDE_INSTALL_LIBDIR}.
KDECMakeSettings предоставляет такие возможности, как CMAKE_AUTORCC ON, цель uninstall, которую можно использовать с cmake --build build/ --target uninstall, и ENABLE_CLAZY.
KDECompilerSettings задаёт минимальный стандарт C++, флаги компилятора, такие как -pedantic, и макросы рекомендуемых практик, например -DQT_NO_CAST_FROM_ASCII, требующие явных преобразований, таких как QStringLiteral().
ECMFindQmlModule позволяет убедиться, что зависимость QML времени выполнения будет найдена во время сборки.
ECMQmlModule предоставляет команды CMake, такие как ecm_add_qml_module() и ecm_target_qml_sources().

Следующий раздел важен, так как в нём указывается, какие зависимости будут подключены во время сборки. Рассмотрим первую:

13
14
15
16
17
18
19
20
21
22
23
24
25
26


find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle

find_package() находит и загружает внешнюю библиотеку и её компоненты.
REQUIRED предписывает CMake завершить работу с ошибкой, если пакет не найден.
COMPONENTS — параметр, предшествующий конкретным компонентам подключаемого фреймворка.
Каждое слово после COMPONENTS обозначает конкретный компонент библиотеки.

Примечание

Если требуется добавить в приложение какой-либо из компонентов, перечисленных в документации по API KDE, сведения о добавлении компонента с помощью CMake приведены на правой боковой панели. Например, для Kirigami там будет указано что-то вроде find_package(KF6Kirigami), которое после добавления ECM превращается в:

find_package(KF6 COMPONENTS Kirigami)

Обратите внимание на подключаемые компоненты: если пропустить хотя бы один из используемых в приведённом коде компонентов, приложение не соберётся.

Строка install указывает CMake установить файл .desktop в ${KDE_INSTALL_APPDIR}, что в Linux соответствует $XDG_DATA_DIRS/applications, обычно /usr/share/applications, а в Windows — C:/Program Files/${PROJECT_NAME}/bin/data/applications:

34

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

Последняя строка позволяет CMake вывести, какие пакеты найдены, а при возникновении ошибки сборка немедленно прерывается:

36

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

А выше этого add_subdirectory(src) указывает CMake на папку src/, где обнаруживается ещё один файл CMakeLists.txt.

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Первый файл отвечал за метаданные и поиск библиотек, а этот — за обработку зависимостей и установку приложения. В нём используются следующие вызовы CMake:

add_executable() создаёт исполняемую цель, которая будет использоваться для запуска проекта.
ecm_add_qml_module() создаёт цель модуля QML, доступную через импорт «org.kde.tutorial».
target_sources() добавляет исходные файлы C++ в исполняемую цель.
ecm_target_qml_sources() добавляет файлы QML в модуль.
target_link_libraries() связывает используемые в коде библиотеки C++ с исполняемым файлом. Kirigami здесь не включён, поскольку используется только его модуль QML.
install() устанавливает исполняемый файл в систему.

Документация по двум командам ECM приведена в API extra-cmake-modules для ECMQmlModule.

Здесь вызов ecm_add_qml_module() использован для изменения традиционной исполняемой цели с исходным кодом C++ и превращения её в нечто, способное принимать файлы QML и исходный код C++, доступный из QML, — это называется использованием исполняемого файла в качестве опорной цели модуля QML. Это означает, что файлы QML выполняются непосредственно как часть приложения, что для приложений обычное дело.

Можно также создать с помощью ecm_add_qml_module() отдельный модуль QML, который не использует исполняемый файл в качестве опорной цели. В этом случае создаётся цель библиотеки с помощью add_library(), она связывается с существующей исполняемой целью с помощью target_link_libraries(), а помимо установки библиотеки с помощью install() потребуется завершить модуль QML с помощью ecm_finalize_qml_module(), чтобы создать два файла: qmldir и qmltypes. Эти файлы используются приложениями QtQuick для поиска отдельных модулей QML.

Способ создания отдельного модуля QML нагляднее показан в руководстве Использование отдельных файлов.

Это дополнения, предоставляемые extra-cmake-modules для упрощения использования декларативной регистрации Qt (замены файлов ресурсов Qt).

Примечание

Эти библиотеки должны соответствовать компонентам, включённым в предыдущий файл CMakeLists.txt, иначе эти компоненты не будут включены, и приложение не соберётся.

Документацию по всем трём командам можно найти в API extra-cmake-modules для ECMQmlModule.

src/components/CMakeLists.txt

В руководстве о том, как разделить свой код на отдельные файлы, был представлен новый файл CMake, позволяющий использовать отдельные модули QML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Чтобы CMake прочитал этот файл, в src/CMakeLists.txt нужно добавить вызов add_subdirectory(), указывающий на него.

Вызов add_library() создаёт новую цель с именем kirigami-hello-components. У этой цели будет собственный набор файлов исходного кода и файлов QML, собственные библиотеки для компоновки и так далее, но после компиляции её нужно скомпоновать с исполняемым файлом, созданным в src/CMakeLists.txt. Для этого имя цели добавляется в список библиотек, которые будут скомпонованы с исполняемым файлом в target_link_libraries().

Вызов ecm_add_qml_module() изменяет библиотеку так, чтобы она, как и прежде, принимала файлы QML, но на этот раз требуется использовать GENERATE_PLUGIN_SOURCE. Когда исполняемый файл используется в качестве опорной цели (как в kirigami-hello), создавать код подключаемого модуля не требуется, поскольку он встроен в исполняемый файл; при отдельных модулях QML, таких как kirigami-hello-components, код подключаемого модуля необходим.

В вышестоящем Qt qt_add_qml_module() по умолчанию создаёт подключаемый модуль вместе с модулем QML, но ecm_add_qml_module() из KDE по умолчанию этого не делает для обратной совместимости.

Для отдельных модулей QML также необходимо завершить цель. В основном это означает, что CMake создаёт два файла, qmldir и qmltypes, которые описывают имеющиеся модули QML и экспортируют их символы для использования в библиотеке. Они важны при установке приложения, чтобы запускаемый исполняемый файл мог найти, где находятся файлы QML для каждого модуля, поэтому они автоматически добавляются к цели.

Затем достаточно установить цель, как и раньше.

Когда в следующий раз потребуется добавить дополнительные файлы QML, не забудьте включить их в этот файл. Файлы C++, в которых используется ключевое слово QML_ELEMENT, которое будет рассмотрено значительно позже в руководстве, также можно добавить здесь с помощью target_sources(). Код можно логически разделить, создав дополнительные модули QML с другими импортами по мере необходимости.

Эта настройка пригодится при разработке большинства приложений Kirigami.

Docs: Разбор main.cpp

Mon, 01 Jan 0001 00:00:00 +0000

Роль main.cpp

Для интерфейса приложений Kirigami используется QML, тогда как бэкенд обычно пишется на C++ благодаря скорости и гибкости этого языка. Хотя на предыдущих страницах QML был подробно рассмотрен, необходимо разобраться в коде бэкенда на C++, чтобы создавать приложения, более полезные, чем те, которых можно добиться на чистом QML.

Здесь будет рассмотрен файл main.cpp, созданный на странице Начало работы, чтобы лучше понять, что происходит в центральном файле C++ приложения. Хотя этот main.cpp — базовый, рассматриваемые возможности останутся необходимыми независимо от того, какое приложение будет создано.

Назначение

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

Сначала нужно включить ряд заголовочных файлов Qt, позволяющих использовать их функции. В данном случае включается ряд заголовков Qt, отвечающих за логику приложения, а также позволяющих читать файлы QML.

Затем создаётся экземпляр QApplication, которому присваивается имя app. Для вызова конструктора требуется передать argc и argv.

Также задаются некоторые метаданные, относящиеся к приложению. К ним относятся организация, создавшая приложение, веб-сайт организации и название приложения. Эти свойства задаются вызовом QApplication, при котором создаётся объект, происходящий от QCoreApplication и предоставляющий приложениям цикл обработки событий независимо от того, есть ли у них графический интерфейс (поэтому если программа запущена без графического интерфейса, эти метаданные всё равно будут заданы).

Чтобы приложение хорошо выглядело со значками Breeze и оформлением Breeze от KDE в средах, отличных от Plasma, таких как Windows или GNOME, нужно выполнить три действия:

Инициализируйте средства работы с темами из KIconThemes на платформах, где темы значков не входят в состав системы (например, Windows или MacOS), с помощью KIconTheme::initTheme()
Задайте QStyle с помощью QApplication::setStyle(), чтобы принудительно использовать Breeze вместо встроенного оформления платформы
Задайте стиль QtQuick Controls с помощью QQuickStyle::setStyle(), чтобы принудительно использовать Breeze с qqc2-desktop-style из KDE

Вызов KIconTheme::initTheme() необходимо выполнить до создания QApplication — это позволяет приложению найти значки Breeze для использования. Установка QStyle в Breeze требуется, поскольку в приложении вместо QGuiApplication используется QApplication. Сами элементы управления в окне, такие как кнопки и флажки, будут следовать Breeze благодаря использованию qqc2-desktop-style.

QQmlApplicationEngine позволяет загрузить приложение из файла QML, что и делается в следующей строке. В engine.loadFromModule("org.kde.tutorial", "Main"); QML загружается из импорта URI, определённого в CMake.

Далее проверяется, правильно ли движок загрузил файл QML: список rootObjects() движка должен быть не пуст. После этого приложение можно запустить с помощью app.exec().

Docs: Страница «О программе»

Mon, 01 Jan 0001 00:00:00 +0000

Kirigami.AboutPage позволяет создать страницу, на которой показываются уведомление об авторских правах приложения, список участников и некоторые сведения о платформе, на которой оно запущено.

Сначала предстоит отредактировать файл main.cpp из предыдущих руководств.

main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <KAboutData>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argc, char *argv[])
{
 QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);

 QApplication app(argc, argv);

 KLocalizedString::setApplicationDomain("helloworld");
 QCoreApplication::setOrganizationName(QStringLiteral("KDE"));
 QCoreApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QCoreApplication::setApplicationName(QStringLiteral("Hello World"));

 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 KAboutData aboutData(
 QStringLiteral("helloworld"),
 i18nc("@title", "Hello World"),
 QStringLiteral("1.0"),
 i18n("Hello world application"),
 KAboutLicense::GPL,
 i18n("(c) 2021"));

 aboutData.addAuthor(
 i18nc("@info:credit", "Your name"),
 i18nc("@info:credit", "Author Role"),
 QStringLiteral("your@email.com"),
 QStringLiteral("https://yourwebsite.com"));

 // Set aboutData as information about the app
 KAboutData::setApplicationData(aboutData);

 // Register a singleton that will be accessible from QML.
 qmlRegisterSingletonType(
 "org.kde.example", // How the import statement should look like
 1, 0, // Major and minor versions of the import
 "About", // The name of the QML object
 [](QQmlEngine* engine, QJSEngine *) -> QJSValue {
 // Here we retrieve our aboutData and give it to the QML engine
 // to turn it into a QML type
 return engine->toScriptValue(KAboutData::applicationData());
 }
 );

 // Load an application from a QML file
 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

В файле main.cpp подключается KAboutData — основной компонент фреймворков KDE, позволяющий хранить сведения о приложении. Эти сведения затем могут использоваться многими другими компонентами KDE Frameworks. Создаётся новый объект aboutData с помощью его достаточно полного конструктора по умолчанию, и добавляются сведения об авторе.

После того как все необходимые сведения заданы, вызывается KAboutData::setApplicationData() для инициализации свойств объекта QApplication .

Затем создаётся qmlRegisterSingletonType(). Это позволяет импортировать код C++ как модуль в main.qml с помощью import org.kde.example 1.0.

Первый аргумент — это URI, который будет использоваться для импорта, второй и третий аргументы — соответственно основная и дополнительная версии, четвёртый — имя типа, имя, которое будет использоваться при обращении к типу About, а последний — ссылка на объект C++, доступный в QML. В последнем случае используется лямбда-выражение, чтобы создать aboutData приложения на месте.

main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

import org.kde.example 1.0

Kirigami.ApplicationWindow {
 id: root

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "gtk-quit"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 },

 Kirigami.Action { // <==== Action to open About page
 text: i18n("About")
 icon.name: "help-about"
 onTriggered: pageStack.layers.push(aboutPage)
 }
 ]
 }

 Component { // <==== Component that instantiates the Kirigami.AboutPage
 id: aboutPage

 Kirigami.AboutPage {
 aboutData: About
 }
 }

 ListModel {
 id: kountdownModel
 }

 AddEditSheet {
 id: addEditSheet
 onAdded: kountdownModel.append({
 "name": name,
 "description": description,
 "date": Date.parse(kdate)
 });
 onEdited: kountdownModel.set(index, {
 "name": name,
 "description": description,
 "date": Date.parse(kdate)
 });
 onRemoved: kountdownModel.remove(index, 1)
 }

 function openPopulatedSheet(mode, index = -1, listName = "", listDesc = "", listDate = "") {
 addEditSheet.mode = mode
 addEditSheet.index = index;
 addEditSheet.name = listName
 addEditSheet.description = listDesc
 addEditSheet.kdate = listDate

 addEditSheet.open()
 }


 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: openPopulatedSheet("add")
 }
 ]

 Kirigami.CardsListView {
 id: layout
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

Сначала используется импорт, определённый в файле main.cpp, а именно org.kde.example. Затем в глобальную выдвижную панель добавляется Kirigami.Action, открывающий страницу «О программе», и создаётся компонент, содержащий Kirigami.AboutPage, который ожидает объект KAboutData::applicationData(). Именно это и было предоставлено в файле main.cpp под именем About, поэтому его можно передать здесь.

CMakeLists

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


cmake_minimum_required(VERSION 3.16)
project(helloworld)

find_package(ECM REQUIRED NO_MODULE)

set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)

find_package(Qt6 REQUIRED NO_MODULE COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami2
 I18n
 CoreAddons
)

add_subdirectory(src)

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

В файле CMakeLists.txt в папке верхнего уровня в вызове find_package() должен присутствовать CoreAddons. Он необходим для KAboutData.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


add_executable(helloworld)

target_sources(helloworld PRIVATE
 main.cpp
 resources.qrc
)

target_link_libraries(helloworld
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::Kirigami2
 KF6::I18n
 KF6::CoreAddons
)

В файле CMakeLists.txt в папке src/ ничего не требуется, поскольку aboutData создан непосредственно на месте.

Запуск приложения

Теперь, если запустить приложение и вызвать действие «О программе» в глобальной выдвижной панели, должна показаться наша страница «О программе».

Docs: Подключение логики к пользовательскому интерфейсу QML

Mon, 01 Jan 0001 00:00:00 +0000

Чтобы внедрить логику в приложение, нужны классы бэкенда на C++, способные выполнять важные вычисления. Писать логику в файлах QML не рекомендуется, поэтому следует перенести как можно больше в бэкенд, чтобы QML использовался только для показа пользовательского интерфейса.

За основу будет взят код руководства Использование отдельных файлов в проекте на C++.

Структура проекта

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml ----------------------- # Modified
└── components/
├── CMakeLists.txt ------------- # Modified
├── AddDialog.qml
├── KountdownDelegate.qml
├── ExposePage.qml ------------- # New
├── backend.h ------------------ # New
└── backend.cpp ---------------- # New

Изменения в существующем коде

src/components/backend.h

Сначала создайте заголовочный файл, в котором будет код, доступный для QML, а именно тип Backend:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON

public:
 explicit Backend(QObject *parent = nullptr);
};

Чтобы сделать код C++ доступным для QML, нужно выполнить два действия, и одно из них — просто использовать макрос QML_ELEMENT, доступный в заголовочном файле <QtQml/qqmlregistration.h>.

Бэкенд будет создан как синглтон: он создаётся только один раз и существует в течение всего времени работы приложения. Для этого используется макрос QML_SINGLETON.

src/components/backend.cpp

Можно добавить начальный код конструктора в backend.cpp:

1
2
3
4
5


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

src/components/ExposePage.qml

С этого момента QML будет знать бэкенд как тип QML Backend. Он содержится в модуле org.kde.tutorial.components.

Это означает, что достаточно добавить импорт в файл QML, чтобы использовать код, предоставляемый из C++:

import org.kde.tutorial.components

Чтобы начать с чистого листа, используя существующий код приложения, создайте новый компонент QML, содержащий пустую страницу:

1
2
3
4
5
6
7


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 // ...
}

src/Main.qml

Чтобы новая страница действительно показывалась, создадим пункт меню, который помещает новую страницу в приложение, — просто чтобы модель было проще проверить.

Для этого можно использовать новый Kirigami.Action вместе с Qt.createComponent(), чтобы создавать страницу динамически:

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

src/components/CMakeLists.txt

Наконец, добавьте только что созданные файлы backend.h, backend.cpp и ExposePage.qml в CMake:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Добавление файлов в существующий модуль QML в CMake — вторая часть предоставления кода для QML.

Следует отметить, что модуль QML должен быть создан с помощью ecm_add_qml_module() или qt_add_qml_module(), поскольку они необходимы для декларативной регистрации.

Теперь можно собрать и установить проект, выполнив те же шаги, что и раньше.

Придание функциональности

src/components/backend.h

Теперь класс, содержащий будущую логику, подключён к приложению, но он всё ещё ничего не делает. Чтобы это изменить, добавим в класс свойство. Свойства — это гораздо больше, чем простая переменная. Они могут сообщать пользовательскому интерфейсу об изменениях, чтобы он обновлял нужные области.

Непосредственно под макросом QML_SINGLETON добавьте новый макрос Q_PROPERTY.

Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)

Может показаться, что для простого чтения и записи кода из бэкенда требуется слишком много кода. Однако при более внимательном рассмотрении видно, что чтение свойства из пользовательского интерфейса уже может выполнять некоторую логику — то же самое при его записи. В этом случае свойство автоматически уведомит интерфейс и бэкенд об изменениях.

Чтение и запись основаны на концепции функций получения и установки. Добавьте в свой класс новый закрытый атрибут, хранящий данные, а также функции получения и установки для него.

Добавьте новый закрытый раздел со следующим кодом:

private:
 QString m_introductionText = QStringLiteral("Hello World!");

И добавьте следующий код в существующий раздел public:

public:
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();

Первая функция — геттер (функция получения), вторая — сеттер (функция установки), а третья — сигнал, испускаемый при изменении свойства. Они соответствуют частям READ, WRITE и NOTIFY приведённого выше Q_PROPERTY.

В результате должно получиться следующее:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

Сигнал не требует реализации в файле backend.cpp, поскольку от него требуется лишь испускание, а функции получения и установки нужно реализовать так, как показано ниже:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

Как видно, при вызове функции установки будет испущен сигнал, который уведомит пользовательский интерфейс и бэкенд об изменении.

src/components/ExposePage.qml

Чтобы показать текст, добавьте Kirigami.Heading в src/components/ExposePage.qml под свойством title компонента Kirigami.Page, добавленного в код.

В результате код в этой части файла должен выглядеть так:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

Наше приложение на данный момент

Существующий код:

CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

src/main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

src/components/KountdownDelegate.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

src/components/AddDialog.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

Код, написанный или изменённый на этой странице:

src/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

src/components/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

src/components/backend.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

src/components/ExposePage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

Теперь соберите и снова запустите программу. На новой странице появится выровненный по центру заголовок Heading с текстом «Hello World!».

Поздравляем, вы изучили:

Регистрация типов бэкенда в QML
Добавление новых элементов в файл QML
Создание новых подклассов QObject
Добавление свойств и их назначение
Что такое сигналы

Чтобы узнать больше о взаимодействии QML и C++, рекомендуется прочитать официальную документацию Qt.

Docs: Подключение моделей C++ к пользовательскому интерфейсу QML

Mon, 01 Jan 0001 00:00:00 +0000

Как показано в предыдущем руководстве, код C++ можно подключить к QML, создав класс, который будет восприниматься как ещё один компонент QML. Однако может потребоваться представить более сложные данные, например данные, которые должны выступать в роли пользовательской ListModel или каким-либо образом делегироваться из Repeater.

Можно создать собственные модели со стороны C++ и объявить, как данные из этой модели должны быть представлены в интерфейсе QML.

Настоятельно рекомендуется перед этим руководством прочитать руководство Представления списков.

За основу кода для этого руководства будет взята предыдущая страница — Подключение логики к пользовательскому интерфейсу QML.

Структура проекта

kirigami-tutorial/
├── CMakeLists.txt --------------------- # Modified for didactic purposes
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml ----------------------- # Modified
└── components/
├── CMakeLists.txt ------------- # Modified
├── AddDialog.qml
├── KountdownDelegate.qml
├── ExposePage.qml
├── ModelsPage.qml ------------- # New
├── model.h -------------------- # New
├── model.cpp ------------------ # New
├── backend.h
└── backend.cpp

Создание новой страницы для руководства по моделям

Прежде чем что-либо делать, добавьте новую страницу в код QML.

Сначала в файле src/Main.qml добавьте следующее действие в глобальную выдвижную панель:

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("C++ models in QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ModelsPage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

Затем создайте новый файл src/components/ModelsPage.qml со следующим содержимым:

1
2
3
4
5
6
7
8
9


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 // ...
}

И наконец, добавьте его в src/components/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Это послужит холстом для страницы руководства.

Использование необработанных строк

Чтобы в этом руководстве было проще понять, как заполняется модель, будет отключена функция, которую приложения KDE, использующие extra-cmake-modules (ECM), применяют по умолчанию и которая оптимизирует код строк. Это позволит обойтись без необходимости писать QStringLiteral() каждый раз при введении строки в коде C++, что пригодится для кода в следующем заголовочном файле.

В корневом файле CMakeLists.txt добавьте следующий код:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)
remove_definitions(-DQT_NO_CAST_FROM_ASCII)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

🚨 Не делайте этого в рабочей эксплуатации

Отключение этого флага CMake преследует исключительно учебные цели. В рабочем коде следует по возможности использовать QStringLiteral() или пространство имён строковых литералов Qt.

Подготовка класса

Будет создан класс, содержащий QMap, в котором в качестве ключа используется QString, а в качестве значений — объекты QStringList. Интерфейс сможет читать и показывать ключи и значения, а работать с ним будет так же просто, как с одномерным массивом. Он должен быть похож на QML ListModel.

Для этого создайте класс, наследующий от QAbstractListModel. Также добавьте некоторые данные в QMap. Эти объявления будут находиться в model.h.

Создайте два новых файла: src/components/model.h и src/components/model.cpp.

Добавьте эти два новых файла в src/components/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
 model.cpp model.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Добавьте в файл src/components/model.h следующий код в качестве начального содержимого:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

Конечно, нельзя просто показать этот класс как есть. Кроме того, нужно сообщить QML, как представлять эти данные в классе. Это делается переопределением трёх основных виртуальных функций:

rowCount() — эту функцию можно рассматривать как способ сообщить QML, сколько элементов должна представить модель.
roleNames() — имена ролей можно рассматривать как имена свойств, привязанных к данным в QML. Эта функция позволяет создавать эти роли.
data() — эта функция вызывается, когда требуется получить данные, соответствующие именам ролей из модели.

Примечание

Пользовательские имена ролей, созданные функцией roleNames(), доступны только при делегировании модели и недоступны вне этого. См. Модели и представления.

Примечание

Технически модели в Qt представляются в виде таблиц со строками и столбцами. Переопределение rowCount() сообщает Qt, сколько строк содержится в модели. Поскольку в этом руководстве рассматривается лишь одномерный массив, «строки» можно понимать просто как «количество элементов».

Переопределение и реализация `rowCount()`

Переопределим функцию в заголовочном файле src/components/model.h. Функция rowCount() принимает собственный параметр, но в этом примере он не используется, поэтому его можно не именовать.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 int rowCount(const QModelIndex &) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

Затем объявите в файле src/components/model.cpp, сколько строк содержит эта модель:

1
2
3
4
5


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

Переопределение и реализация `roleNames()`

Прежде чем переопределять roleNames(), нужно объявить роли на стороне C++ с помощью открытого перечисления. Причина в том, что эти значения перечисления передаются в data() каждый раз, когда QML обращается к соответствующей роли, и благодаря этому data() можно заставить возвращать нужные данные.

Начнём с создания перечисления ролей в src/components/model.h, где каждое значение — роль для стороны C++.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };

 QHash<int, QByteArray> roleNames() const override;
 int rowCount(const QModelIndex &) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

После того как с этим разобрались, можно наконец создать то, что представляют собой эти роли на стороне QML, с помощью QHash, где ключами служат значения перечисления, сопоставленные с QByteArray. Это должно находиться в src/components/model.cpp. Именно текст в QByteArray используется в самом коде QML.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

В модели из нашего примера роль «species» позволяет получить ключ QString «Feline», «Fox», «Goat», каждый в отдельном делегате. То же можно сделать со значениями QStringList для списка имён персонажей.

Переопределение и реализация `data()`

В data() передаются два параметра: index и role. index — это позиция данных в модели. Как уже отмечалось, role используется QML для получения конкретных данных при обращении к роли.

В data() можно использовать оператор switch, чтобы возвращать подходящие данные и тип данных в зависимости от роли, что возможно, поскольку data() возвращает QVariant. Однако всё же нужно убедиться, что получено нужное местоположение данных. В приведённом ниже примере видно, что объявляется новая переменная-итератор, которая задаётся как начало списка плюс строка индекса, и возвращаются данные, на которые указывает итератор.

Однако нельзя просто вернуть любые данные. Может возникнуть попытка привязать данные к свойству с несовместимым типом данных, например QStringList к QString. Чтобы данные показывались правильно, может потребоваться преобразование данных. Для этого создадим новую закрытую статическую функцию с именем formatList().

В результате в файле src/components/model.cpp получается следующий код:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

А в файл src/components/model.h добавьте следующий код:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

Использование класса в QML

Используемый файл QML будет содержать всего три компонента Kirigami.AbstractCard, где ключ — это заголовок, а значение — содержимое. Эти карточки создаются путём делегирования AbstractCard с помощью Repeater, где в качестве модели выступает созданная ранее пользовательская модель. Доступ к данным осуществляется с помощью слова model, за которым следуют роли, объявленные в roleNames().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Controls.Label {
 text: model.characters
 }
 }
 }
 }
}

Изменение данных

Редактирование данных с помощью `dataChanged()` и `setData()`

Может возникнуть ситуация, когда требуется изменить данные в модели и отразить эти изменения на стороне интерфейса. При каждом изменении данных в модели необходимо испустить сигнал dataChanged(), который применит эти изменения на стороне интерфейса в конкретных ячейках, указанных в его аргументах. В этом руководстве можно просто использовать аргумент index функции setData().

setData() — виртуальная функция, которую можно переопределить, чтобы изменение данных со стороны интерфейса автоматически отражалось на стороне бэкенда. Она принимает три параметра:

index — расположение данных.
value — содержимое новых данных.
role — в этом контексте роль служит для того, чтобы сообщить представлениям, как обрабатывать данные. Здесь роль должна быть Qt::EditRole.

В этом случае параметр role используется, чтобы setData() можно было редактировать через пользовательский ввод (Qt::EditRole). С помощью index можно определить местоположение данных, которые следует изменить содержимым value.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

Примечание

setData() не испускает автоматически сигнал dataChanged() — это нужно делать вручную.

Соответствующее дополнение добавьте в файл src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 bool setData(const QModelIndex &index, const QVariant &value, int role) override;
private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

Обновим код QML, чтобы можно было открыть диалог, позволяющий редактировать модель с помощью Controls.Button, прикреплённой к карточкам.

Добавьте следующий Kirigami.PromptDialog в src/components/ModelsPage.qml вместе с новой кнопкой редактирования:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 }
 }
 }
 }
 }
 Kirigami.PromptDialog {
 id: editPrompt
 property var model
 property alias text: editPromptText.text
 title: "Edit Characters"
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: {
 const model = editPrompt.model;
 model.characters = editPromptText.text;
 editPrompt.close();
 }
 Controls.TextField {
 id: editPromptText
 onAccepted: editPrompt.accept()
 }
 }
}

Теперь при изменении значений модели в интерфейсе изменения должны автоматически обновляться в бэкенде.

Добавление строк

Добавлена возможность изменять данные в существующих ключах QMap, и на стороне интерфейса это отражается как изменение содержимого внутри AbstractCards. Но что, если потребуется добавить в QMap новую запись ключа и отразить её на стороне QML? Для этого создадим новый метод, вызываемый со стороны QML и выполняющий эту задачу.

Чтобы сделать метод доступным в QML, объявление метода нужно начинать с макроса Q_INVOKABLE. Этот метод также будет содержать строковый параметр, который станет новым ключом в QMap.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 Q_INVOKABLE void addSpecies(const QString &species);

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

Внутри этого метода нужно сообщить Qt о необходимости создать дополнительные строки в модели. Для этого вызывается beginInsertRows() — так начинается операция добавления строк, — затем вставляется всё необходимое, после чего вызывается endInsertRows() для завершения операции. Однако в конце всё ещё необходимо испустить сигнал dataChanged(). На этот раз предстоит обновить все строки, с первой по последнюю, поскольку QMap может переупорядочиться в алфавитном порядке, и это нужно отследить по всем строкам.

При вызове beginInsertRows() сначала нужно передать класс QModelIndex, чтобы указать место добавления новых строк, а затем — номера первой и последней новых строк. В этом руководстве первым аргументом будет просто QModelIndex(), так как использовать этот параметр здесь не требуется. Для номеров первой и последней строк можно просто взять текущее количество строк, поскольку в конец модели добавляется всего одна строка.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

Примечание

Функция dataChanged() использует QModelIndex в качестве типа данных для своих параметров. Однако целые числа можно преобразовать в типы данных QModelIndex с помощью функции index().

Обновим код QML, чтобы можно было добавить новый ключ в QMap.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 actions: [
 Kirigami.Action {
 icon.name: "list-add-symbolic"
 text: "Add New Species"
 onTriggered: {
 addPrompt.open();
 }
 }
 ]
 Model {
 id: customModel
 }
 ColumnLayout {
 // ...
 }
 Kirigami.PromptDialog {
 id: addPrompt
 title: "Add New Species"
 standardButtons: Kirigami.Dialog.Ok
 onAccepted: {
 customModel.addSpecies(addPromptText.text);
 addPromptText.text = ""; // Clear TextField every time it's done
 addPrompt.close();
 }
 Controls.TextField {
 id: addPromptText
 Layout.fillWidth: true
 onAccepted: addPrompt.accept()
 }
 }
 Kirigami.PromptDialog {
 id: editPrompt
 // ...
 }
}

Теперь в верхней части приложения должно появиться новое действие, открывающее диалог, позволяющий добавить в модель новый элемент с собственными данными.

Удаление строк

Удаление строк выполняется так же, как и добавление строк. Создайте ещё один метод, который будет вызываться в QML. На этот раз будет использоваться дополнительный параметр — целое число, являющееся номером строки. Название вида используется для удаления ключа из QMap, а номер строки — для удаления строки в интерфейсе.

Добавьте в файл src/components/model.h новую функцию Q_INVOKABLE с именем deleteSpecies():

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 Q_INVOKABLE void addSpecies(const QString &species);
 Q_INVOKABLE void deleteSpecies(const QString &speciesName, const int &rowIndex);

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

Соответствующую реализацию добавьте в файл src/components/model.cpp:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

void Model::deleteSpecies(const QString &speciesName, const int& rowIndex) {
 beginRemoveRows(QModelIndex(), rowIndex, rowIndex);
 m_list.remove(speciesName);
 endRemoveRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

Теперь обновим приложение, чтобы кнопка «Удалить» появлялась в RowLayout рядом с кнопкой редактирования внутри AbstractCard, и подключим её к методу удаления.

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 RowLayout {
 Layout.fillWidth: true
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 Controls.Button {
 text: "Delete"
 onClicked: {
 customModel.deleteSpecies(model.species, index);
 }
 }
 }
 }
 }
 }
 }

Наше приложение на данный момент

Существующий код:

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

src/main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

src/components/KountdownDelegate.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

src/components/AddDialog.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

src/components/ExposePage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

src/components/backend.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

Код, написанный или изменённый на этой странице:

CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)
remove_definitions(-DQT_NO_CAST_FROM_ASCII)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

src/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML Tutorial")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("C++ models in QML tutorial")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ModelsPage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

src/components/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
 model.cpp model.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

src/components/ModelsPage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 actions: [
 Kirigami.Action {
 icon.name: "list-add-symbolic"
 text: "Add New Species"
 onTriggered: {
 addPrompt.open();
 }
 }
 ]
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 RowLayout {
 Layout.fillWidth: true
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 Controls.Button {
 text: "Delete"
 onClicked: {
 customModel.deleteSpecies(model.species, index);
 }
 }
 }
 }
 }
 }
 }
 }
 Kirigami.PromptDialog {
 id: addPrompt
 title: "Add New Species"
 standardButtons: Kirigami.Dialog.Ok
 onAccepted: {
 customModel.addSpecies(addPromptText.text);
 addPromptText.text = ""; // Clear TextField every time it's done
 addPrompt.close();
 }
 Controls.TextField {
 id: addPromptText
 Layout.fillWidth: true
 onAccepted: addPrompt.accept()
 }
 }

 Kirigami.PromptDialog {
 id: editPrompt
 property var model
 property alias text: editPromptText.text
 title: "Edit Characters"
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: {
 const model = editPrompt.model;
 model.characters = editPromptText.text;
 editPrompt.close();
 }
 Controls.TextField {
 id: editPromptText
 onAccepted: editPrompt.accept()
 }
 }
}

src/components/model.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 bool setData(const QModelIndex &index, const QVariant &value, int role) override;
 Q_INVOKABLE void addSpecies(const QString &species);
 Q_INVOKABLE void deleteSpecies(const QString &speciesName, const int &rowIndex);
private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

src/components/model.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

void Model::deleteSpecies(const QString &speciesName, const int& rowIndex) {
 beginRemoveRows(QModelIndex(), rowIndex, rowIndex);
 m_list.remove(speciesName);
 endRemoveRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

Дополнительные сведения

Дополнительные сведения см. в разделах Использование моделей C++ с представлениями Qt Quick и Программирование модель/представление.

Docs: Введение в Kirigami Addons

Mon, 01 Jan 0001 00:00:00 +0000

Kirigami Addons — это дополнительный набор визуальных компонентов, которые хорошо работают на мобильных устройствах и настольных компьютерах и гарантированно являются кроссплатформенными. Для создания компонентов используется Kirigami.

Здесь будет настроен новый проект Kirigami Addons, а также представлены несколько полезных компонентов.

Эти компоненты используют средства локализации KDE, поэтому прежде чем приступить к их использованию, потребуется создать небольшой проект, в котором применяется KLocalizedContext.

Настройка проекта

Начальная структура проекта будет выглядеть так:

addonsexample/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

Совет

Эту структуру файлов можно быстро создать с помощью:

mkdir -p addonsexample/contents/ui
touch addonsexample/{CMakeLists.txt,main.cpp}
touch addonsexample/Main.qml

Начнём с использования вполне стандартного CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)

project(FormCardTutorial)

find_package(ECM REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECompilerSettings)
include(KDECMakeSettings)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Widgets # For QApplication
 Quick # For QML
 QuickControls2 # For QQuickStyle
)
find_package(KF6 REQUIRED COMPONENTS
 CoreAddons # For KAboutData
 I18n # For KLocalizedContext
)
qt_policy(SET QTP0001 NEW)

add_executable(addonsexample)

target_sources(addonsexample PRIVATE main.cpp)

ecm_add_qml_module(addonsexample
 GENERATE_PLUGIN_SOURCE
 URI org.kde.addonsexample
)

ecm_target_qml_sources(addonsexample SOURCES
 Main.qml
 SettingsPage.qml
 JsonAboutPage.qml
)

target_link_libraries(addonsexample PRIVATE
 Qt::Widgets
 Qt::Quick
 Qt::QuickControls2
 KF6::CoreAddons
 KF6::I18n
)

install(TARGETS addonsexample DESTINATION ${KDE_INSTALL_BINDIR})

Интересная часть — main.cpp:

#include <QtQml>
#include <QApplication>
#include <QQmlApplicationEngine>
#include <QIcon>
#include <QQuickStyle>
#include <KAboutData>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argCount, char* argVector[])
{
 QApplication app(argCount, argVector);
 KLocalizedString::setApplicationDomain("org.kde.addonsexample");

 KAboutData aboutData(
 QStringLiteral("addonsexample"),
 i18nc("@title:window", "Addons Example"),
 QStringLiteral("1.0"),
 i18nc("@info", "This program shows how to use Kirigami Addons"),
 KAboutLicense::GPL_V3,
 QStringLiteral("(C) 2023"),
 i18nc("@info", "Optional text shown in the About"),
 QStringLiteral("https://kde.org"));

 aboutData.addAuthor(i18nc("@info:credit", "John Doe"),
 i18nc("@info:credit", "Maintainer"));

 KAboutData::setApplicationData(aboutData);

 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }
 QApplication::setWindowIcon(QIcon::fromTheme(QStringLiteral("kde")));

 QQmlApplicationEngine engine;
 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.addonsexample", "Main");
 app.exec();
}

Если читали руководство по KXmlGui или последнее руководство по Kirigami на странице «О программе» в Kirigami, многое из этого покажется знакомым.

Создаётся приложение, и с помощью конструктора по умолчанию KAboutData добавляются метаданные приложения, в качестве автора указывается сам разработчик, а затем вызывается setApplicationData(), чтобы завершить процесс. Кроме того, на будущее задаётся значок приложения, взятый из системного оформления.

Затем в qmlRegisterSingletonType() используется лямбда-выражение, чтобы напрямую передать метаданные приложения в QML и сделать его свойства доступными.

Затем создаётся экземпляр движка QML, а его контекст настраивается на использование KLocalizedContext из KDE, служащего для интеграции переведённых строк; только что созданный движок передаётся в качестве параметра.

Файл QML просто загружается из файла ресурсов, а теперь остаётся лишь заняться начальным файлом QML.

FormCard и FormButtonDelegate

Идея приложения — создать собственную галерею Kirigami Addons, демонстрирующую несколько компонентов, по одному на странице. Главная страница будет содержать простой список кнопок в ColumnLayout, каждая из которых открывает отдельную страницу.

Изначально наш Main.qml должен выглядеть так:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 // Our code will go here
 }
 }
}

Удобный pageStack используется, чтобы установить в качестве начальной страницы Kirigami.ScrollablePage.

Хотя для достижения цели можно было бы использовать FormLayout вместе с компонентами QtQuick Controls, здесь будет представлен FormCard.

Основное назначение карточки формы — служить контейнером для других компонентов, при этом её цвет отличается от цвета фона, как у Kirigami.Card, однако она предназначена для окон параметров. В приложении можно разместить несколько карточек формы, чтобы обозначить разные разделы. Карточка формы также должна быть непосредственным дочерним элементом ColumnLayout.

Импорт org.kde.kirigamiaddons.formcard делает доступными все компоненты FormCard в файле QML.

На главной странице будет только один раздел, поэтому добавим одну FormCard:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 // Our buttons will go here
 }
 }
 }
}

Замечательная особенность FormCard в том, что компоновка выполняется автоматически. Иными словами, чтобы указать положение компонентов внутри FormCard, достаточно порядка их следования: присоединённые свойства Layout не нужны, а якоря и позиционеры использовать не следует.

В FormCard можно просто добавить несколько кнопок:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 }
 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 }
 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

Вот и всё! Кнопки пока не работают, но теперь всё готово, чтобы поработать со страницами «О программе»!

Затем соберём и запустим его так:

cmake -B build/ -DCMAKE_INSTALL_PREFIX=~/kde5/usr
cmake --build build/
cmake --install build/
aboutexample

Чтобы узнать о других способах сборки приложения (например, в Windows), см. страницу Начало работы с Kirigami.

Docs: Страницы «О программе» в FormCard

Mon, 01 Jan 0001 00:00:00 +0000

Некоторые из этих компонентов позволяют указать авторство своей работы и работы других участников проекта, а также упомянуть используемые в приложении фреймворки: AboutKDE и AboutPage.

О KDE

Каждая новая кнопка, созданная на предыдущем шаге, должна открывать новую страницу. Добавить новые страницы можно, создав их как Components и затем используя pageStack.layers.push() для каждой кнопки, чтобы загрузить эту страницу в Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

Вот и всё! Достаточно создать экземпляр FormCard.AboutKDE. После нажатия кнопки AboutKDE должно появиться примерно следующее:

Страница «О программе»

Страница AboutPage приложения немного сложнее, но пользоваться ею по-прежнему очень просто.

Чтобы создать простую страницу «О программе», использующую данные, заданные с помощью KAboutData::setApplicationData(aboutData); в main.cpp, добавьте в Main.qml следующее:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 Component {
 id: aboutpage
 FormCard.AboutPage {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 onClicked: root.pageStack.layers.push(aboutpage)
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

Страница «О программе» нашего приложения должна выглядеть так:

Использование JSON вместо KAboutData

Вместо того чтобы страница «О программе» получала информацию из KAboutData, можно передать объект JSON напрямую. Тем не менее, чтобы значок приложения показывался, потребуется использовать QApplication::setWindowIcon() в файле main.cpp.

Создайте файл MyAboutPage.qml следующим образом:

import org.kde.kirigamiaddons.formcard as FormCard
import org.kde.about

FormCard.AboutPage {
 title: i18nc("@action:button", "About")
 aboutData: {
 "displayName" : "Addons Example",
 "productName" : "",
 "componentName" : "addonsexample",
 "shortDescription" : "This program shows how to use AboutKDE and AboutPage",
 "homepage" : "https://kde.org",
 "bugAddress" : "",
 "version" : "1.0",
 "otherText" : "Optional text shown in the About",
 "authors" : [
 {
 "name" : "John Doe",
 "task" : "Maintainer",
 "emailAddress" : "",
 "webAddress" : "",
 "ocsUsername" : ""
 }
 ],
 "credits" : [],
 "translators" : [],
 "licenses" : [
 {
 "name" : "GPL v3",
 "text" : "Long license text goes here",
 "spdx" : "GPL-3.0"
 }
 ],
 "copyrightStatement" : "© 2023",
 "desktopFileName" : ""
 }

}

Затем измените файл Main.qml, добавив новую страницу «О программе»:

Основной объект JSON здесь содержит ключи displayName, productName, homepage и так далее. Каждому из ключей authors, credits, translators и licenses можно передать массив объектов. Объекты, передаваемые в authors, credits и translators, используют одни и те же ключи, что позволяет показывать их в отдельных разделах, а licenses содержит ключи name, text и spdx для каждой добавленной лицензии, поскольку один и тот же проект нередко включает несколько лицензий.

Эти ключи необязательны, но ожидается разумный минимум ключей, чтобы в приложении не было пустых полей: displayName, version, description, homepage, copyrightStatement и authors. Тем не менее рекомендуется заполнить как можно больше ключей.

Docs: Делегаты форм на страницах параметров

Mon, 01 Jan 0001 00:00:00 +0000

Теперь, когда в приложение добавлены страницы About и AboutKDE, те же внутренние компоненты позволяют создавать страницы параметров.

Структура проекта должна выглядеть так:

addonsexample
├── CMakeLists.txt
├── main.cpp
├── Main.qml
├── MyAboutPage.qml
└── SettingsPage.qml

Требуемые изменения

Измените Main.qml, чтобы добавить новую страницу параметров:

import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 Component {
 id: aboutpage
 MyAboutPage {}
 }

 Component {
 id: settingspage
 SettingsPage {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 onClicked: root.pageStack.layers.push(aboutpage)
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 onClicked: root.pageStack.layers.push(settingspage)
 }
 }
 }
 }
}

Теперь можно приступить к рассмотрению компонентов, из которых создаётся страница параметров: FormCard и его делегаты.

Делегаты форм

FormCard и FormCardPage

FormCard.FormCard — основной компонент, который будет использоваться для группировки всех его дочерних компонентов — делегатов.

Ранее карточка формы использовалась во введении в Kirigami Addons. Её основное назначение — служить контейнером для других компонентов, при этом цвет карточки отличается от цвета фона, как у Kirigami.Card.

Создайте новый файл SettingsPage.qml:

import QtQuick
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormCard {
 // Здесь размещаются все делегаты!
 }

 FormCard.FormCard {
 // Здесь размещаются все делегаты!
 }
}

Так как для страницы параметров создаётся отдельный файл QML и нужно предусмотреть возможную прокрутку страницы, используется FormCard.FormCardPage, который наследуется от Kirigami.ScrollablePage.

Преимущество страницы карточки формы в том, что она имеет встроенную компоновку, поэтому дополнительный ColumnLayout не нужен, а делегаты добавляются непосредственно в неё.

Примечание

Делегаты FormCard можно использовать напрямую с Kirigami.ScrollablePage, но в этом случае потребуется добавить собственные компоновки.

FormHeader

Для каждой создаваемой FormCard можно создать FormHeader непосредственно перед ней. Заголовок использует полужирное начертание и показывается прямо над карточкой формы.

import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 // Здесь размещаются делегаты…
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 // Здесь размещаются делегаты…
 }
}

FormTextDelegate и FormSectionText

Начнём с простого — с обычного текста.

FormSectionText просто добавляет тонкий делегат, содержащий надпись. FormTextDelegate содержит текст и серое описание.

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18n("Online Account Settings")
 }
 FormCard.FormTextDelegate {
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18n("The Maintainer ™️")
 }
 }
}

Добавляется фиктивный текст для гипотетического определения оформления. Если потребуется настоящее определение цветовой схемы, в будущем это можно сделать по аналогии с Neochat (код здесь), используя модель C++ с KColorSchemeManager.

В разделе «Учётные записи в Интернете» имеется дополнительное свойство leading. К нему можно добавить Item, чтобы он показывался перед текстом. Противоположное свойство trailing позволяет показать Item после текста, но в приложении оно не используется.

Для простоты здесь используется Kirigami.Icon, но это можно также реализовать с помощью Avatar из Kirigami Addons, который получает информацию из модели, как это сделано в Neochat.

В итоге должно получиться так:

FormButtonDelegate

FormButtonDelegate внешне похож на FormTextDelegate, но по нему можно щёлкнуть, и он показывает стрелку, направленную вправо. Ранее он использовался во введении в Kirigami Addons.

В отличие от FormTextDelegate, у которого были свойства leading и trailing для показа элемента до и после основного содержимого, FormButtonDelegate имеет только свойство leading, так как правая сторона занята стрелкой.

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18n("Online Account Settings")
 }
 FormCard.FormTextDelegate {
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18n("The Maintainer ™️")
 }
 FormCard.FormButtonDelegate {
 icon.name: "list-add"
 text: i18n("Add a new account")
 onClicked: console.info("Clicked!")
 }
 }
}

Свойство icon.name используется, чтобы задать значок «плюс» (+), который показывается после места, где показывался бы leading, и перед основным содержимым. Это распространённый приём, указывающий на то, что кнопка добавит что-то в список.

Поскольку этот пример приводится лишь для наглядности, подробно не рассматривается, что произойдёт после нажатия кнопки: она просто выводит в терминал «Clicked!». Можно было бы создать новую страницу создания учётной записи, которая добавляет ещё одного пользователя в модель, а затем вывести страницу на экран — так же, как это сделано в Main.qml.

FormRadioDelegate, FormCheckDelegate и FormSwitchDelegate

Радиокнопки, флажки и переключатели — очень часто используемые компоненты любого пользовательского интерфейса. Kirigami Addons предоставляет их в виде FormRadioDelegate, FormCheckDelegate и FormSwitchDelegate.

Их единственные основные свойства — text и description. Различаются они по применению, поскольку все наследуются от AbstractButton, поэтому используются его сигналы и обработчики: checked и onChecked, toggled и onToggled, clicked и onClicked.

В приложении требуется реализовать функцию автосохранения, причём её параметры должны показываться, только если эта функция включена. Создайте новый раздел с помощью FormCard и FormHeader, затем добавьте FormSwitchDelegate и FormRadioDelegate.

FormCard.FormHeader {
 title: i18n("Autosave")
}

FormCard.FormCard {
 FormCard.FormSwitchDelegate {
 id: autosave
 text: i18n("Enabled")
 }
 FormCard.FormRadioDelegate {
 text: i18n("After every change")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18n("Every 10 minutes")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18n("Every 30 minutes")
 visible: autosave.checked
 }
}

Видимость каждой радиокнопки привязывается к переключателю, поэтому они показываются только тогда, когда переключатель включён.

Практические рекомендации

Нажмите, чтобы узнать больше

Если есть опыт программирования на императивных языках, таких как C++, может возникнуть соблазн установить свойство checked переключателя, чтобы включить видимость радиокнопок, присвоив true с помощью JavaScript, например:

checked: {
 radio1.visible = true;
 radio2.visible = true;
 radio3.visible = true;
}

Это не очень эффективно для декларативного языка QML, его сигналов и слотов. Вместо выражений JavaScript старайтесь по возможности использовать привязки QML, как в случае visible: autosave.checked.

Подробнее см. на этой странице.

Чтобы проверить флажок, можно добавить новый FormCheckDelegate в раздел «Общие».

FormCard.FormHeader {
 title: i18n("General")
}

FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 FormCard.FormCheckDelegate {
 text: i18n("Show Tray Icon")
 onToggled: {
 if (checkState) {
 console.info("A tray icon appears on your system!")
 } else {
 console.info("The tray icon disappears!")
 }
 }
 }
}

Здесь для показа фиктивного текста, имитирующего появление значка в системном лотке, используется обработчик сигнала onToggled. При желании значок в системном лотке можно легко реализовать с помощью KStatusNotifierItem из KDE или SystemTrayIcon из Qt.

Пока что наше приложение должно выглядеть так:

FormComboBoxDelegate

Обычный компонент ComboBox можно создать с помощью FormComboBoxDelegate.

У этого поля со списком есть несколько полезных свойств, которые можно использовать: editable, displayText и displayMode.

Установка editable: true позволяет редактировать текст поля со списком, что полезно, если нужно добавить новые варианты в поле со списком:

Если нужно показать дополнительный текст перед каждым параметром, можно использовать что-то вроде displayText: "Profile: " + currentText:

А самый интересный из них, который будет использоваться в примере, — displayMode. Он может принимать три значения:

FormComboBoxDelegate.ComboBox: стандартный небольшой раскрывающийся список, показывающий перечень параметров.

FormComboBoxDelegate.Dialog: диалог со списком параметров в середине окна, подобное Kirigami.OverlaySheet.

FormComboBoxDelegate.Page: новая страница, содержащая список параметров, которые показываются в отдельном окне.

Добавьте следующий код между делегатами «Current Color Scheme» и «Show Tray Icon» в карточке формы «General».

FormCard.FormComboBoxDelegate {
 text: i18n("Default Profile")
 description: i18n("The profile to be loaded by default.")
 displayMode: FormCard.FormComboBoxDelegate.ComboBox
 currentIndex: 0
 editable: false
 model: ["Work", "Personal"]
}

С флажком страница параметров должна выглядеть так:

FormDelegateSeparator

Страница параметров приобретает форму, но разделы становятся всё длиннее. Можно добавить несколько экземпляров FormDelegateSeparator, чтобы страница выглядела аккуратнее:

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 id: root

 title: i18nc("@title", "Settings")

 FormCard.FormHeader {
 title: i18nc("@title:group", "General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18nc("@info", "Current Color Scheme")
 description: "Breeze"
 }

 FormCard.FormComboBoxDelegate {
 id: combobox
 text: i18nc("@label:listbox", "Default Profile")
 description: i18nc("@info:whatsthis", "The profile to be loaded by default.")
 displayMode: FormCard.FormComboBoxDelegate.ComboBox
 currentIndex: 0
 editable: false
 model: ["Work", "Personal"]
 }

 FormCard.FormDelegateSeparator {
 above: combobox
 below: checkbox
 }

 FormCard.FormCheckDelegate {
 id: checkbox
 text: i18nc("@option:check", "Show Tray Icon")
 onToggled: {
 if (checkState) {
 console.info("A tray icon appears on your system!")
 } else {
 console.info("The tray icon disappears!")
 }
 }
 }
 }

 FormCard.FormHeader {
 title: i18nc("@title:group", "Autosave")
 }

 FormCard.FormCard {
 FormCard.FormSwitchDelegate {
 id: autosave
 text: i18nc("@option:check", "Enabled")
 }
 FormCard.FormDelegateSeparator {
 above: autosave
 below: firstradio
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 id: firstradio
 text: i18nc("@option:radio", "After every change")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18nc("@option:radio", "Every 10 minutes")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18nc("@option:radio", "Every 30 minutes")
 visible: autosave.checked
 }
 }

 FormCard.FormHeader {
 title: i18nc("@title:group", "Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18nc("@info:whatsthis", "Online Account Settings")
 }
 FormCard.FormTextDelegate {
 id: lastaccount
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18nc("@info:credit", "The Maintainer ™️")
 }
 FormCard.FormDelegateSeparator {
 above: lastaccount
 below: addaccount
 }
 FormCard.FormButtonDelegate {
 id: addaccount
 icon.name: "list-add"
 text: i18nc("@action:button", "Add a new account")
 onClicked: console.info("Clicked!")
 }
 }
}

Как правило, разделители можно использовать везде, где между компонентами имеются существенные различия, хотя место их размещения выбирается самостоятельно. Например, в разделе «Общие» флажок отличается от предыдущих компонентов тем, что не начинается с текста; в разделе «Автосохранение» разделитель объединяет радиокнопки в группу; а в разделе «Учётные записи» добавление разделителя между последней учётной записью и кнопкой придаёт кнопке дополнительный акцент.

Свойства above и below довольно очевидны в применении: передаётся id компонентов выше и ниже разделителя. Если они заданы, разделитель будет немедленно скрываться, как только элемент выше или ниже выделен или на него наведён указатель. Они особенно полезны, например, когда компоненты создаются динамически и нельзя заранее определить, какой элемент окажется непосредственно перед разделителем или после него. Так было бы в разделе «Учётные записи» нашего приложения, если бы логика добавления новых учётных записей была реализована, и тогда можно было бы взять последний элемент модели.

Обратите внимание, что разделитель над параметром значка в системном лотке не показывается при наведении на него указателя.

Docs: Настройка для Windows

Mon, 01 Jan 0001 00:00:00 +0000

Введение

Qt хорошо поддерживает Windows, поэтому приложения, использующие Qt и extra-cmake-modules из KDE, не потребуют множества изменений для корректной работы в Windows.

Требуются три вещи:

Чертёж Craft
Настройка стиля Breeze
Значки в составе приложения

Чертёж Craft требуется, чтобы объединить все зависимости вместе с приложением и создать исполняемый файл.

Директиву препроцессора #ifdef Q_OS_WIN можно использовать для написания кода, который будет применяться только при сборке приложения в Windows. Это необходимо как минимум один раз, чтобы принудительно применить к приложению стиль Breeze и оно хорошо выглядело в Windows, но в зависимости от приложения может потребоваться больше.

Включение в приложение необходимых значков для его работы в Windows — самый сложный этап, но и extra-cmake-modules (ECM) из KDE, и Qt предоставляют средства, упрощающие эту задачу.

Чертёж Craft

Чтобы начать, сначала необходимо выполнить инструкции из раздела Сборка программного обеспечения KDE в Windows с помощью Craft, чтобы получить работоспособную чертёж Craft и хотя бы собрать приложение в Windows.

Как только проект удастся собрать, появятся ошибки компиляции и времени выполнения, которые помогут устранить проблемы совместимости с Windows.

Стиль Breeze

Учебное руководство Kirigami уже должно быть в основном совместимо с Windows, но шаги для этого следует описать явно.

Чтобы обеспечить использование стиля Breeze, нужно внести два изменения: задать для QStyle значение breeze, а для стиля Qt Quick Controls — значение org.kde.desktop.

QStyle управляет большей частью внешнего вида приложения QtWidgets. Это необходимо в приложении QtQuick, поскольку приложение инициализируется с помощью QApplication (традиционно используемого с QtWidgets).

Стиль Qt Quick Controls, напротив, определяет большую часть внешнего вида приложения QtQuick. Это влияет на то, как будут выглядеть элементы управления QML. Стиль KDE org.kde.desktop (также известный как qqc2-desktop-style) особенный: он пытается устранить дублирование, заимствуя элементы оформления из QStyle приложения (поэтому и используется QApplication). Благодаря этому приложения QtWidgets и QtQuick могут в основном выглядеть одинаково и совместно использовать компоненты оформления.

Приложениям QtQuick / Kirigami необходимо задать оба стиля в коде C++. Чтобы задать QStyle, его нужно добавить в двух местах.

В Craft:

def setDependencies(self):
 self.runtimeDependencies["kde/plasma/breeze"] = None

А в C++:

QApplication::setStyle("breeze");

Это то, что используется в учебном руководстве Kirigami. В противном случае можно загружать стиль Breeze только в Windows, где это наиболее актуально, с помощью ifdef:

#ifdef Q_OS_WIN
 QApplication::setStyle("breeze");
#endif

Стиль Qt Quick Controls нужно добавить в трёх местах.

В Craft:

def setDependencies(self):
 self.runtimeDependencies["kde/frameworks/tier3/qqc2-desktop-style"] = None

В C++, где требуется условная компиляция:

if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE"))
{
 QQuickStyle::setStyle("org.kde.desktop");
}

А также, при необходимости, в CMake одним из двух способов:

find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)
# or
ecm_find_qmlmodule(org.kde.desktop REQUIRED)

Так как это зависимость времени выполнения, её не требуется задавать в CMake, который используется на этапе компиляции. Однако это может послужить сигналом — как для себя, так и для других — о том, правильно ли настроено окружение и сможет ли оно запустить полученное приложение, что позволит легче находить отсутствующие пакеты или ошибки в настройке.

Команда find_package() выполняет поиск именно файлов конфигурации CMake для qqc2-desktop-style, тогда как ecm_find_qmlmodule() менее строга и ищет только модуль QML. Для последней требуется подключить ECMFindQmlModule:

include(ECMFindQmlModule)

Поставка значков

Чтобы приложение использовало значки Breeze, сначала нужно включить KIconThemes в проект.

После этого потребуется несколько команд CMake, чтобы включить значок приложения в состав приложения.

KIconThemes

Для этого нужно выполнить следующие три шага:

Добавление его в Craft в качестве зависимости:

def setDependencies(self):
 self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None

Добавление его в качестве зависимости в CMake:

find_package(KF6 REQUIRED COMPONENTS IconThemes)

# ...

target_link_libraries(myapp
 PRIVATE
 # ...
 KF6::IconThemes
)

Использование в коде C++ в файле main.cpp:

#include <KIconTheme>

// …
int main(int argc, char* argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 // …
}

Учтите, что, хотя в названии проекта и в вызове CMake используется множественное число (KIconThemes, KF6IconThemes), в вызове C++ используется единственное число (KIconTheme).

KIconThemes необходимо инициализировать до запуска приложения.

Значок приложения

Если у приложения есть значок, его необходимо добавить в проект и как ресурс QML, и как часть установки значка.

Обычно в Linux значок приложения можно просто установить в нужную папку, и при необходимости приложение само извлечёт значок. Как правило, значок приложения состоит из основного значка SVG и нескольких значков PNG разных размеров.

Установка значка SVG в CMake выполняется так:

install(FILES ${PROJECT_SOURCE_DIR}/icons/org.kde.myapp.svg DESTINATION ${KDE_INSTALL_FULL_ICONDIR}/hicolor/scalable/apps)

А установка значков PNG выполняется так:

ecm_install_icons(ICONS
 16-apps-myapp.png
 24-apps-myapp.png
 32-apps-myapp.png
 48-apps-myapp.png
 64-apps-myapp.png
 128-apps-myapp.png
 256-apps-myapp.png
 512-apps-myapp.png
 DESTINATION share/icons)

При установке значка приложения в Linux PNG-значок, например 48-apps-myapp.png, помещается в ${INSTALL_PREFIX}/share/icons/hicolor/48x48/apps/myapp.png, а SVG-значок — в ${INSTALL_PREFIX}/share/icons/hicolor/scalable/apps/org.kde.myapp.svg, где ${INSTALL_PREFIX} обычно означает /usr, /usr/local или ~/.local. Обратите внимание, как в случае PNG имя значка превращается в путь, который он получит в файловой системе.

Подробнее об установке файлов можно прочитать в разделе Сборка программного обеспечения KDE вручную: шаг установки.

После установки значка таким способом его можно вызвать в коде QML просто как myapp или org.kde.myapp — так же, как при вызове из QIcon::fromTheme(). Это можно использовать с любым элементом управления QML, имеющим свойство icon.name.

В Windows такого стандартной папки нет, поэтому установка значка ничего не даёт: его необходимо включить в состав приложения. Для этого PNG-файл можно поместить в собственную папку установки с помощью ecm_add_app_icon(), а файл PNG или SVG можно встроить в приложение как файл ресурсов Qt в ecm_add_qml_module() или ecm_target_qml_sources().

Значок приложения в формате PNG устанавливается с помощью:

ecm_add_app_icon(myapp ICONS ${PROJECT_SOURCE_DIR}/icons/256-apps-myapp.png)

А основной значок приложения включается в состав как ресурс Qt с помощью:

ecm_add_qml_module(myapp URI org.kde.myapp)
ecm_target_qml_sources(myapp SOURCES Main.qml RESOURCES ../icons/org.kde.myapp.svg)

Благодаря этому значок приложения будет доступен как ресурс Qt по пути qrc:/qt/qml/org/kde/myapp/org.kde.myapp.svg. Это можно использовать с любым элементом управления QML, у которого есть свойство icon.source.

Путь RESOURCES зависит от того, где расположены значки. Традиционно в корне проекта создаётся папка icons/ для хранения всех значков, поскольку они не считаются исходными файлами.

После установки значков (в Linux) и включения их в приложение (в Windows и Android) значок можно задать в коде. В коде QML для совместимости с Windows и Android следует использовать значок, включённый в приложение; в коде C++, в частности при задании значка окна, можно по умолчанию использовать значок из темы значков, а значок, включённый в приложение, — как запасной вариант с помощью QIcon::fromTheme() в вызове QGuiApplication::setWindowIcon():

QGuiApplication::setWindowIcon(QIcon::fromTheme("org.kde.myapp", QIcon(":/qt/qml/org/kde/myapp/org.kde.myapp.svg")));

Значки Kirigami

Хотя в Windows нет стандартной папки для установки значков из темы значков, необходимые значки Breeze можно включить в приложение Windows.

Craft выполняет это автоматически, если для проекта правильно настроен KIconThemes, а значки Breeze включены в проект как зависимость.

Чтобы настроить KIconThemes, см. раздел KIconThemes выше.

Чтобы добавить значки Breeze в качестве зависимости проекта, добавьте в чертёж Craft следующее:

def setDependencies(self):
 # …
 self.runtimeDependencies["kde/frameworks/tier1/breeze-icons"] = None

Таким образом, не потребуется вручную включать значки Breeze в состав приложения как ресурс: достаточно использовать имя QIcon::fromTheme(), например kde или application-exit-symbolic.

Сборка

Чтобы собрать приложение в Windows, необходимо выполнить инструкции из раздела Сборка программного обеспечения KDE в Windows с помощью Craft: сборка собственных проектов в Windows.

Сборки в системе непрерывной интеграции

Если проект правильно настроен для сборки в Windows и использует инфраструктуру KDE для размещения кода (KDE Invent), можно настроить задания CI/CD для Windows.

Для этого потребуется добавить соответствующие шаблоны CI для Windows с помощью файла .gitlab-ci.yaml и перечислить зависимости в файле .kde-ci.yaml, как указано в разделе Система непрерывной интеграции.

Устранение неполадок

Если возникли проблемы с адаптацией приложения к Windows, можно посетить следующие комнаты в Matrix: