Agordi kaj komenci

Instalado de Kirigami

Antaŭ ol komenci, ni devos instali Kirigami sur nia maŝino. Estas tri manieroj fari tion:

• Instalante Kirigami el la deponejoj en via Linuksa distribuo
• Konstruante Kirigami kun kdesrc-build
• Instalante Kirigami kun Craft

Instalante Kirigami el la deponejoj en via Linuksa distribuo

Ni bezonas C++-kompililon, Qt-disvolvajn pakaĵojn kaj Kirigami. Malfermu terminalan aplikaĵon kaj rulu unu el la jenaj, depende de kiu Linuksa distribuo vi uzas:

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

Pliaj informoj pri aliaj distribuoj troveblas ĉi tie.

Se vi volas konstrui Kirigami per Qt6, ĉi tio nuntempe ne eblas kun nur distribuaj pakoj en Linukso. Vi devos uzi kdesrc-build anstataŭe.

Konstruante Kirigami per kdesrc-build

KDE havas propran ilon por facile konstrui ĉiujn ĝiajn bibliotekojn kaj programojn: kdesrc-build. Ĝi povas esti uzata por konstrui Kirigami sur Linukso kaj FreeBSD.

Por ĉi tiu lernilo, vi devos sekvi la agordan instrukciojn por kdesrc-build sed uzi dosierujon ~/kde5 anstataŭe, poste kopii la specimenon KF5 dosiero al via hejmo:

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

Post tio, vi povas simple ruli la jenon sur terminalo:

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

Kaj tiam vi povas kompili viajn Kirigami-projektojn sur la sama terminala ŝelo, kiun vi uzis por fonti la prefiksan dosieron. Se vi fermas vian terminalon, vi povas simple fonti la dosieron denove por kompili vian apon.

Instalado de Kirigami kun Craft

KDE havas propran ilon por facile instali la plej multajn el siaj bibliotekoj kaj programoj: Craft. Ĝi povas esti uzata por instali Kirigami en Linukso, FreeBSD, Vindozo,Android kaj macOS.

Vi devos sekvi la agordan instrukciojn por Craft. Antaŭ la fino de la aranĝo, vi devus esti rulinta medio-agordan dosieron (craftenv.ps1 aŭ craftenv.sh), kiu donos al vi terminalŝelon kie vi kompilos vian Kirigami-aplikaĵon.

Post tio, vi povas simple ruli la jenon sur terminalo:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Se vi fermas vian terminalon, vi povas simple ruli la medio-agordan dosieron denove por kompili vian apon.

Projekta strukturo

Kvankam ekzistas iloj, kiuj povas facile agordi niajn dosierojn, ni kreos ilin permane. Ĉi tio permesos al ni pli bone kompreni la pecojn, kiuj konsistigos nian novan aplikaĵon.

Unue ni kreas nian projektan dosierujon. Ni nomos la nian "saluton".

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

Ene de ĉi tiu dosierujo ni kreos dosierujon src/ kaj CMakeLists.txt. Ĝenerale estas konsiderata bona praktiko meti ĉiujn niajn ĉefajn koddosierojn en dosierujon src/. Nia dosierujo src/ siavice enhavos dosierujon nomitan contents/, kiu mem enhavas dosierujon nomitan ui/. Jen kie ni kreos niajn QML-dosierojn.

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

Ĉi tio estas KDE-konvencio, sed ne ĉiuj KDE-projektoj uzas ĉi tiun strukturon. Vi rajtas agordi aferojn alimaniere, sed vi devos konsideri tion kiam vi kreas viajn dosierojn CMakeLists.txt kaj resources.qrc.

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

Jen kie ni pritraktos la fasadon de nia aplikaĵo.

Se vi konas iom da Javascript, tiam multe de QML ŝajnos al vi konata (kvankam ĝi havas siajn proprajn proprecojn). La dokumentaro de Qt havas ampleksan kvanton da materialo pri ĉi tiu lingvo se vi emas provi ion memstare. Dum ĉi tiuj lerniloj ni koncentriĝos grandan parton de nia atento al nia QML-kodo, kie ni povas uzi Kirigami por akiri la plej grandan parton de ĝi.

Nuntempe, ni koncentriĝu pri main.qml. Unue ni importas kelkajn gravajn modulojn:

• QtQuick, la norma biblioteko uzata en QML-aplikoj.
• QtQuick Controls, kiu provizas kelkajn normajn regilojn, kiujn ni povas uzi por fari niajn aplikaĵojn interagaj.
• QtQuick Layouts, kiu disponigas ilojn por meti komponentojn ene de la aplika fenestro.
• Kirigami , kiu provizas kelkajn komponantojn taŭgajn por krei aplikojn, kiuj funkcias trans aparatoj de malsamaj formoj kaj grandecoj.

Ni tiam venas al nia baza elemento, Kirigami.ApplicationWindow , kiu provizas kelkajn bazajn funkciojn necesajn por ĉiuj Kirigami-aplikoj. Ĉi tiu estas la fenestro, kiu enhavos ĉiun el niaj paĝoj, la ĉefaj sekcioj de nia UI.

Ni tiam starigas la id-proprecon de la fenestro al "radiko". ID-oj estas utilaj ĉar ili lasas nin unike referenci komponenton, eĉ se ni havas plurajn de la sama tipo.

Ni ankaŭ fiksas la fenestron titolo proprecon al "Saluton Mondo". Vi rimarkos, ke ni envolvis nian "Saluton Mondo" en funkcio nomata i18nc(), kie ni detaligas la kuntekston de la ĉeno same kiel la ĉenon mem.

Ni tiam starigas la unuan paĝon de nia paĝa stako. Plej multaj Kirigami-aplikoj estas organizitaj kiel stako de paĝoj, ĉiu paĝo enhavante rilatajn komponentojn taŭgajn por specifa tasko. Nuntempe, ni tenas ĝin simpla, kaj algluiĝas al ununura paĝo. pageStack estas komence malplena stako de paĝoj provizita de Kirigami.ApplicationWindow , kaj kun pageStack.initialPage: Kirigami.Page {...} ni agordas la unuan paĝon prezentitan post ŝargo de la aplikaĵo al Kirigami.Paĝo . Ĉi tiu paĝo enhavos nian tutan enhavon.

Fine, ni inkluzivas en nia paĝo Controls.Label kiu ebligas al ni meti tekston sur nia paĝo. Ni uzas anchors.centerIn: parent por centri nian etikedon horizontale kaj vertikale ene de nia gepatra elemento. En ĉi tiu kazo, la gepatra komponanto de nia etikedo estas Kirigami.Paĝo . La lasta afero, kiun ni devas fari, estas agordi ĝian tekston: text: i18n("Saluton Mondo!").

ĉefa.cpp

main.cpp pritraktas la "komercan logikon" de nia aplikaĵo. C++ estas oportuna ĉar ĝi estas fleksebla kaj rapida, eĉ se ĝi estas pli engaĝita ol aliaj programlingvoj.

main.cpp ankaŭ estas la enirpunkto al nia aplikaĵo. La du partoj de nia projekto, la backend kaj la uzantinterfaco, estas ambaŭ starigitaj kaj komencitaj ĉi tie.

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

Nuntempe, ni ne bezonas tro multe detalojn pri tio, kion faras nia main.cpp-kodo, sed ĝia rolo estos signife pli grava post kiam ni decidos aldoni pli kompleksajn funkciojn al nia aplikaĵo estonte. Se vi volas antaŭeniri, vi povas legi pli pri kiel ĉi tiu main.cpp funkcias en ĉi tiu paĝo.

rimedoj.qrc

Nia resources.qrc estas Qt Resource-dosiero. Ĝi enhavas la liston de ĉiuj QML-dosieroj same kiel aliajn dosierojn (kiel propraj piktogramoj) kiuj estos inkluzivitaj en la binaron.

1
2
3
4
5

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

Rimarku la linion <file alias="main.qml">contents/ui/main.qml</file>. Ĝi detaligas kiuj QML-dosieroj estos inkluzivitaj en la kompilprocezo. En nia kazo ni nur uzas main.qml, sed se ni aldonus pliajn QML-dosierojn al nia kodo, ni bezonus certigi, ke ni inkluzivas ĝin en la dosieron resources.qrc aldonante alian linion kiel ĉi tiu. .

Ĉi tiu rimeda dosiero ebligas al ni uzi la vojon "qrc:" + "/main.qml" en nia main.cpp, anstataŭ bezoni specifi la tutan vojon "contents/ui/main.qml". .

CMakeLists.txt

CMakeLists.txt dosieroj estas bezonataj por uzi la elektosistemon de KDE, CMake. La dosiero CMakeLists.txt en nia plej alta dosierujo specifos iujn el la karakterizaĵoj de nia aplikaĵo. Ĝi ankaŭ inkluzivas kelkajn el la dependecoj, kiujn ni bezonas por kompili nian projekton.

 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)

La CMakeLists.txt difinas kiel konstrui viajn projektojn. Plejparto de la enhavo ĉi tie estas nur por komenci vian projekton. Vi povas legi linio-post-linian, profundan klarigon pri tio, kion faras ĉi tiu CMakeLists-dosiero ĉi tie.

La plej grava afero memorinda estas, ke la dependecoj de Qt kaj KDE Frameworks estas administritaj per find_package(). Vi devos modifi ĉi tiujn liniojn kaj inkluzivi iujn ajn kromajn komponantojn, kiujn vi decidas uzi dum la disvolviĝo de via aplikaĵo.

La fina linio, add_subdirectory(src), indikas CMake al la dosierujo helloworld/src/, kie troviĝas nia fontkodo. Ni enprofundu en la dosieron helloworld/src/CMakeLists.txt tie.

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

Ĉi tiu estas multe pli mallonga! Ni trarigardu kion ĝi faras:

• add_executable() kreas ruleblan el la donitaj fontdosieroj.
• target_link_libraries() ligas la bibliotekojn uzatajn en nia kodo al nia rulebla.

Nun kiam CMake estis prizorgita, ni rigardu la dosierojn, kun kiuj ni pasigos la plimulton de nia tempo laborante.

Kompilante kaj funkciigante la aplikaĵon

Ni estas preskaŭ ĉe la cellinio. La lasta afero, kiun ni devas fari, estas konstrui kaj ruli nian aplikaĵon. Fari tion dependos de kiu platformo vi estas.

Se vi ruligas vian projekton en Linukso, vi devos specifi la lokon, kie la programo estos instalita. Por fari tion, ni devas ŝanĝi dosierujojn al nia dosierujo helloworld/ en nia elekta fina aplikaĵo kaj ruli la jenajn komandojn:

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

La programo estos instalita al ~/kde5/usr/bin.

Se vi kompilas vian projekton per Craft en Vindozo, vi eble bezonos specifi CMake Generatoron por la unua paŝo, depende de ĉu vi uzas Visual Studio 2019. (msvc) aŭ MinGW (make) por kompili viajn projektojn.

Se Visual Studio:

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

Se MinGW:

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

En ambaŭ kazoj, la programo estos instalita al C:\CraftRoot\bin.

Vi povas tiam ruli la helloworld-programon per:

helloworld # Sur Linukso
helloworld.exe # Sur Vindozo

Voila! Nun vi vidos vian unuan Kirigami-aperon aperi antaŭ viaj propraj okuloj.