Введение в Kirigami Addons

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.