Úvod do Kirigami Addons

Kirigami Addons je dodatočná sada vizuálnych komponentov, ktoré dobre fungujú na mobiloch aj desktopoch a je zaručená ich multiplatformovosť. Na vytváranie svojich komponentov používa Kirigami pod kapotou.

Tu nastavíte váš nový projekt Kirigami Addons a budete oboznámení s niekoľkými užitočnými komponentmi.

Tieto komponenty využívajú lokalizačné nástroje KDE, takže predtým, než ich začneme používať, budeme musieť nastaviť malý projekt, ktorý využíva KLocalizedContext.

Nastavenie vášho projektu

Počiatočná štruktúra projektu bude vyzerať takto:

addonsexample/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

mkdir -p addonsexample/contents/ui
touch addonsexample/{CMakeLists.txt,main.cpp}
touch addonsexample/Main.qml

Začneme použitím veľmi štandardného 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})

Zaujímavá časť bude 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();
}

Ak ste si prečítali náš tutoriál KXmlGui alebo posledný tutoriál Kirigami o stránke O programe Kirigami, veľa z toho sa vám bude zdať známe.

Vytvoríme našu aplikáciu a použijeme predvolený konštruktor KAboutData na pridanie metadát našej aplikácie, pridáme sa ako autor a potom použijeme setApplicationData() na dokončenie procesu. Pre neskoršie použitie tiež nastavíme ikonu aplikácie, ktorá pochádza zo systémovej témy.

Potom použijeme lambda výraz v qmlRegisterSingletonType() na priame odoslanie metadát našej aplikácie na stranu QML, čím sprístupníme jej vlastnosti.

Potom vytvoríme inštanciu nášho QML enginu a nastavíme jeho kontext na používanie KLocalizedContext od KDE, ktorý slúži na integráciu preložených reťazcov, pričom ako parameter odovzdáme práve vytvorený engine.

Jednoducho načítame náš súbor QML zo súboru zdrojov a teraz sa stačí postarať o náš počiatočný súbor QML.

FormCard a FormButtonDelegate

Nápad pre našu aplikáciu je navrhnúť vlastnú galériu Kirigami Addons, ktorá ukáže viaceré komponenty, jeden na stránku. Hlavná stránka bude obsahovať jednoduchý zoznam tlačidiel v ColumnLayout, pričom každé otvorí samostatnú stránku.

Náš Main.qml by mal pôvodne vyzerať takto:

 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
        }
    }
}

Používame náš praktický pageStack na nastavenie úvodnej stránky na Kirigami.ScrollablePage.

Hoci by sme mohli použiť FormLayout spolu s komponentmi QtQuick Controls na dosiahnutie nášho cieľa, tu vám predstavíme FormCard.

Hlavným účelom FormCard je slúžiť ako kontajner pre iné komponenty s farbou odlišnou od pozadia, podobným spôsobom ako Kirigami.Card, ale pre okná nastavení. V aplikácii môžete mať viacero FormCard na označenie rôznych sekcií. Váš FormCard by mal byť tiež priamym potomkom ColumnLayout.

Import org.kde.kirigamiaddons.formcard sprístupní všetky komponenty FormCard vo vašom súbore QML.

Na našej hlavnej stránke budeme mať iba jednu sekciu, takže pridáme jeden 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
            }
        }
    }
}

Skvelou vecou na FormCard je, že za vás vykonáva automatické rozloženie. Inými slovami, stačí poradie jeho komponentov na určenie ich pozície vo vnútri FormCard, žiadne pripojené vlastnosti Layout nie sú potrebné a neočakáva sa, že budete používať anchors alebo positioners.

Do nášho FormCard môžeme jednoducho pridať niekoľko tlačidiel:

 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")
                }
            }
        }
    }
}

To je všetko! Tlačidlá ešte nie sú použiteľné, ale teraz sme pripravení experimentovať s našimi stránkami O aplikácii!

Potom to zostavíme a spustíme takto:

cmake -B build/ -DCMAKE_INSTALL_PREFIX=~/kde5/usr
cmake --build build/
cmake --install build/
aboutexample

Ak chcete vidieť iné spôsoby zostavenia vašej aplikácie (napríklad na Windows), pozrite si stránku Začíname s Kirigami.