Opzetten en aan de slag gaan

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 kdesrc-build
• 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:

KubuntuKDE Neon	sudo apt install build-essential cmake extra-cmake-modules qtbase5-dev qtdeclarative5-dev qtquickcontrols2-5-dev kirigami2-dev libkf5i18n-dev gettext libkf5coreaddons-dev qml-module-org-kde-qqc2desktopstyle
ManjaroArch	sudo pacman -S base-devel extra-cmake-modules cmake qt5-base qt5-declarative qt5-quickcontrols2 kirigami2 ki18n kcoreaddons breeze qqc2-desktop-style
OpenSUSE	sudo zypper install --type pattern devel_C_C++ sudo zypper install cmake extra-cmake-modules libQt5Core-devel libqt5-qtdeclarative-devel libQt5QuickControls2-devel kirigami2-devel ki18n-devel kcoreaddons-devel qqc2-desktop-style
Fedora	sudo dnf groupinstall "Development Tools" "Development Libraries" sudo dnf install cmake extra-cmake-modules qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtquickcontrols2-devel kf5-kirigami2-devel kf5-ki18n-devel kf5-kcoreaddons-devel qqc2-desktop-style

Verdere informatie voor andere distributies is hier te vinden.

Als u Kirigami wilt bouwen met Qt6 dan is dat nu niet mogelijk met alleen distributiepakketten op Linux. U moet in plaats daarvan uw toevlucht nemen tot kdesrc-build.

Kirigami bouwen met kdesrc-build

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

Voor deze inleiding moet u de opzetinstructies voor kdesrc-build volgen maar een map ~/.kde5 in plaats daarvan gebruiken, daarna het voorbeeld KF5-bestand naar uw thuismap kopiëren:

cp ~/kde5/src/kdesrc-build/kdesrc-buildrc-kf5-sample ~/.config/kdesrc-buildrc

Daarna kunt u eenvoudig het volgende in een terminal uitvoeren:

kdesrc-build kirigami kcoreaddons ki18n breeze plasma-integration qqc2-desktop-style
source ~/kde5/build/kirigami/prefix.sh

En daarna kunt u uw Kirigami-projecten in dezelfde terminal-shell compileren die u gebruikte om het prefix-bestand met source binnen te halen. Als u uw terminal sluit kunt u eenvoudig het bestand opnieuw binnenhalen om uw toepassing te compileren.

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. De onze gaat "helloworld" heten.

helloworld/
├── CMakeLists.txt
└── src/
    ├── CMakeLists.txt
    ├── main.cpp
    ├── resources.qrc
    └── contents/
        └── ui/
            └── main.qml

In deze map gaan we een src/ map en CMakeLists.txt aanmaken. Het wordt in het algemeen als een goede praktijk beschouwd om al onze bestanden met hoofdcode in een map src/ te plaatsen. Onze map src/ zal op zijn beurt een map genaamd contents/ bevatten, die zelf een map genaamd ui/ bevat. Dit is waar we onze QML-bestanden aanmaken.

mkdir -p helloworld/src/contents/ui
touch helloworld/CMakeLists.txt
touch helloworld/src/{CMakeLists.txt,main.cpp,resources.qrc}
touch helloworld/src/contents/ui/main.qml

Dit is een KDE-conventie, maar niet alle KDE projecten gebruiken deze structuur. U bent vrij om dingen anders op te zetten, maar u zult hiermee rekening moeten houden bij aanmaken van uw bestanden CMakeLists.txt en resources.qrc.

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

// Includes relevant modules used by the QML
import QtQuick 2.15
import QtQuick.Controls 2.15 as Controls
import QtQuick.Layouts 1.15
import org.kde.kirigami 2.20 as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
    // Unique identifier to reference this object
    id: root

    // 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.

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 van het venster title 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.

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!").

main.cpp

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.

main.cpp is 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

#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    KLocalizedString::setApplicationDomain("helloworld");
    QCoreApplication::setOrganizationName(QStringLiteral("KDE"));
    QCoreApplication::setOrganizationDomain(QStringLiteral("kde.org"));
    QCoreApplication::setApplicationName(QStringLiteral("Hello World"));

    if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
        QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
    }

    QQmlApplicationEngine engine;

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

    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. Als u al wat verder wilt gaan dan kunt u meer lezen hoe deze main.cpp werkt in deze pagina.

resources.qrc

Onze resources.qrc is een Qt Resource file. Het bevat de lijst met alle QML bestanden evenals andere bestanden (zoals aangepaste pictogrammen) die ingevoegd zullen worden in het binaire programma.

1
2
3
4
5

<RCC>
    <qresource prefix="/">
        <file alias="main.qml">contents/ui/main.qml</file>
    </qresource>
</RCC>

Merk de regel <file alias="main.qml">contents/ui/main.qml</file> op. Het detailleert welke QML bestanden ingevoegd gaan worden in het compilatieproces. In ons geval gaan we alleen main.qml gebruiken, maar als we meer QML bestanden aan onze code toevoegen, moeten we nagaan dat we het invoegen in bestand resources.qrc door nog een regel zoals deze in te voegen.

Dit hulpbronbestand laat ons het pad "qrc:" + "/main.qml" gebruiken in onze main.cpp, in plaats van het moeten specificeren van het gehele pad "contents/ui/main.qml".

CMakeLists.txt

CMakeLists.txt bestanden zijn nodig om het door KDE gekozen bouwsysteem te gebruiken, CMake. Het bestand CMakeLists.txt in uw bovenste map gaat enige van de karakteristieken van uw toepassing definiëren. Het voegt ook enige van de afhankelijkheden in 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

cmake_minimum_required(VERSION 3.16)
project(helloworld)

find_package(ECM REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)

find_package(Qt${QT_MAJOR_VERSION} REQUIRED NO_MODULE COMPONENTS
    Core
    Quick
    Test
    Gui
    QuickControls2
    Widgets
)

find_package(KF${QT_MAJOR_VERSION} REQUIRED COMPONENTS
    Kirigami2
    I18n
    CoreAddons
)

add_subdirectory(src)

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 afhankelijkheden van Qt en KDE Frameworks beheerd worden met find_package(). U zult deze regels moeten wijzigen en extra componenten toevoegen die u beslist om te gebruiken tijdens de ontwikkeling van uw toepassing.

De laatste regel, add_subdirectory(src), laat CMake wijzen naar de map 'helloworld/src/', waar uw broncode is gelokaliseerd. Laten we eens kijken in het bestand helloworld/src/CMakeLists.txt aldaar.

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

add_executable(helloworld)

target_sources(helloworld PRIVATE
    main.cpp
    resources.qrc
)

target_link_libraries(helloworld
    Qt${QT_MAJOR_VERSION}::Quick
    Qt${QT_MAJOR_VERSION}::Qml
    Qt${QT_MAJOR_VERSION}::Gui
    Qt${QT_MAJOR_VERSION}::QuickControls2
    Qt${QT_MAJOR_VERSION}::Widgets
    KF${QT_MAJOR_VERSION}::I18n
)

install(TARGETS helloworld ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Deze is heel wat korter! Laten we doornemen wat het doet:

• add_executable maakt een uitvoerbaar programma uit de gegeven bronbestanden.
• target_link_libraries() koppelt dynamisch de bibliotheken, die gebruikt worden in onze code, aan ons uitvoerbare bestand.

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

De toepassing compileren en uitvoeren.

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.

Als u uw project op Linux draait, hebt u de plaats nodig waar het programma geïnstalleerd zal worden. Om dat te doen moeten we de mappen naar onze helloworld/ map in onze gekozen terminaltoepassing wijzigen en de volgende commando's uitvoeren:

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

Het programma zal geïnstalleerd worden in ~/kde5/usr/bin.

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 2019 (msvc) of MinGW (make) gebruikt om uw projecten te compileren.

Indien Visual Studio:

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

Indien 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.

U kunt daarna het programma helloworld uitvoeren met:

helloworld # Op Linux
helloworld.exe # Op Windows

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