Вступ до додатків Kirigami

Знайомимося із компонентами додатків Kirigami

Додатки Kirigami — це додатковий набір візуальних компонентів, які добре працюють на мобільних пристроях і комп'ютерах і гарантовано є багатоплатформовими. З лаштунками вони використовують Kirigami для створення своїх компонентів.

Тут ви налаштуєте свій новий проєкт додатків Kirigami і познайомитеся з кількома корисними компонентами.

Ці компоненти використовують засоби локалізації KDE, тому перед тим, як ми почнемо ними користуватися, нам потрібно буде налаштувати невеликий проєкт, який використовує KLocalizedContext .

Налаштовування вашого проекту

Початкова структура проєкту має бути такою:

addonsexample/
├── CMakeLists.txt
├── main.cpp
├── resources.qrc
└── contents/
    └── ui/
        └── 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)

find_package(Qt${QT_MAJOR_VERSION} REQUIRED COMPONENTS
    Widgets        # For QApplication
    Quick          # For QML
    QuickControls2 # For QQuickStyle
)
find_package(KF${QT_MAJOR_VERSION} REQUIRED COMPONENTS
    CoreAddons # For KAboutData
    I18n       # For KLocalizedContext
)

add_executable(addonsexample)

target_sources(addonsexample PRIVATE main.cpp resources.qrc)

target_link_libraries(addonsexample PRIVATE
    Qt::Widgets
    Qt::Quick
    Qt::QuickControls2
    KF${QT_MAJOR_VERSION}::CoreAddons
    KF${QT_MAJOR_VERSION}::I18n
)

install(TARGETS addonsexample DESTINATION ${KDE_INSTALL_BINDIR})

Стандартний resources.qrc:

<!DOCTYPE RCC>
<RCC version="1.0">
<qresource prefix="/">
    <file alias="main.qml">contents/ui/main.qml</file>
</qresource>
</RCC>

Цікавою частиною буде 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"),
        i18n("Addons Example"),
        QStringLiteral("1.0"),
        i18n("This program shows how to use Kirigami Addons"),
        KAboutLicense::GPL_V3,
        QStringLiteral("(C) 2023"),
        i18n("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")));

    qmlRegisterSingletonType(
        "org.kde.about",
        1, 0, "About",
        [](QQmlEngine *engine, QJSEngine *) -> QJSValue {
            return engine->toScriptValue(KAboutData::applicationData());
        }
    );

    QQmlApplicationEngine engine;
    engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
    engine.load(QStringLiteral("qrc:/main.qml"));
    app.exec();
}

Якщо ви вже прочитали наш підручник з KXmlGui або останній підручник з Kirigami на сторінці про Kirigami, ви вже знайомі зі значною частиною цього розділу.

Ми створюємо нашу програму та використовуємо типовий конструктор KAboutData , щоб додати метадані нашої програми, додаємо себе як автора, а потім використовуємо setApplicationData() , щоб завершити процес. Надалі ми також встановлюємо піктограму програми, яка походить із загальносистемної теми.

Далі ми використаємо лямбду у qmlRegisterSingletonType для безпосереднього надсилання метаданих вашої програми на бік QML, відкриваючи її властивості.

Потім ми створюємо екземпляр нашого рушія QML і встановлюємо його контекст на використання KLocalizedContext KDE, який використовується для інтеграції перекладених рядків, передаючи щойно створений рушій як параметр.

Ми просто завантажуємо наш файл QML із файла ресурсів, і тепер нам потрібно лише подбати про наш початковий файл QML.

FormCard і FormButtonDelegate

Ідея нашого додатка полягає в тому, щоб розробити власну галерею додатків Kirigami, демонструючи кілька компонентів, по одному на сторінку. Головна сторінка міститиме простий список кнопок у ColumnLayout, кожна з яких відкриватиме окрему сторінку.

Спочатку, наш contents/ui/main.qml має виглядати так:

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

import QtQuick 2.15
import QtQuick.Layouts 1.15

import org.kde.kirigami 2.15 as Kirigami
import org.kde.kirigamiaddons.formcard 1.0 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.

Основне призначення FormCard — слугувати контейнером для інших компонентів, використовуючи колір, відмінний від фону, подібно до Kirigami.Card , але для вікон налаштувань. Ви можете мати кілька FormCards у своїй програмі для позначення різних розділів. Очікується, що ваша FormCard буде прямою дочірньою формою ColumnLayout.

Імпортування org.kde.kirigamiaddons.formcard робить доступними для вашого файла QML усі компоненти FormCard.

У нас буде лише один розділ на нашій головній сторінці, тому ми додамо одну FormCard:

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

import QtQuick 2.15
import QtQuick.Layouts 1.15

import org.kde.kirigami 2.15 as Kirigami
import org.kde.kirigamiaddons.formcard 1.0 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 — не потрібно ніяких прикріплених властивостей компонування, і немає потреби у використанні прив'язок або [позиціонерів](https://doc.qt.io /qt-6/qtquick-positioning-layouts.html).

Ми можемо просто додати декілька кнопок всередину нашого 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 2.15
import QtQuick.Layouts 1.15

import org.kde.kirigami 2.15 as Kirigami
import org.kde.kirigamiaddons.formcard 1.0 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.

Previous
Сторінка «Про програму»
Next
Сторінки «Про програму» FormCard