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:
sudo pacman -S base-devel extra-cmake-modules cmake kirigami ki18n kcoreaddons breeze kiconthemes qt6-base qt6-declarative qqc2-desktop-style | |
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 qqc2-desktop-style | |
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 qqc2-desktop-style |
Verdere informatie voor andere distributies is hier te vinden.
If you wish to build Kirigami with Qt6, it is recommended to use kdesrc-build instead, especially for Linux installations using Plasma 5.
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.
Daarna kunt u eenvoudig het volgende in een terminal uitvoeren:
kdesrc-build 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. Hetrdt 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 case you want to automatically build the project with kde-builder/kdesrc-build, custom module name should be the same as the project root folder (in our case it will be "kirigami-tutorial"), otherwise you would need to customize thesource-dir
or dest-dir
for the module. We will assume the path to your main.cpp
will be ~/kde/src/kirigami-tutorial/src/main.cpp
.Main.qml
|
|
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 sleutelwoordas
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 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.
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
The primary purpose of Desktop Entry files is to show your app on the application launcher on Linux. Another reason to have them is to have window icons on Wayland, as they are required to tell the compositor "this window goes with this icon".
It must follow a reverse-DNS naming scheme followed by the .desktop
extension such as org.kde.tutorial.desktop
:
|
|
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.
|
|
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.
The line with install()
tells CMake where to install the desktop file.
Let's delve into the kirigami-tutorial/src/CMakeLists.txt
file in there.
|
|
This file consists of five steps:
- create an executable
- change the executable into a QML module that accepts QML files
- add C++ and QML files to the executable
- link the libraries necessary for the executable to run
- install the executable to the right place
Next time you need to add more QML files, add them to the existing ecm_target_qml_sources()
call. C++ files that use the QML_ELEMENT keyword which we will see later in the tutorial can be added using target_sources()
.
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.
|
|
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
De toepassing moet zijn pictogramthema, QStyle en QtQuick Controls -stijl naar Breeze instellen om op Windows te verschijnen. Om er meer over te weten te komen, zie Begrijpen van main.cpp.
Als wat vooruit wilt lopen dan kunt u meer te lezen over hoe deze main.cpp
werkt in Begrijpen van main.cpp
If you want to see a few ways on how the C++ code can be improved, like using KAboutData for translatable application metadata, be sure to check our KXmlGui tutorial.
For now, the part that interests us is this line:
engine.loadFromModule("org.kde.tutorial", "Main");
The first argument is the URI set in kirigami-tutorial/src/CMakeLists.txt
, and the second argument is the name of the QML module we want to use (Main
, coming from the name of our Main.qml
file, which needs to start with an uppercase letter).
The old method
You might encounter this alternative way to load QML files in real code!
The old method of loading QML files had some disadvantages and after Qt6 it became excessively verbose:
engine.load(QUrl(QStringLiteral("qrc:/qt/qml/org/kde/tutorial/qml/Main.qml")));
This Qt resource URI above follows the pattern <resource_prefix><import_URI><optional_QML_dir><file>
. In this case:
- resource prefix = default / in Qt5, /qt/qml in Qt6
- import URI = /org/kde/tutorial, which matches the URI org.kde.tutorial
- optional QML dir = /qml, necessary if the QML files are stored in a directory called 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 or FreeBSD
If you want kdesrc-build to handle building and installation of your project, you need to specify a custom module in your ~/.config/kdesrc-buildrc
:
...
module kirigami-tutorial
no-src
end module
Then you can build and install it with the command:
kdesrc-build kirigami-tutorial
In geval u het bouwen en installeren handmatig wilt doen zonder kdesrc-build, 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 "~/.local"
Het programma zal geïnstalleerd worden in ~/.local/bin
en zijn desktop-item in ~/.local/share/applications
.
Windows
If you are compiling your project on Windows after having set up Craft, CMake should automatically detect the right compiler:
cmake -B build/
cmake --build build/
cmake --install build/
Afhankelijk van hoe u de compiler hebt geïnstalleerd, moet u misschien een CMake-generator specificeren voor de eerste stap, afhankelijk van of u Visual Studio (msvc) of MinGW (make) gebruikt om uw projecten te compileren.
If Visual Studio, depending on the compiler you chose to install, it might be:
cmake -B build/ -G "Visual Studio 16 2019"
Or:
cmake -B build/ -G "Visual Studio 17 2022"
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
.
If you ever get in doubt as to the name of the compiler that should be used in the cmake
call, run:
cmake -G
It will list all available generators.
De toepassing uitvoeren
U kunt daarna het programma kirigami-tutorial
uitvoeren met:
kirigami-hello # Op Linux, handmatig
kde-builder --run kirigami-hello # On Linux, with 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.
To run the new QML application in mobile mode, you can use QT_QUICK_CONTROLS_MOBILE=1
:
QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello
If you have compiled the project manually with CMake and for some reason you'd like to uninstall the project, you can run:
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.