Nastavitev in zagon

Nameščanje Kirigami

Preden začnemo, bomo morali namestiti Kirigami na naš računalnik. To lahko storite na tri načine:

• Namestitev Kirigamija iz skladišč v vaši distribuciji Linuxa
• Izgradnja Kirigamija s kde-builder
• Namestitev Kirigami s programom Craft

Namestitev Kirigamija iz skladišč v vaši distribuciji Linuxa

Potrebujemo prevajalnik C++, razvojne pakete Qt in Kirigami. Odprite terminalsko aplikacijo in zaženite nekaj od naslednjega, odvisno od tega, katero distribucijo Linuxa uporabljate:

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

Dodatne informacije za druge distribucije najdete tukaj.

Gradnja Kirigami s kde-builder

KDE ima orodje po meri za enostavno izgradnjo vseh svojih knjižnic in programov: kde-builder. Uporablja se lahko za izdelavo Kirigamija na Linuxu in FreeBSD.

Za ta učbenik boste morali slediti navodilom za namestitev kde-builder.

Po tem lahko preprosto zaženete naslednje na terminalu:

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

Namestitev Kirigami s programom Craft

KDE ima orodje po meri za preprosto namestitev večine svojih knjižnic in programov: Craft. Uporablja se lahko za namestitev Kirigamija v Linux, FreeBSD, Windows , Android in [macOS](https://community.kde. org/Guidelines_and_HOWTOs/Build_from_source/Mac).

Slediti boste morali navodilom za namestitev za Craft. Do konca namestitve bi morali zagnati datoteko za nastavitev okolja (craftenv.ps1 ali craftenv.sh), ki vam bo dala terminalsko lupino, kjer boste prevajali svojo aplikacijo Kirigami.

Po tem lahko preprosto zaženete naslednje na terminalu:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Če zaprete terminal, lahko preprosto znova zaženete namestitveno datoteko okolja, da prevedete svojo aplikacijo.

Struktura projekta

Medtem ko obstajajo orodja, s katerimi lahko enostavno nastavite naše datoteke, jih bomo ustvarili ročno. Tako bomo bolje razumeli dele, ki bodo iznašli našo novo aplikacijo.

Najprej ustvarimo našo projektno mapo (uporabite lahko spodnje ukaze). Našo vadnico bomo imenovali kirigami-tutorial/.

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

V tej mapi bomo ustvarili mapo src/ in CMakeLists.txt. Na splošno velja za dobro prakso, da vse naše glavne kodne datoteke C++ postavite v mapo src/. Vanjo smo vstavili tudi datoteko Main.qml, saj se bo izvajala skupaj z izvršljivo datoteko.

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

Tukaj bomo delali na ospredju naše aplikacije.

Če poznate nekaj Javascripta, se vam bo večina QML zdela znana (čeprav ima svoje posebnosti). Dokumentacija Qt vsebuje obsežno količino gradiva o tem jeziku, če želite nekaj poskusiti sami. Med temi učbenki bomo veliko pozornosti namenili naši kodi QML, kjer lahko uporabimo Kirigami, da ga kar najbolje izkoristimo.

Za zdaj se osredotočimo na Main.qml. Najprej uvozimo številne pomembne module:

• QtQuick je standardna knjižnica, ki se uporablja v aplikacijah QML.
• QtQuick Controls, ki zagotavlja številne standardne kontrole, s katerimi lahko naše aplikacije naredimo interaktivne.
• QtQuick Layouts, ki ponuja orodja za postavitev komponent v okno aplikacij.
• Kirigami, ki zagotavlja številne komponente primerne za ustvarjanje aplikacij, ki delujejo po napravah različnih oblik in velikosti.

Nato pridemo do našega osnovnega elementa 'Kirigami.ApplicationWindow', ki zagotavlja nekaj osnovnih funkcij, ki so potrebne za vse Kirigami aplikacije. To je okno, ki bo vsebovalo vsako od naših strani, glavne odseke našega uporabniškega vmesnika.

Nato določimo lastnost okna določilnik 'id' na 'root'. Določilniki so uporabni, ker nam dovolijo edinstveno sklicevanje na komponento, tudi če jih imamo več iste vrste.

Naslov okna kot lastnost 'title' smo nastavili na "Hello World". Opazili boste, da smo zavili naš niz "Hello World" v funkcijo imenovano 'i18nc()', kjer podrobno opišemo kontekst niza kot tudi sami niz.

Nato nastavimo prvo stran na našem skladu strani. Večina aplikacij Kirigami je organizirana kot sklad strani, vsaka stran vsebuje povezane komponente, ki so prilagojene določeni nalogi. Za zdaj se držimo preprostega pravila in se držimo ene same strani. Sklad pageStack je v začetku prazen sklad strani, ki ga je v Kirigami.ApplicationWindow in z začetno stranjo pageStack.initialPage: Kirigami.Page {...} nastavimo prvo stran, predstavljeno ob nalaganju aplikacije na ' Kirigami.Page, ki bo vsebovala vso našo vsebino.

Na koncu na naši strani vključimo v Controls.Label, ki nam dovoli, da besedilo postavimo na našo stran. Uporabljamo 'anchors.centerIn: parent' za centriranje naše oznake vodoravno in navpično znotraj našega nadrejenega elementa. V tem primeru je nadrejena komponenta oznake stran Kirigami.Page. Zadnja stvar, ki jo moramo storiti je, da nastavimo besedilo: text: i18n("Hello World!").

org.kde.tutorial.desktop

Glavni namen datotek za vnos namizja je prikazati vašo aplikacijo v zaganjalniku aplikacij v sistemu Linux. Drug razlog, da jih imate, so ikone oken na Waylandu, saj morajo sestavljavcu sporočiti "to okno gre s to ikono".

Slediti mora shemi poimenovanja povratnega DNS, ki ji sledi končnica .desktop, kot je 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

Datoteke CMakeLists.txt so potrebne za uporabo izbranega gradbenega sistema KDE, CMake. Naša datoteka kirigami-tutorial/CMakeLists.txt bo določila nekatere značilnosti naše aplikacije. Vključuje tudi nekatere odvisnosti, ki jih potrebujemo za prevajanje našega projekta.

 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)

Datoteka CMakeLists.txt določa, kako zgraditi vaše projekte. Večina vsebine tukaj je samo za postopek postopnega razvoja vašega projekta. Preberite poglobljeno razlago, kaj datoteka CMakeLists počne tukaj.

Najpomembnejša stvar, ki jo morate upoštevati, je, da se odvisnosti gradnje C++ ogrodij Qt in KDE upravljajo s find_package() in QML odvisnosti med izvajanjem se upravljajo z ecm_find_qml_module(). Te vrstice boste morali spremeniti in vključiti vse dodatne komponente, ki se jih boste odločili uporabiti med razvojem vaše aplikacije.

Vrstica z add_subdirectory(src) usmerja CMake v imenik kirigami-tutorial/src/, kjer se nahaja naša izvorna koda.

Vrstica z install() pove CMake, kam naj namesti namizno datoteko.

Poglobimo se v tamkajšnjo datoteko kirigami-tutorial/src/CMakeLists.txt.

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

Ta datoteka je sestavljena iz petih korakov:

1. ustvari izvršljivo datoteko
2. spremeni izvršljivo datoteko v modul QML, ki sprejema datoteke QML
3. dodaj datoteke C++ in QML k izvršljivi datoteki
4. poveži knjižnice, ki so potrebne za delovanje izvršljive datoteke
5. namesti izvršljivo datoteko na pravo mesto

Ko boste naslednjič morali dodati več datotek QML, jih dodajte obstoječemu klicu ecm_target_qml_sources(). Datoteke C++, ki uporabljajo ključno besedo QML_ELEMENT, ki jo bomo videli kasneje v učbeniku, je mogoče dodati z uporabo target_sources().

Zdaj, ko je za CMake poskrbljeno, poglejmo datoteke, s katerimi bomo večino časa preživeli pri delu.

main.cpp

Datoteka kirigami-tutorial/src/main.cpp obravnava "poslovno logiko" naše aplikacije. C++ je priročen, ker je prilagodljiv in hiter, čeprav je bolj zapleten kot drugi programski jeziki.

Deluje tudi kot vstopna točka v našo aplikacijo. Oba dela našega projekta, zaledje in uporabniški vmesnik, sta nastavljena in zagnana tukaj.

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

Za zdaj se nam ni treba spuščati v preveč podrobnosti o tem, kaj počne naša koda main.cpp, vendar bo njena vloga postala bistveno pomembnejša, ko se bomo odločili, da bomo v prihodnosti naši aplikaciji dodali bolj zapleteno funkcionalnost.

Če želite napredovati, si lahko preberete več o tem, kako ta main.cpp deluje v Ugotavljanje main.cpp.

Če želite videti nekaj načinov, kako je mogoče izboljšati kodo C++, na primer z uporabo KAboutData za metapodatke aplikacij, ki jih je mogoče prevesti, si oglejte našo KXmlGui tutorial.

Za zdaj nas zanima ta vrstica:

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

Prvi argument je URI, nastavljen v kirigami-tutorial/src/CMakeLists.txt, drugi argument pa je ime modula QML, ki ga želimo uporabiti (Main, izhaja iz imena našega Main.qml `, ki se mora začeti z veliko črko).

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

Prevajanje in namestitev aplikacije

Skoraj smo na ciljni črti. Zadnja stvar, ki jo moramo narediti, je zgraditi in zagnati našo aplikacijo. To bo odvisno od platforme, na kateri ste.

Linux ali FreeBSD

Če želite, da kde-builder obravnava gradnjo in namestitev vašega projekta, morate:

• prenesti mapo projekta na ~/kde/src, to je, ~/kde/src/kirigami-tutorial
• določiti modul po meri na koncu vašega ~/.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

Nato ga lahko zgradite in namestite z ukazom:

kde-builder kirigami-tutorial

Če želite sestaviti in namestiti ročno brez kde-builderja, boste morali določiti mesto, kjer bo program nameščen. Da to naredimo, moramo spremeniti imenike v našo mapo kirigami-tutorial/ v naši izbrani terminalski aplikaciji in zagnati naslednje ukaze:

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

Program bo nameščen v $HOME/.local/bin, njegov vnos na namizju pa v $HOME/.local/share/applications.

Windows

Če prevajate svoj projekt v sistemu Windows, potem ko ste nastavili Craft, CMake bi moral samodejno zaznati pravi prevajalnik:

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

Odvisno od tega, kako ste namestili prevajalnik, boste morda morali določiti CMake Generator za prvi korak, odvisno od tega, ali za prevajanje svojih projektov uporabljate Visual Studio (msvc) ali MinGW (make).

Če je Visual Studio, odvisno od prevajalnika, ki ste ga izbrali za namestitev, je lahko:

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

Ali:

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

Če MinGW:

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

V obeh primerih bo program nameščen na C:\CraftRoot\bin.

Če ste kdaj v dvomih glede imena prevajalnika, ki bi ga morali uporabiti v klicu cmake, zaženite:

cmake -G

Navedel bo vse razpoložljive generatorje.

Zagon aplikacije

Nato lahko zaženete program kirigami-hello z:

kirigami-hello # Na Linuxu, ročno
kde-builder --run kirigami-hello # V sistemu Linux s kde-builderjem
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # Na Linuxu s kdesrc-build
kirigami-hello.exe # Na Windows

Voilà! Zdaj boste videli, da se vaša prva Kirigami aplikacija pojavi pred vašimi očmi.

Za zagon nove aplikacije QML v mobilnem načinu lahko uporabite QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Če ste projekt prevedli ročno s CMake in bi iz nekega razloga želeli odstraniti projekt, lahko zaženete:

cmake --build build/ --target uninstall