Ställa in och komma igång

Installera Kirigami

Innan vi börjar måste vi installera Kirigami på datorn. Det finns tre sätt att göra det:

• Installera Kirigami från arkiven i Linux-distribution
• Using kde-builder
• Installera Kirigami med Craft

Installera Kirigami från arkiven i Linux-distribution.

Vi behöver en C++-kompilator, Qt-utvecklingspaket och Kirigami. Öppna ett terminalprogram och kör något av följande, beroende på vilken Linux-distribution du använder:

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

Ytterligare information för andra distributioner finns här.

Using kde-builder

Set up your development environment with kde-builder. That will give you the necessary development tools and underlying libraries, and build the KDE Frameworks from scratch.

Create a folder ~/kde/src/kirigami-tutorial. In that folder you will place the source code files from this tutorial.

Add the following at the end of your ~/.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

Installera Kirigami med Craft

KDE har ett eget verktyg för att enkelt installera de flesta av dess bibliotek och program: Craft. Det kan användas för att installera Kirigami på Linux, FreeBSD, Windows, Android och macOS.

Du måste följa installationsinstruktionerna för Craft. I slutet av installationen ska du ha kört en miljöinstallationsfil (craftenv.ps1 eller craftenv.sh), som ger dig ett skal i en terminal där du kan kompilera ditt Kirigami-program.

Därefter kan du helt enkelt köra följande på en terminal:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Om du stänger din terminal kan du helt enkelt köra miljöinstallationsfilen igen för att kompilera ditt program.

Projektstruktur

Även om det finns verktyg som enkelt kan skapa våra filer, kommer vi att skapa dem manuellt. Det låter oss förstå delarna som utgör vårt nya program bättre.

Först skapar vi vår projektkatalog (du kan använda kommandona nedan). Vi kallar vår kirigami-tutorial/.

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

Under katalogen skapar vi katalogen src/ och CMakeLists.txt. Det anses i allmänhet vara god praxis att placera alla våra huvudsakliga C++ källkodsfiler i katalogen src. Vi placerar också filen Main.qml i den eftersom den används tillsammans med det körbara programmet.

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

Här är stället där vi hanterar vårt förgrundsprogram.

Om du kan lite Javascript ser mycket av QML bekant ut (även om det har sina egenheter). Qt:s dokumentation har en omfattande mängd material om språket om du känner för att prova något på egen hand. Genom alla de här handledningarna kommer vi att fokusera mycket av vår uppmärksamhet på vår QML-kod, där vi kan använda Kirigami för att få ut så mycket som möjligt av den.

Låt oss för tillfället fokusera på Main.qml. Först importerar vi ett antal viktiga moduler:

• QtQuick, standardbiblioteket som används i QML-program.
• QtQuick Controls, som tillhandahåller ett antal standardkontroller som vi kan använda för att göra vårt program interaktivt.
• QtQuick Layouts, som tillhandahåller verktyg för att placera komponenter inom programmets fönster.
• Kirigami, som tillhandahåller ett antal komponenter lämpade för att skapa program som fungerar över apparater av olika form och storlek.

Sedan kommer vi till vårt baselement, Kirigami.ApplicationWindow som tillhandahåller några grundfunktioner nödvändiga för alla Kirigami-program. Det är fönstret som kommer att innehålla alla våra sidor, huvuddelen av vårt användargränssnitt.

Vi ställer sedan in fönstrets egenskap id till 'root'. Identifierare är användbara eftersom de låter oss referera till en komponent unikt, även om vi har flera av samma typ.

Vi ställer också in fönstrets egenskap title till "Hello World". Du märker att vi har omgivit vår "Hello World" sträng med en funktion som heter i18nc(), där vi beskriver strängens sammanhang förutom själva strängen.

Därefter anger vi första sidan i vår sidstapel. Del flesta Kirigami-program är organiserade som en stapel av sidor, där varje sida innehåller relaterade komponenter anpassade för en viss uppgift. För närvarande låter vi det vara enkelt, och håller oss till en enda sida. pageStack är en sidstapel som initialt är tom som Kirigami.ApplicationWindow tillhandahåller, och med pageStack.initialPage: Kirigami.Page {...} ställer vi in den första sidan som presenteras när programmet laddas i en Kirigami.Page. Sidan står för allt vårt innehåll.

Slutligen inkluderar vi en Controls.Label på vår sida, som låter oss placera text på den. Vi använder anchors.centerIn: parent för att centrera vår beteckning horisontellt och vertikalt inom vårt överliggande element. I det här fallet är det överliggande elementet för Controls.Label vår Kirigami.Page. Det sista vi behöver göra är att ange texten: text: i18n("Hello World!").

org.kde.tutorial.desktop

Det primära syftet med Desktop Entry-filer är att visa programmet i programstart på Linux. En annan anledning att ha dem är att ha fönsterikoner på Wayland, eftersom de måste tala om för sammansättningen att "det här fönstret hör ihop med den här ikonen".

Det måste följa ett omvänt domännamnsschema följt av tillägget .desktop såsom 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

CMakeLists.txt

Filerna kallade CMakeLists.txt behövs för att använda KDE:s utvalda byggsystem, CMake. Vår kirigami-tutorial/CMakeLists.txt specificerar vissa av programmets egenskaper. Den inkluderar också några av de beroenden vi behöver för att kunna kompilera vårt projekt.

 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 definierar hur dina projekt byggs. Det mesta av innehållet här är bara för att projektet ska komma igång. Du kan läsa en radvis, djupgående, förklaring av vad CMakeLists filen gör här.

Det viktigaste att komma ihåg är att C++ beroenden av Qt och KDE Ramverk hanteras med find_package() och QML körtidsberoenden hanteras med ecm_find_qml_module(). Du måste ändra raderna och inkludera alla ytterligare komponenter som du bestämmer dig för att använda under utvecklingen av programmet.

Raden med add_subdirectory(src), pekar CMake på katalogen 'kirigami-tutorial/src/', där vår källkod finns.

Raden med install() talar om för CMake var skrivbordsfilen ska installeras.

Låt oss fördjupa oss i filen kirigami-tutorial/src/CMakeLists.txt där.

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

Filen består av fem steg:

1. skapa en körbar fil
2. ändra den körbara filen till en QML-modul som accepterar QML-filer
3. lägg till C++ och QML-filer i den körbara filen
4. länka biblioteken som krävs för att körbara filen ska köras
5. installera den körbara filen på rätt plats

Nästa gång fler QML-filer behöver läggas till, gör det i det befintliga anropet ecm_target_qml_sources(). C++ filer som använder nyckelordet QML_ELEMENT, som vi kommer att se senare i handledningen, kan läggas till med target_sources().

Nu när vi har tagit hand om CMake, låt oss titta på filerna vi ska spendera den största delen av tiden att arbeta med.

main.cpp

Filen kirigami-tutorial/src/main.cpp hanterar "uppgiftslogiken" i vårt program. C++ är praktiskt eftersom det är flexibelt och snabbt, även om det är mer omfattande än andra programspråk.

Den fungerar också som programmets startpunkt. De två delarna av vårt projekt, bakgrund och användargränssnittet, skapas och startas båda här.

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

För tillfället behöver vi inte gå in på detaljerna rörande vad vår kod i main.cpp gör i så stor utsträckning, men dess roll växer signifikant när vi bestämmer oss för att lägga till mer komplicerad funktionalitet i vårt program i framtiden.

Om du vill komma framåt, kan du läsa mer om hur main.cpp fungerar i Figuring out main.cpp.

Om du vill se några sätt C++ koden kan förbättras, som att använda KAboutData för översättbar metadata i programmet, se till att ta en titt på vår KXmlGui handledning /kxmlgui).

För tillfället är den del som intresserar oss den här raden:

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

Det första argumentet är URI angiven i kirigami-tutorial/src/CMakeLists.txt, och det andra argumentet är namnet på QML-modulen vi vill använda (Main, kommer från namnet på vår Main.qml -fil, som måste börja med en stor bokstav).

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

Kompilera och installera programmet

Vi har nästa nått mållinjen. Det sista vi måste göra är att bygga och köra vårt program. Hur man gör det beror på vilken plattform som används.

Linux eller FreeBSD

Compiling with kde-builder

Make sure you have followed the instructions in Using kde-builder.

Compile the necessary build dependencies with kde-builder, then compile kirigami-tutorial by running the following commands in a terminal:

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

Compiling manually

Change directories to the project's root folder, then run the following command in a terminal:

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

Programmet installeras i ~/.local/bin och dess skrivbordspost i $HOME/.local/share/applications.

Windows

Om du kompilerar projektet på Windows efter att ha ställt in Craft, ska CMake automatiskt upptäcka rätt kompilator:

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

Beroende på hur du installerade kompilatorn, kan du behöva ange en CMake Generator för det första steget, beroende på om du använder Visual Studio (msvc) eller MinGW (make) för att kompilera dina projekt.

Om Visual Studio, beroende på kompilatorn du valde att installera, kan det vara:

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

Eller:

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

För MinGW:

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

I båda fall, installeras programmet i C:\CraftRoot\bin.

Om du någon gång tvivlar på namnet på kompilatorn som ska användas i 'cme-anropet', kör:

cmake -G

Det listar alla tillgängliga generatorer.

Köra programmet

Därefter kan programmet kirigami-hello köras med:

kirigami-hello # På Linux, manuellt
kde-builder --run kirigami-hello # With kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # With kdesrc-build
kirigami-hello.exe # På Windows

Se där! Nu dyker ditt allra första Kirigami-program upp framför dina ögon.

För att köra den nya QML-applikationen i mobilläge kan man använda QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Om du har kompilerat projektet manuellt med CMake och av någon anledning vill avinstallera projektet kan du köra:

cmake --build build/ --target uninstall