Agordi kaj komenci

Pretiĝas por krei nian unuan Kirigami-aplikaĵon

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
Using kde-builder
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:

Manjaro

Arch

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

Pliaj informoj pri aliaj distribuoj troveblas ĉi tie.

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

⏳ With kdesrc-build...

Click here to know how this was done with kdesrc-build

This step used to be done by writing to ~/.config/kdesrc-buildrc instead with a different syntax:

# after include ${module-definitions-dir}/kf6-qt6.ksb
module kirigami-tutorial
  no-src
end module

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 (vi povas uzi la komandojn sube). Ni nomos nian kirigami-lernilo/.

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

Ene de ĉi tiu dosierujo ni kreos dosierujon src/ kaj CMakeLists.txt. Ĝenerale estas konsiderata bona praktiko meti ĉiujn niajn ĉefajn C++-koddosierojn en dosierujon src/. Ni ankaŭ metas la dosieron Main.qml en ĝi ĉar ĝi estos rulita kune kun la rulebla.

Konsileto

Vi povas rapide krei ĉi tiun dosierstrukturon per:

mkdir -p kirigami-tutorial/src
touch kirigami-tutorial/{CMakeLists.txt,org.kde.tutorial.desktop}
touch kirigami-tutorial/src/{CMakeLists.txt,main.cpp,Main.qml}

Noto

In case you want to automatically build the project with kde-builder, 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 the source-dir or dest-dir for the module. We will assume the path to your main.cpp will be $HOME/kde/src/kirigami-tutorial/src/main.cpp.

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

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.

Noto

Meti la QtQuick-Regilojn kaj Kirigami-importaĵojn en apartajn nomspacojn uzante la ŝlosilvorton as estas plej bona praktiko, kiu certigas, ke neniuj komponantoj kun la sama nomo povas konflikti. Vi eble vidos malsamajn nomojn por QtQuick Controls en natura medio, kiel "QQC" aŭ "QQC2". Ni uzos "Regiloj" en ĉi tiu lernilo por klareco.

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.

Noto

i18n() funkcioj igas vian apon pli facile tradukebla, ĉar ili resendas version de la provizita ĉeno en la lingvo de la uzanto ( kondiĉe ke via aplikaĵo estas lokalizita por tiu lingvo). Dum angla uzanto eble vidos nian fenestrotitolon kiel "Saluton Mondo", hispana uzanto vidos "Hola Mundo".

i18nc() baziĝas sur la funkcio i18n() permesante al programistoj disponigi iom da kunteksto al tradukistoj laborantaj pri la programo . Ĉi tie ni klarigas, ke la UI-komponento estas la titolo de la aplika fenestro, do ni inkluzivis la ĉenon "@title:window" antaŭ "Saluton Mondo". Vidu la Ki18n Programmer's guide por pliaj detaloj.

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

org.kde.tutorial.desktop

La ĉefa celo de Desktop Entry-dosieroj estas montri vian apon sur la aplikaĵlanĉilo en Linukso. Alia kialo por havi ilin estas havi fenestrajn piktogramojn sur Wayland, ĉar ili estas postulataj por diri al la kompostisto "ĉi tiu fenestro konvenas kun ĉi tiu piktogramo".

Ĝi devas sekvi reverse-DNS-nomskemon sekvita de la etendaĵo .desktop kiel ekzemple 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

Noto

Window and taskbar icons will work in a Wayland session only if apps' desktop files are placed in ~/.local/share/applications or /usr/share/applications. To get icons working in this tutorial, either copy the app's desktop file there or switch to a development session as instructed in kde-builder tutorial. Some KDE applications might have working icons if they were already installed on the system.

CMakeLists.txt

CMakeLists.txt dosieroj estas bezonataj por uzi la elektosistemon de KDE, CMake. Nia dosiero kirigami-tutorial/CMakeLists.txt 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
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)

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 por memori estas, ke la C++-konstruaj dependecoj de Qt kaj KDE Frameworks estas administritaj per find_package() kaj QML rultempaj dependecoj estas administritaj per ecm_find_qml_module(). 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 linio kun add_subdirectory(src) indikas CMake al la dosierujo kirigami-tutorial/src/, kie troviĝas nia fontkodo.

La linio kun install() diras al CMake kie instali la labortablan dosieron.

Ni enprofundu en la dosieron kirigami-tutorial/src/CMakeLists.txt 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
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})

Ĉi tiu dosiero konsistas el kvin paŝoj:

krei plenumeblan
ŝanĝi la plenumeblan en QML-modulon, kiu akceptas QML-dosierojn
aldoni C++ kaj QML-dosierojn al la rulebla
ligi la bibliotekojn necesajn por ke la rulebla rulu
instali la ruleblan en la ĝusta loko

Venontfoje vi devas aldoni pliajn QML-dosierojn, aldonu ilin al la ekzistanta ecm_target_qml_sources() alvoko. C++-dosieroj, kiuj uzas la ŝlosilvorton QML_ELEMENT, kiun ni vidos poste en la lernilo, povas esti aldonitaj uzante target_sources().

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

ĉefa.cpp

La dosiero kirigami-tutorial/src/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.

Ĝi ankaŭ funkcias kiel 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
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();
}

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.

Etosado en Vindozo

Alklaku ĉi tie por legi pli

La aplikaĵo devas meti sian piktogram-etoson, QStyle, kaj QtQuick-Controls-stilon al Breeze por ke ĝi montriĝu en Vindozo. Por ekscii pli, vidu Figuring out main.cpp.

Se vi volas antaŭeniri, vi povas legi pli pri kiel ĉi tiu main.cpp funkcias en Figuring out main.cpp.

Se vi volas vidi kelkajn manierojn pri kiel la C++-kodo povas esti plibonigita, kiel uzi KAboutData por tradukeblaj aplikaĵmetadatumoj, nepre kontrolu nian [KXmlGui-lerniilon](/docs/getting-started /kxmlgui).

Nuntempe, la parto kiu interesas nin estas ĉi tiu linio:

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

La unua argumento estas la URI aro en kirigami-tutorial/src/CMakeLists.txt, kaj la dua argumento estas la nomo de la QML-modulo, kiun ni volas uzi (Main, venante de la nomo de nia Main.qml dosiero, kiu devas komenci per majuskla litero).

La malnova metodo

Vi eble renkontos ĉi tiun alternativan manieron ŝargi QML-dosierojn en reala kodo!

La malnova metodo de ŝargo de QML-dosieroj havis kelkajn malavantaĝojn kaj post Qt6 ĝi iĝis troe devorta:

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

Ĉi tiu Qt-rimedo URI supre sekvas la ŝablonon <resource_prefix><import_URI><optional_QML_dir><file>. Tiuokaze:

rimeda prefikso = defaŭlta / en Qt5, /qt/qml en Qt6
import URI = /org/kde/tutorial, kiu kongruas kun la URI org.kde.tutorial
laŭvola QML dir = /qml, necesa se la QML-dosieroj estas konservitaj en dosierujo nomita qml/
dosiero = la QML-dosiero

Kompilante kaj instalante 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.

Linux aŭ 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"

The program will be installed to $HOME/.local/bin and its desktop entry to $HOME/.local/share/applications.

Vindozo

Se vi kompilas vian projekton en Vindozo post agordi Craft, CMake devus aŭtomate detekti la ĝustan kompililon:

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

Depende de kiel vi instalis la kompililon, vi eble bezonos specifi CMake-Generatoron por la unua paŝo, depende de ĉu vi uzas Visual Studio (msvc) aŭ MinGW (make) por kompili viajn projektojn.

Se Visual Studio, depende de la kompililo kiun vi elektis instali, povus esti:

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

Aŭ:

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

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.

Se vi iam dubas pri la nomo de la kompililo, kiu devus esti uzata en la alvoko cmake, rulu:

cmake -G

Ĝi listigos ĉiujn disponeblajn generatorojn.

Rulante la aplikaĵon

Vi povas tiam ruli la programon kirigami-hello per:

kirigami-hello # En Linukso, permane
kde-builder --run kirigami-hello # With kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # With kdesrc-build
kirigami-hello.exe # Sur Vindozo

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

Ekrankopio de la generita Kirigami-aplikaĵo

Por ruli la novan QML-aplikaĵon en movebla reĝimo, vi povas uzi QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Se vi kompilis la projekton permane per CMake kaj ial vi ŝatus malinstali la projekton, vi povas ruli:

cmake --build build/ --target uninstall

Noto

Venontfoje kiam vi volas krei la necesajn dosierojn kaj dosierujojn, vi povas uzi KAppTemplate aŭ KDevelop por aŭtomate generi taŭgan projekton por komenci. Ili estas haveblaj de la deponejoj de ĉiu grava distribuo. Ĉi tiuj aplikoj ankaŭ generos dosierojn enhavantajn AppStream metadatenojn kaj .desktop dosieron kiu enhavas informojn pri kiel la aplikaĵo. devus esti montrita en linuksa aplika lanĉilo.

Danke al la magio de CMakeLists, vi ankaŭ povas uzi IDEojn kiel KDevelop aŭ QtCreator por disvolvi ĉi tiun aplikaĵon en komforta medio kun minimuma penado.

Klarigante paĝojn