Opzetten en aan de slag gaan

Gereed zijn om onze eerste Kirigami toepassing te maken

Kirigami installeren

Alvorens te beginnen moeten we Kirigami op onze machine installeren. Er zijn drie manieren om dat te doen:

Kirigami installeren uit de opslagruimte in uw Linux distributie
Kirigami bouwen met kde-builder
Kirigami installeren met Craft

Kirigami installeren uit de opslagruimte in uw Linux distributie

We hebben een C++ compiler, Qt ontwikkelpakketten en Kirigami nodig. Open een terminaltoepassing en voer een van de volgende, afhankelijk van welke Linux distributie u gebruikt:

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 groupinstall "Development Tools" "Development Libraries"
sudo dnf install 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

Verdere informatie voor andere distributies is hier te vinden.

Kirigami bouwen met kde-builder

KDE heeft een eigen hulpmiddel om gemakkelijk al zijn bibliotheken en programma's te bouwen: kde-builder. Het kan gebruikt worden om Kirigami op Linux en FreeBSD te bouwen.

Voor deze inleiding moet u de opzetinstructies voor kde-builder volgen.

Daarna kunt u eenvoudig het volgende in een terminal uitvoeren:

kde-builder kirigami kcoreaddons ki18n breeze plasma-integration kiconthemes qqc2-desktop-style

Kirigami installeren met Craft

KDE heeft een eigen hulpmiddel om gemakkelijk de meeste van zijn bibliotheken en programma's te installeren: Craft. Het kan gebruikt worden om Kirigami te installeren op Linux, FreeBSD, Windows, Android en macOS.

U moet de opzetinstructies voor Craft volgen. Aan het einde van de opzet zou u een opzetbestand voor de omgeving (craftenv.ps1 of craftenv.sh) moeten uitvoeren, die u een terminal-shell geeft waar u uw Kirigami toepassing kunt compileren.

Daarna kunt u eenvoudig het volgende in een terminal uitvoeren:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Als u uw terminal sluit kunt u eenvoudig het opzetbestand voor de omgeving opnieuw binnenhalen om uw toepassing te compileren.

Projectstructuur

Terwijl er hulpmiddelen zijn die gemakkelijk onze bestanden in kunnen stellen, gaan we ze handmatig aanmaken. Hiermee begrijpen we de onderdelen beter waaruit onze nieuwe toepassing gaat bestaan.

Eerst maken we onze projectmap aan (u kunt de onderstaande commando's gebruiken). De onze gaan we kirigami-tutorial/ noemen.

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

In deze map gaan we een map src/ en CMakeLists.txt aanmaken. Het wordt in het algemeen als een goede praktijk beschouwd om al onze bestanden met hoofd C++-code in een map src/ te plaatsen. We zetten ook het bestand Main.qml erin omdat het tegelijk met het uitvoerbare bestand zal draaien.

Tip

U kunt deze bestandsstructuur snel aanmaken met:

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

Notitie

In het geval dat u automatisch het project met kde-builder wilt bouwen, dan moet de naam van de eigen module hetzelfde zijn als de basismap van het project (in ons geval zal dit zijn "kirigami-tutorial"), anders moet u de source-dir of dest-dir voor de module aanpassen. We nemen aan dat het pad naar uw hoofd main.cpp zal zijn $HOME/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!")
        }
    }
}

Hier gaan we onze frontend van de toepassing behandelen.

Als u enige Javascript kent, dan zal veel van QML u bekend voorkomen (hoewel het zijn eigen eigenaardigheden heeft). Qt's documentation heeft een uitgebreide hoeveelheid materiaal over deze taal als u zelf iets wilt proberen. Gedurende de loop van deze inleidingen zullen we veel van onze aandacht focussen op onze QML code, waar we Kirigami kunnen gebruiken om er het meeste uit te krijgen.

Laten we ons voor nu focussen op Main.qml. Eerst importeren we een aantal belangrijke modulen:

QtQuick, de standaard bibliotheek gebruikt in QML toepassingen.
QtQuick Controls, die een aantal standaard besturingen levert die we kunnen gebruiken om onze toepassingen interactief te maken.
QtQuick Layouts, die hulpmiddelen voor het plaatsen van componenten in de toepassingsvensters levert.
Kirigami, die een aantal componenten levert geschikt voor het aanmaken van toepassingen die werken over apparaten met verschillende vormen en groottes.

Notitie

De QtQuick Controls en Kirigami imports in aparte naamruimten stoppen met het gebruik van sleutelwoord as is een beste praktijk die verzekert dat er geen componenten zijn met dezelfde naam die in conflict kunnen zijn. U zou verschillende namen voor QtQuick Controls in het wild kunnen zien, zoals "QQC" of "QQC2". We zullen "Controls" in deze handleiding gebruiken voor alle helderheid.

Daarna komen we bij ons basiselement, Kirigami.ApplicationWindow die enige basis functies levert nodig voor alle Kirigami toepassen. Dit is het venster dat elk van onze pagina's bevat, de hoofdsecties van onze UI.

Daarna zetten we de eigenschap id van het venster op 'root'. ID's zijn nuttig omdat ze ons uniek verwijzen naar een component, zelfs als we er verschillende hebben van hetzelfde type.

We stellen ook de eigenschap title van het venster in op "Hello World". U zult hebben opgemerkt dat we onze tekenreeks "Hello World" hebben ingepakt in een functie genaamd i18nc, waar we de context van de tekenreeks, evenals de tekenreeks zelf, detailleren.

Notitie

i18n() functies maken uw toepassing gemakkelijker te vertalen, omdat ze een versie van de geleverde tekenreeks leveren in de taal van de gebruiker (voor zover uw toepassing gelokaliseerd is voor die taal). Terwijl een Engelse gebruiker onze venstertitel als "Hello World" zal zien, zou een Nederlandse gebruiker "Hallo wereld" te zien krijgen.

i18nc() bouwt verder op de functie i18n() door ontwikkelaars, die aan de toepassing werken. Hiermee leggen we uit dat de UI-component de titel is van het toepassingsvenster, we hebben dus de tekenreeks "@title:window" voor "Hello World" ingevoegd. Zie de Ki18n Programmer's guide voor meer details.

Daarna zetten we de eerste pagina van onze pagina stapel. De meeste Kirigami toepassingen zijn georganiseerd als een stapel pagina's, elke pagina bevat gerelateerde componenten passend bij een specifieke taak. Voor nu houden we het eenvoudig en blijven bij een enkele pagina. pageStack is een initieel lege stapel pagina's geleverd door Kirigami.ApplicationWindow en met pageStack.initialPage: Kirigami.Page {...} zetten we de eerste pagina op gepresenteerd bij het laden van de toepassing op een Kirigami.Page. Deze pagina zal al onze inhoud zal bevatten.

Tenslotte voegen we in onze pagina een Controls.Label in die ons tekst laat plaatsen op onze pagina. We gebruiken anchors.centerIn: parent om ons label horizontaal en verticaal te centreren in ons ouderelement. In dit geval is de oudercomponent van Kirigami.Page. Het laatste ding dat we moeten doen is het zetten van zijn tekst: text: i18n("Hello World!").

org.kde.tutorial.desktop

Het hoofddoel van Desktop Entry bestanden is te zorgen dat uw programma in de toepassingenstarter van Linux verschijnt. Een andere reden om ze te hebben is om bij Wayland venster-pictogrammen te hebben, omdat ze nodig zijn om de compositor te vertellen "dit venster hoort bij dit icon".

Het moet een reverse-DNS naam-schema volgen gevolgd door de .desktop extensie zoals org.kde.tutorial.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
[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[sl]=Učbenik Kirigami
Name[sv]=Kirigami-handledning
Name[tr]=Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami
Name[x-test]=xxKirigami Tutorialxx
Name[zh_TW]=Kirigami 教學
Exec=kirigami-hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

Notitie

Venster- en werkbalkpictogrammen zullen in een Wayland sessie alleen werken als bureaublad bestanden van toepassingen geplaatst zijn in ~/.local/share/applications of /usr/share/applications. Om pictogrammen in deze handleiding werkend te krijgen, ofwel kopieer het desktop-bestand van de toepassing daar of schakel om naar een ontwikkelsessie zoals geïnstrueerd in inleiding van kde-builder. Sommige KDE toepassingen zouden werkende pictogrammen kunnen hebben als ze al zijn geïnstalleerd in het systeem.

CMakeLists.txt

CMakeLists.txt bestanden zijn nodig om het door KDE gekozen bouwsysteem te gebruiken, CMake. Ons bestand kirigami-tutorial/CMakeLists.txt gaat enige van de karakteristieken van uw toepassing specificeren. Het bevat ook enige van de afhankelijkheden die we nodig hebben om ons project te compileren.

 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)

De CMakeLists.txt definieert onze te bouwen projecten. Het meeste van de inhoud hier is slechts om uw project af te trappen. U kunt een regel-bij-regel, uitgebreide uitleg over wat dit bestand CMakeLists doet hier lezen.

Het belangrijkste om te onthouden is dat de C++-bouwafhankelijkhedenn Qt en KDE Frameworks beheerd worden met find_package()an QML runtime afhankelijkheden worden beheerd met ecm_find_qml_module(). U zult deze regels moeten wijzigen en extra componenten toevoegen die u beslist om te gebruiken tijdens de ontwikkeling van uw toepassing.

De regel met add_subdirectory(src), laat CMake wijzen naar de map kirigami-tutorial/src/, waar uw broncode is gelokaliseerd.

De regel met install() geeft aan CMake door waar het desktop-bestand geïnstalleerd moet worden.

Laten we dieper in het bestand kirigami-tutorial/src/CMakeLists.txt duiken.

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

Dit bestand bestaat uit vijf stappen:

Creëer een uitvoerbaar bestand
Wijzig het uitvoerbare bestand in een QML module dat QML-bestanden accepteert
voeg C++ en QML-bestanden toe aan het uitvoerbare bestand
koppel de bibliotheken die noodzakelijk zijn voor het uitvoerbare bestand om te kunnen werken
Installeer het uitvoerbare bestand op de juiste plaats

De volgende keer dat u meer QML-bestanden moet toevoegen, voeg ze toe aan de al aanwezige aanroepecm_target_qml_sources(). C++ bestanden die het de aanroep QML_ELEMENT gebruiken die we later in de instructie zullen behandelen kunnen door target_sources() te gebruiken worden toegevoegd.

Nu we met CMake klaar zijn, laten we kijken naar de bestanden waarmee we de meeste tijd aan gaan werken.

main.cpp

Het bestand kirigami-tutorial/src/main.cpp behandelt de "zakelijke logica" van onze toepassing. C++ is handig omdat het flexibel en snel is, zelfs als het moeilijker is dan andere programmeertalen.

Het functioneert ook als de ingang naar onze toepassing. De twee delen van ons project, de backend en het gebruikersinterface, worden beiden hier opgezet en gestart.

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

Op dit moment hoeven we niet in teveel detail te gaan met betrekking tot wat onze code in main.cpp doet, maar zijn rol zal aanzienlijk belangrijker worden nadat we besluiten complexere functionaliteit in de toekomst aan onze toepassing toe te voegen.

Thema's toekennen op Windows

Klik hier om meer te lezen

Als wat vooruit wilt lopen dan kunt u meer te lezen over hoe deze main.cpp werkt in Begrip van main.cpp

Als u een paar manieren wilt bestuderen over hoe C++ code verbetert kan worden, zoals het gebruik van KAboutData voor vertaalbare metadata van het programma, ga dan naar onze KXmlGui-instructie.

Op dit moment interesseert ons deze regel:

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

Het eerste argument is de ingestelde URI in kirigami-tutorial/src/CMakeLists.txt, en het tweede argument is de naam van de QML module die we willen gaan gebruiken (Main, komend van de naam van ons Main.qml-bestand, wat moet beginnen met een hoofdletter).

De oude methode

U kan deze alternatieve methode om QML-bestanden te laden tegen komen in echte code!

De oude methode voor het laden van QML-bestanden had enkele nadelen en na Qt6 werd het wel erg spraakzaam:

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

Dit Qt resource URI hierboven volgt het patroon <resource_prefix><import_URI><optional_QML_dir><file>. In dit geval:

resource prefix = default / in Qt5, /qt/qml in Qt6
importeer URI = /org/kde/tutorial, wat overeenkomt met de URI org.kde.tutorial
optioneel QML dir = /qml, noodzakelijk als de QML-bestanden worden opgeslagen in een map met de naam qml/
bestand = het QML-bestand

De toepassing compileren en installeren

We zijn bijna bij de eindstreep. Het laatste wat we moeten doen is bouwen en onze toepassing uitvoeren. Om dat te doen hangt af van op welke platform u bent.

Linux of FreeBSD

Als u wilt dat kde-builder het bouwen en installeren van uw project afhandelt, dan moet u:

de projectmap naar ~/kde/src, dat is, ~/kde/src/kirigami-tutorial
specificeer een aangepaste module aan het eind van uw ~/.config/kde-builder.yaml:

project kirigami-tutorial:
  no-src: true

⏳ Met kdesrc-build...

Klik hier om meer te weten hoe dt is gedaan met kdesrc-build

Deze stap werd gedaan door in plaats daarvan te schrijven naar ~/.config/kdesrc-buildrc met een andere syntaxis:

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

Daarna kan u bouwen en installeren met het commando:

kde-builder kirigami-tutorial

In geval u het bouwen en installeren handmatig wilt doen zonder kde-builder, dan hebt u de plaats nodig waar het programma geïnstalleerd zal worden. Om dat te doen moeten we de mappen naar onze map kirigami-tutorial/ in onze gekozen terminaltoepassing wijzigen en de volgende commando's uitvoeren:

cmake -B build/
cmake --build build/
cmake --install build/ --prefix "$HOME/.local"

Het programma zal geïnstalleerd worden in $HOME/.local/bin en zijn desktop-item in $HOME/.local/share/applications.

Windows

Als u uw project op Windows compileert nadat Craft in opgezet, zou CMake automatisch de juiste compiler detecteren:

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

Als u uw project met Craft compileert onder Windows, hebt u misschien een CMake-generator nodig voor de eerste stap, afhankelijk van of u Visual Studio (msvc) of MinGW (make) gebruikt om uw projecten te compileren.

Bij Visual Studio, afhankelijk van de gekozen compiler die is geïnstalleerd, kan het zijn:

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

Of:

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

En bij MinGW:

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

In beide gevallen zal het programma geïnstalleerd worden in C:\CraftRoot\bin.

Als u twijfels heeft over de naam van de compiler die in cmake aangeroepen moet worden, voer dan het volgende uit:

cmake -G

Dit zal een lijst met alle beschikbare generators tonen.

De toepassing uitvoeren

U kunt daarna het programma kirigami-tutorial uitvoeren met:

kirigami-hello # Op Linux, handmatig
kde-builder --run kirigami-hello # OP Linux, met kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # Op Linux, met kdesrc-build
kirigami-hello.exe # Op Windows

Voilà! Nu ziet u uw allereerste Kirigami toepassing voor uw eigen ogen verschijnen.

Schermafdruk van de gegenereerde Kirigami toepassing

Om het nieuwe QML-programma in de modus mobiel op te starten, kan u QT_QUICK_CONTROLS_MOBILE=1 gebruiken:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Als u voor een reden het project handmatig met CMake heeft gecompileerd en voor de een of andere reden het project wilt dëinstalleren, dan kan u het volgende uitvoeren:

cmake --build build/ --target uninstall

Notitie

De volgende keer dat u de benodigde bestanden en mappen aanmaakt, kunt u KAppTemplate of KDevelop gebruiken om automatisch een geschikt project te beginnen. Ze zijn beschikbaar vanuit elke belangrijke opslagruimte van distributies. Deze toepassingen zullen ook bestanden genereren met metagegevens AppStream en een bestand .desktop die informatie over hoe de toepassing getoond zou moeten worden in een toepassingenstarter van linux.

Dankzij de magie van CMakeLists kunt u ook IDE's zoals KDevelop of QtCreator gebruiken om deze toepassing in een comfortabele omgeving met minimale inspanning te ontwikkelen.

Pagina's uitleggen