Ställa in och komma igång

Bli redo att skapa vårt första program med Kirigami

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 din Linux-distributions arkiv
Bygga Kirigami med kdesrc-build
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:

Kubuntu KDE 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
Manjaro Arch	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

Further information for other distributions can be found here.

Om du vill bygga Kirigami med Qt6 är detta för närvarande inte möjligt med endast distributionspaket på Linux. Du måste ta till kdesrc-build istället.

Bygga Kirigami med kdesrc-build

KDE har ett eget verktyg för att enkelt bygga alla dess bibliotek och program: kdesrc-build. Det kan användas för att bygga Kirigami på Linux och FreeBSD.

For this tutorial, you will need to follow the setup instructions for kdesrc-build but using a ~/kde5 directory instead, then copy the sample KF5 file to your home:

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

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

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

Och sedan kan du kompilera dina Kirigami-projekt med skalet i samma terminal som du använde för att hämta prefixfilen. Om du stänger terminalen kan du helt enkelt hämta filen igen för att kompilera ditt program.

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

Tema på Windows

Klicka här för att läsa mer

När du bygger programmet efter att ha installerat beroenden med Craft, säkerställer enbart installation av KIconThemes och Breeze att programmet kan använda Breeze-ikoner på plattformar som Windows, länkning är inte nödvändig. qqc2-desktop-style ansvarar å andra sidan för den snygga stilen vi vill införa på plattformarna.

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. Vi kallar den "helloworld".

helloworld/
├── CMakeLists.txt
└── src/
    ├── CMakeLists.txt
    ├── main.cpp
    ├── resources.qrc
    └── contents/
        └── ui/
            └── 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 källkodsfiler i katalogen src. Vår src/ katalog innehåller i sin tur en katalog som heter contents/, som innehåller en katalog som heter ui/. Det är här vi skapar våra QML-filer.

Tips

Du kan snabbt skapa filstrukturen med:

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

Alternativt kan standardmallen i Kirigami användas, som tillhandahålls av KDevelop, KDE:s huvudsakliga integrerade utvecklingsmiljö för kodning i C++ och QML. KAppTemplate är också tillgänglig om en snabb mall för att börja koda i din favoritmiljö eller texteditor är allt som behövs.

Det är en KDE-konvention, men alla KDE-projekt använder inte den här strukturen. Det står dig fritt att göra saker och ting annorlunda, men du måste ta hänsyn till det när du skapar filerna CMakeLists.txt och 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!")
        }
    }
}

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.

Anmärkning

Att placera QtQuick-kontroller och Kirigami-import i separata namnrymder med nyckelordet as är bästa praxis för att säkerställa att inga komponenter med samma namn kan orsaka konflikt. Du kan se olika namn för QtQuick Controls i verkligheten, såsom "QQC" eller "QQC2". Vi använder "Controls" i handledningen för tydlighetens skull.

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.

Anmärkning

i18n()-funktioner gör programmet lättare att översätta, eftersom de returnerar en version av den tillhandahållna strängen på användarens språk (under förutsättning att vårt program har översatts till det språket). Även om en engelskspråkig användare ser vår fönstertitel som 'Hello World', skulle en spansk användare kunna se "Hola Mundo".

i18nc() bygger på funktionen i18n() genom att tillåta utvecklare att ge visst sammanhang till översättarna som arbetar med programmet. Det är därför vi har inkluderat strängen "@title" innan "Hello World". Se Ki18n Programmer's guide för mer information.

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

main.cpp

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.

main.cpp är också 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
#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();
}

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 på den här sidan.

resources.qrc

Vår resources.qrc är en Qt-resursfil. Den innehåller en lista över alla QML-filer samt andra filer (som egna ikoner) som kommer att inkluderas i binärfilen.

1
2
3
4
5
<RCC>
    <qresource prefix="/">
        <file alias="main.qml">contents/ui/main.qml</file>
    </qresource>
</RCC>

Observera raden <file alias="main.qml">contents/ui/main.qml</file>. Den anger vilka QML-filer som ska inkluderas i kompileringsprocessen. I vårt fall används bara main.qml, men om vi skulle lägga till fler QML-filer i vår kod, skulle vi behöva säkerställa att de inkluderas i resources.qrc genom att lägga till ytterligare rader som den här.

Resursfilen låter oss använda sökvägen "qrc:" + "/main.qml" i main.cpp, istället för att behöva ange hela sökvägen "contents/ui/main.qml".

CMakeLists.txt

Filerna kallade CMakeLists.txt behövs för att använda KDE:s utvalda byggsystem, CMake. Filen CMakeLists.txti vår toppnivåkatalog 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
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)

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 beroenden på Qt och KDE Ramverk hanteras med find_package(). Du måste ändra raderna och inkludera alla ytterligare komponenter som du bestämmer dig för att använda under utvecklingen av programmet.

Den sista raden, add_subdirectory(src), pekar CMake på katalogen 'helloworld/src/', där vår källkod finns. Låt oss fördjupa oss i filenhelloworld/src/CMakeLists.txt där.

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

Den är mycket kortare. Låt oss gå igenom vad den gör:

add_executable() skapar ett körbart program från de angivna källkodsfiler.
target_link_libraries() länkar biblioteken som används i vår kod till vårt körbara program.

Anmärkning

Observera att biblioteken ska motsvara komponenterna som vi inkluderade i vår tidigare CMakeLists.txt fil, annars inkluderas inte komponenterna och vårt program går inte att kompilera.

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.

Kompilera och köra 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.

Om projektet görs på Linux, måste platsen där programmet ska installeras anges. För att göra det, behöver vi lägga till katalogen 'helloworld' i terminalprogrammet vi tycker bäst om och köra följande kommandon:

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

Programmet installeras i ~/kde5/usr/bin.

Om du kompilerar ditt projekt med Craft på Windows kan du behöva ange en CMake Generator för det första steget, beroende på om du använder Visual Studio 2019 (msvc) ) eller MinGW (make) för att kompilera dina projekt.

För Visual Studio:

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

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.

Därefter kan programmet helloworld köras med:

helloworld # På Linux
helloworld.exe # På Windows

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

Skärmbild av det genererade Kirigami-programmet

Anmärkning

Nästa gång du vill skapa filerna och katalogerna som behövs, kan du använda KAppTemplate eller KDevelop för att automatiskt generera ett lämpligt projekt att starta med. De är tillgängliga från alla större distributioners arkiv. Programmen genererar också filer som innehåller AppStream metadata och en .desktop-fil som innehåller information om hur programmet ska visas i en Linux programstart.

Tack vare magin i CMakeLists, kan du också använda integrerade utvecklingsmiljöer såsom KDevelop eller QtCreator för att utveckla programmet i en bekväm miljö med minimal ansträngning.

Explaining pages