Nastavenie s C++

Inštalácia Kirigami

Pred začiatkom budeme musieť nainštalovať Kirigami na náš počítač. Existujú tri spôsoby, ako to urobiť:

• Inštalácia Kirigami z repozitárov vašej distribúcie Linux
• Použitie kde-builder
• Inštalácia Kirigami pomocou Craft

Ak ste na dostatočne aktuálnej distribúcii, ako je Debian Testing, najnovšie non-LTS Ubuntu, Fedora, openSUSE Tumbleweed alebo Arch, môžete nainštalovať Kirigami z vašej distribúcie.

Ak ste na nie dostatočne aktuálnej distribúcii, ako je Debian Stable alebo LTS Ubuntu, mali by ste pre tento tutoriál použiť kde-builder. Mal by zabrať nanajvýš 2 GB úložiska.

Inštalácia Kirigami z repozitárov vo vašej distribúcii Linuxu

Potrebujeme kompilátor C++, vývojové balíky Qt a Kirigami. Otvorte terminál a spustite jeden z nasledujúcich príkazov v závislosti od distribúcie Linux, ktorú používate:

KubuntuKDE 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
ManjaroArch	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-kirigami2-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-qtbase-devel qt6-qtdeclarative-devel qt6-qtquickcontrols2-devel kf6-qqc2-desktop-style

Ďalšie informácie pre ostatné distribúcie nájdete v časti Inštalácia závislostí na zostavenie.

Použitie kde-builder

Nastavte si vývojové prostredie pomocou kde-builder. To vám poskytne potrebné vývojové nástroje a základné knižnice a zostaví KDE Frameworks od nuly.

Vytvorte priečinok ~/kde/src/kirigami-tutorial. Do tohto priečinka umiestnite súbory zdrojového kódu z tohto tutoriálu.

Pridajte nasledujúce na koniec vášho ~/.config/kde-builder.yaml:

project kirigami-tutorial:
  no-src: true

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

Inštalácia Kirigami pomocou Craft

KDE má vlastný nástroj na jednoduchú inštaláciu väčšiny svojich knižníc a programov: Craft. Dá sa použiť na inštaláciu Kirigami na Windows, Android a macOS.

Aj keď je Craft dostupný aj pre Linux a FreeBSD, jeho zamýšľané použitie je iba pre AppImages a balenie.

Budete musieť nasledovať inštrukcie na nastavenie Craft. Na konci nastavenia by ste mali spustiť súbor nastavenia prostredia (craftenv.ps1 vo Windows alebo craftenv.sh na všetkých ostatných platformách), ktorý vám dá terminálový shell, kde budete kompilovať vašu aplikáciu Kirigami.

Potom môžete spustiť nasledovné v termináli:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Toto bude pri prvom spustení chvíľu trvať. Ak zatvoríte terminál, môžete spustiť súbor nastavenia prostredia na opätovnú prípravu terminálu.

Štruktúra projektu

Hoci existujú nástroje, ktoré môžu jednoducho nastaviť naše súbory, vytvoríme ich manuálne. To nám umožní lepšie pochopiť časti, z ktorých sa bude skladať naša nová aplikácia.

Najprv vytvoríme priečinok nášho projektu (môžete použiť nižšie uvedené príkazy). Náš budeme volať kirigami-tutorial/.

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

V tomto priečinku vytvoríme priečinok src/ a CMakeLists.txt. Všeobecne sa považuje za dobrú prax umiestniť všetky naše hlavné súbory kódu C++ do priečinka src/. Tiež do neho umiestnime súbor Main.qml, pretože sa bude spúšťať spolu so spustiteľným súborom.

mkdir -p kirigami-tutorial/src
touch kirigami-tutorial/{CMakeLists.txt,org.kde.tutorial.desktop}
touch kirigami-tutorial/src/{CMakeLists.txt,main.cpp,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

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

Tu budeme spracovávať frontend našej aplikácie.

Ak poznáte trochu Javascript, potom sa vám veľa z QML bude zdať povedomé (aj keď má svoje zvláštnosti). Dokumentácia Qt má rozsiahle množstvo materiálu o tomto jazyku, ak chcete skúsiť niečo na vlastnú päsť. V priebehu týchto tutoriálov sa zameriame veľkú časť pozornosti na náš QML kód, kde môžeme využiť Kirigami na maximum.

Zatiaľ sa zameriame na Main.qml. Najprv importujeme niekoľko dôležitých modulov:

• QtQuick, štandardná knižnica používaná v aplikáciách QML.
• QtQuick Controls, ktorá poskytuje množstvo štandardných ovládacích prvkov, ktoré môžeme použiť na interaktívnosť našich aplikácií.
• QtQuick Layouts, ktorá poskytuje nástroje na umiestňovanie komponentov v rámci okna aplikácie.
• Kirigami, ktorá poskytuje množstvo komponentov vhodných na vytváranie aplikácií fungujúcich na zariadeniach rôznych tvarov a veľkostí.

Potom sa dostávame k nášmu základnému prvku, Kirigami.ApplicationWindow, ktorý poskytuje niektoré základné funkcie potrebné pre všetky aplikácie Kirigami. Toto je okno, ktoré bude obsahovať každú z našich stránok, hlavné sekcie nášho UI.

Potom nastavíme vlastnosť id okna na "root". ID sú užitočné, pretože nám umožňujú jednoznačne odkazovať na komponent, aj keď máme niekoľko rovnakého typu.

Nastavíme tiež vlastnosť title okna na "Hello World". Všimnete si, že sme obalili náš reťazec "Hello World" do funkcie i18nc(), kde uvedieme kontext reťazca aj samotný reťazec.

Potom nastavíme prvú stránku nášho zásobníka stránok. Väčšina aplikácií Kirigami je organizovaná ako zásobník stránok, pričom každá stránka obsahuje súvisiace komponenty vhodné pre konkrétnu úlohu. Zatiaľ to udržujeme jednoduché a zostávame pri jednej stránke. pageStack je pôvodne prázdny zásobník stránok poskytovaný Kirigami.ApplicationWindow a pomocou pageStack.initialPage: Kirigami.Page {...} nastavíme prvú stránku prezentovanú pri načítaní aplikácie na Kirigami.Page. Táto stránka bude obsahovať všetok náš obsah.

Nakoniec zahrnieme na našu stránku Controls.Label, ktorý nám umožní umiestniť text na stránku. Používame anchors.centerIn: parent na vycentrovanie nášho popisku horizontálne a vertikálne v rámci rodičovského prvku. V tomto prípade je rodičovským komponentom nášho popisku Kirigami.Page. Posledná vec, ktorú musíme urobiť, je nastaviť jeho text: text: i18n("Hello World!").

org.kde.tutorial.desktop

Primárnym účelom súborov Desktop Entry je zobraziť vašu aplikáciu v spúšťači aplikácií v Linuxe. Ďalším dôvodom mať ich je mať ikony okien na Waylande, pretože sú potrebné na to, aby povedali kompozitoru "toto okno patrí k tejto ikone".

Musí nasledovať schému pomenovania s obráteným DNS s príponou .desktop, ako napríklad 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

[Desktop Entry]
Name=Kirigami Tutorial
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[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

CMakeLists

Súbory CMakeLists.txt sú potrebné na použitie zostavovacieho systému KDE podľa výberu, CMake. Náš súbor kirigami-tutorial/CMakeLists.txt bude špecifikovať niektoré vlastnosti našej aplikácie. Tiež zahŕňa niektoré závislosti, ktoré potrebujeme na kompiláciu nášho projektu.

 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 definuje, ako sa zostavujú vaše projekty. Väčšina obsahu tu je len na spustenie vášho projektu. Podrobné vysvetlenie riadok po riadku, čo tento súbor CMakeLists robí, si môžete prečítať tu.

Najdôležitejšia vec, ktorú si treba zapamätať, je, že zostavovacie závislosti C++ Qt a KDE Frameworks sú spravované pomocou find_package() a QML závislosti v čase behu sú spravované pomocou ecm_find_qml_module(). Budete musieť upraviť tieto riadky a zahrnúť akékoľvek ďalšie komponenty, ktoré sa rozhodnete použiť počas vývoja vašej aplikácie.

Riadok s add_subdirectory(src) nasmeruje CMake do adresára kirigami-tutorial/src/, kde sa nachádza náš zdrojový kód.

Riadok s install() hovorí CMake, kam nainštalovať súbor desktop.

Poďme sa ponoriť do súboru 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})

Tento súbor pozostáva z piatich krokov:

1. vytvorenie spustiteľného súboru
2. premeniť spustiteľný súbor na modul QML, ktorý prijíma súbory QML
3. pridanie súborov C++ a QML do spustiteľného súboru
4. prepojenie knižníc potrebných na spustenie
5. inštalácia spustiteľného súboru na správne miesto

Nabudúce, keď budete potrebovať pridať ďalšie QML súbory, pridajte ich do existujúceho volania ecm_target_qml_sources(). Súbory C++, ktoré používajú kľúčové slovo QML_ELEMENT, ktoré uvidíme neskôr v tutoriáli, sa dajú pridať pomocou target_sources().

Teraz, keď sme sa postarali o CMake, pozrime sa na súbory, s ktorými budeme tráviť väčšinu nášho času.

main.cpp

Súbor kirigami-tutorial/src/main.cpp spracováva "biznis logiku" našej aplikácie. C++ je praktické, pretože je flexibilné a rýchle, aj keď je náročnejšie ako iné programovacie jazyky.

Tiež slúži ako vstupný bod do našej aplikácie. Obe časti nášho projektu, backend a používateľské rozhranie, sú tu nastavené a spustené.

 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();
}

Zatiaľ nemusíme zachádzať do prílišných detailov ohľadom toho, čo robí náš kód main.cpp, ale jeho úloha sa výrazne zvýši, keď sa rozhodneme pridať zložitejšiu funkčnosť do našej aplikácie v budúcnosti.

Ak sa chcete dostať dopredu, môžete si prečítať viac o tom, ako tento main.cpp funguje, v časti Pochopenie main.cpp.

Ak chcete vidieť niekoľko spôsobov, ako sa dá kód C++ vylepšiť, napríklad použitím KAboutData pre preložiteľné metadáta aplikácie, určite si pozrite náš tutoriál KXmlGui.

Zatiaľ nás zaujíma tento riadok:

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

Prvý argument je URI nastavené v kirigami-tutorial/src/CMakeLists.txt a druhý argument je názov QML modulu, ktorý chceme použiť (Main, pochádzajúci z názvu nášho súboru Main.qml, ktorý musí začínať veľkým písmenom).

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

Zostavenie a inštalácia aplikácie

Sme takmer na cieľovej čiare. Posledná vec, ktorú musíme urobiť, je zostaviť a spustiť našu aplikáciu. Postup bude závisieť od toho, na akej platforme sa nachádzate.

Linux alebo FreeBSD

Zostavenie pomocou kde-builder

Uistite sa, že ste nasledovali pokyny v časti Použitie kde-builder.

Skompilujte potrebné zostavovacie závislosti pomocou kde-builder, potom skompilujte kirigami-tutorial spustením nasledujúcich príkazov v termináli:

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

Manuálne zostavenie

Zmeňte adresár na koreňový priečinok projektu, potom spustite nasledujúci príkaz v termináli:

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

Program bude nainštalovaný do ~/.local/bin a jeho súbor desktop do ~/.local/share/applications.

Okná

Ak kompilujete svoj projekt v systéme Windows po nastavení Craft, CMake by mal automaticky detekovať správny kompilátor:

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

V závislosti od toho, ako ste nainštalovali kompilátor, možno budete musieť špecifikovať generátor CMake pre prvý krok, v závislosti od toho, či používate Visual Studio (msvc) alebo MinGW (make) na kompiláciu vašich projektov.

Ak Visual Studio, v závislosti od kompilátora, ktorý ste sa rozhodli nainštalovať, môže to byť:

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

Alebo:

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

Ak MinGW:

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

V oboch prípadoch bude program nainštalovaný do C:\CraftRoot\bin.

Ak ste niekedy na pochybách ohľadom názvu kompilátora, ktorý by sa mal použiť vo volaní cmake, spustite:

cmake -G

Zobrazí zoznam všetkých dostupných generátorov.

Spustenie aplikácie

Potom môžete spustiť program kirigami-hello pomocou:

kirigami-hello # Na Linuxe, manuálne
kde-builder --run kirigami-hello # S kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # S kdesrc-build
kirigami-hello.exe # Na Windows

Voilà! Teraz uvidíte vašu úplne prvú aplikáciu Kirigami priamo pred vašimi očami.

Na spustenie novej QML aplikácie v mobilnom režime môžete použiť QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Ak ste skompilovali projekt manuálne pomocou CMake a z nejakého dôvodu by ste chceli projekt odinštalovať, môžete spustiť:

cmake --build build/ --target uninstall