Configurar i com començar

Preparant-nos per a crear la nostra primera aplicació escrita amb el Kirigami

Instal·lació del Kirigami

Abans de començar, haurem d'instal·lar el Kirigami a la nostra màquina. Hi ha tres maneres de fer-ho:

Instal·lar el Kirigami a partir dels repositoris de la vostra distribució Linux
Utilitzar el «kde-builder»
Instal·lar el Kirigami amb el Craft

Instal·lar el Kirigami a partir dels repositoris de la vostra distribució Linux

Necessitem un compilador de C++, els paquets de desenvolupament de les Qt i el Kirigami. Obriu una aplicació de terminal i executeu un dels següents, depenent de quina distribució Linux utilitzeu:

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

Trobareu més informació sobre les altres distribucions aquí.

Utilitzar el «kde-builder»

Configureu l'entorn de desenvolupament amb el «kde-builder». Això us proporcionarà les eines de desenvolupament necessàries i les biblioteques subjacents i construirà els Frameworks de KDE des de zero.

Creeu una carpeta ~/kde/src/kirigami-tutorial. En aquesta carpeta situareu els fitxers de codi font d'aquesta guia d'aprenentatge.

Afegiu el següent al final del vostre ~/.config/kde-builder.yaml:

project kirigami-tutorial:
  no-src: true

⏳ Amb el «kdesrc-build»...

Feu clic aquí per a conèixer com s'ha fet amb el «kdesrc-build»

Aquest pas es feia escrivint a ~/.config/kdesrc-buildrc amb una sintaxi diferent:

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

Instal·lar el Kirigami amb el Craft

KDE té una eina personalitzada per a instal·lar fàcilment la majoria de les seves biblioteques i programes: Craft. Es pot utilitzar per a instal·lar el Kirigami al Linux, el FreeBSD, el Windows, l'Android i el macOS.

Cal seguir les instruccions de configuració per al Craft. Cap al final de la configuració, hauríeu d'executar un fitxer de configuració d'entorn (craftenv.ps1 o craftenv.sh), que us proporcionarà un intèrpret d'ordres de terminal a on compilareu la vostra aplicació Kirigami.

Després d'això, simplement podeu executar el següent en un terminal:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Si tanqueu el terminal, podeu tornar a executar el fitxer de configuració d'entorn per a compilar la vostra aplicació.

Estructura del projecte

Si bé existeixen eines que poden configurar amb facilitat els nostres fitxers, els crearem manualment. Això ens permetrà comprendre millor les peces que compondran la nostra nova aplicació.

Primer crearem la nostra carpeta de projecte (podeu utilitzar les ordres de sota). L'anomenarem kirigami-tutorial/.

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

Dins d'aquesta carpeta crearem una carpeta src/ i un CMakeLists.txt. En general, es considera una bona pràctica posar tots els nostres principals fitxers de codi C++ en una carpeta src/. També hi posarem el fitxer Main.qml ja que s'executarà junt amb l'executable.

Consell

Podeu crear ràpidament aquesta estructura de fitxers amb:

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

Nota

En cas que vulgueu construir automàticament el projecte amb el kde-builder, el nom del mòdul personalitzat hauria de ser el mateix que la carpeta arrel del projecte (en el nostre cas serà «kirigami-tutorial»), en cas contrari hauríeu de personalitzar el source-dir o dest-dir per al mòdul. Assumirem que el camí cap al main.cpp serà $HOME/kde/src/kirigami-tutorial/src/main.cpp.

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

Aquí és on manejarem el frontal de la nostra aplicació.

Si coneixeu alguna cosa de JavaScript, gran part de QML us resultarà familiar (encara que té les seves pròpies peculiaritats). Si teniu ganes de provar alguna cosa pel vostre compte, la documentació de les Qt té una gran quantitat de material sobre aquest llenguatge. Al llarg d'aquestes guies d'aprenentatge, centrarem gran part de la nostra atenció en el codi en QML, on podrem emprar el Kirigami per a aprofitar-lo al màxim.

Per ara, centrem-nos en Main.qml. Primer importarem diversos mòduls importants:

QtQuick, la biblioteca estàndard utilitzada en les aplicacions QML.
QtQuick Controls, que proporciona una sèrie de controls estàndard que podem utilitzar perquè les nostres aplicacions siguin interactives.
QtQuick Layouts, que proporciona eines per a col·locar els components dins de la finestra de l'aplicació.
El Kirigami, que proporciona una sèrie de components adequats per a crear aplicacions que funcionen en dispositius de formes i mides diferents.

Nota

Posar els QtQuick Controls i les importacions del Kirigami en espais de noms separats utilitzant la paraula clau as és una millor pràctica que assegura que cap component amb el mateix nom pugui entrar en conflicte. Podreu trobar diferents noms per als controls QtQuick en els textos, com ara «QQC» o «QQC2». Utilitzarem "Controls" en aquesta guia d'aprenentatge per a més claredat.

Després arribem al nostre element base, la Kirigami.ApplicationWindow, que proporciona algunes característiques bàsiques necessàries per a totes les aplicacions escrites amb el Kirigami. Aquesta és la finestra que contindrà cadascuna de les nostres pàgines, les seccions principals de la nostra interfície d'usuari.

Després, establim la propietat id de la finestra a "root". Els ID són útils perquè ens permeten fer referència de forma única a un component, fins i tot si en tenim diversos del mateix tipus.

També establirem la propietat title de la finestra a "Hello World". Us adonareu que hem embolcallat la nostra cadena "Hello World" amb una funció amb la crida i18nc(), on detallem el context de la cadena, així com la cadena en si.

Nota

Les funcions i18n() fan que la vostra aplicació sigui traduïble amb més facilitat, ja que retornen una versió de la cadena proporcionada en l'idioma de l'usuari (sempre que l'aplicació estigui localitzada per a aquest idioma). Mentre que un usuari anglès pot veure el títol de la finestra com «Hello World», un usuari català veurà «Hola món».

i18nc() construeix la funció i18n() que permet als desenvolupadors proporcionar un context als equips de traducció que treballen en l'aplicació. És per això que hem inclòs la cadena "@title:window" abans de "Hello World". Vegeu la Guia del programador Ki18n per a més detalls.

Després establirem la primera pàgina de la nostra pila de pàgines. La majoria de les aplicacions escrites amb el Kirigami estan organitzades com una pila de pàgines, cada pàgina conté els components relacionats adequats per a una tasca específica. Per ara, el mantenim senzill i ens cenyim a una sola pàgina. pageStack és una pila inicialment buida de pàgines proporcionades per Kirigami.ApplicationWindow, i amb pageStack.initialPage: Kirigami.Page{...} establim la primera pàgina presentada en carregar l'aplicació a una Kirigami.Page. Aquesta pàgina contindrà tot el nostre contingut.

Finalment, incloem en la nostra pàgina un Controls.Label que ens permetrà inserir text a la nostra pàgina. Utilitzarem anchors.centerIn: parent per a centrar la nostra etiqueta horitzontalment i verticalment dins de l'element pare. En aquest cas, el component principal de la nostra etiqueta és Kirigami.Page. L'últim que hem de fer és configurar el text: text: i18n("Hello World!").

org.kde.tutorial.desktop

El propòsit principal dels fitxers Desktop Entry és mostrar la vostra aplicació al llançador d'aplicacions en el Linux. Una altra raó per tenir-los és tenir icones de finestra al Wayland, ja que es requereixen per a dir al compositor «aquesta finestra va amb aquesta icona».

Ha de seguir un esquema de noms DNS invers seguit de l'extensió .desktop com ara 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

Nota

Les icones de les finestres i de la barra de tasques només funcionaran en una sessió del Wayland si els fitxers «desktop» de les aplicacions es col·loquen a ~/.local/share/applications o /usr/share/applications. Per a aconseguir icones que funcionin en aquesta guia d'aprenentatge, copieu el fitxer «desktop» de l'aplicació o canvieu a una sessió de desenvolupament com s'indica en la guia d'aprenentatge del «kde-builder». Algunes aplicacions de KDE podrien tenir icones funcionant si ja estaven instal·lades al sistema.

CMakeLists.txt

Els fitxers CMakeLists.txt són necessaris per a utilitzar el sistema de compilació triat pel KDE, CMake. El fitxer kirigami-tutorial/CMakeLists.txt especifica algunes característiques de la nostra aplicació. També inclou algunes de les dependències que necessitem per a compilar el projecte.

 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)

El CMakeLists.txt defineix com construir els vostres projectes. La major part del seu contingut només és per a arrencar el vostre projecte. Aquí podeu llegir una explicació detallada línia a línia del que fa aquest fitxer CMakeLists.

El més important a tenir en compte és que les dependències de construcció C++ de les Qt i dels Frameworks de KDE es gestionen amb find_package() i les dependències en temps d'execució del QML es gestionen amb ecm_find_qml_module(). Haureu de modificar aquestes línies i incloure qualsevol component addicional que decidiu utilitzar durant el desenvolupament de la vostra aplicació.

La línia amb add_subdirectory(src), apunta el CMake al directori kirigami-tutorial/src/, on es troba el nostre codi font.

La línia amb install() indica al CMake on instal·lar el fitxer «desktop».

Aprofundim en el fitxer 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})

Aquest fitxer consta de cinc passos:

crea un executable
canvia l'executable a un mòdul QML que accepta fitxers QML
afegeix fitxers C++ i QML a l'executable
enllaça les biblioteques necessàries perquè s'executi l'executable
instal·la l'executable al lloc correcte

La pròxima vegada haureu d'afegir més fitxers en QML, afegir-los a la crida existent ecm_target_qml_sources(). Els fitxers C++ que utilitzen la paraula clau QML_ELEMENT que veurem més endavant a la guia d'aprenentatge es poden afegir utilitzant target_sources().

Ara que ens hem revisat el CMake, vegem els fitxers als quals dedicarem la major part del nostre temps de treball.

main.cpp

El fitxer kirigami-tutorial/src/main.cpp gestiona la «lògica empresarial» de la nostra aplicació. El C++ és útil perquè és flexible i ràpid, encara que és més complicat que altres llenguatges de programació.

També funciona com el punt d'entrada a la nostra aplicació. Les dues parts del nostre projecte, el dorsal i la interfície d'usuari, ambdós es configuren i s'inicien aquí.

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

Per ara, no necessitem entrar en massa detalls sobre el que fa el nostre codi de main.cpp, però la seva funció serà significativament més important una vegada en el futur decidim afegir una funcionalitat més complexa a l'aplicació.

Temes al Windows

Feu clic aquí per a llegir-ne més

L'aplicació ha d'establir el seu estil de tema d'icones, QStyle i QtQuick Controls a Brisa per tal de mostrar-se al Windows. Per a saber-ne més, vegeu Descobrir el main.cpp.

Si voleu avançar, podeu llegir més sobre com funciona aquest main.cpp a Descobrir el main.cpp.

Si voleu veure algunes maneres de millorar el codi C++, com ara utilitzar el KAboutData per a les metadades d'aplicació traduïbles, reviseu la Guia d'aprenentatge del KXmlGui.

De moment, la part que ens interessa és aquesta línia:

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

El primer argument és l'URI establert a kirigami-tutorial/src/CMakeLists.txt, i el segon argument és el nom del mòdul QML que volem utilitzar (Main), que prové del nom del nostre fitxer Main.qml, el qual ha de començar amb una lletra en majúscula).

El mètode antic

Podeu trobar aquesta manera alternativa de carregar fitxers QML en codi real!

El mètode antic de càrrega de fitxers QML tenia alguns inconvenients i després de les Qt6 es va tornar excessivament detallat a la sortida:

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

Aquest UR del recurs Qt segueix el patró <resource_prefix><import_URI><optional_QML_dir><file>. En aquest cas:

resource prefix = predeterminat / a Qt5, /qt/qml a Qt6
import URI = /org/kde/tutorial, que coincideix amb l'URI org.kde.tutorial
optional QML dir = /qml, necessari si els fitxers QML s'emmagatzemen en un directori anomenat qml/
file = el fitxer QML

Compilar i instal·lar l'aplicació

Estem gairebé a la línia de meta. L'últim que hem de fer és construir i compilar la nostra aplicació. Fer això dependrà de la plataforma en la qual estem.

Linux o FreeBSD

Compilar amb el «kde-builder»

Assegureu-vos que heu seguit les instruccions d'Utilitzar el «kde-builder».

Compileu les dependències de construcció necessàries amb el «kde-builder», després compileu kirigami-tutorial executant les ordres següents en un terminal:

kde-builder kirigami ki18n kcoreaddons breeze kiconthemes qqc2-desktop-style
kde-builder kirigami-tutorial

Compilar manualment

Canvieu els directoris a la carpeta arrel del projecte i executeu l'ordre següent en un terminal:

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

El programa s'instal·larà a $HOME/.local/bin i la seva entrada «desktop» a $HOME/.local/share/applications.

Windows

Si esteu compilant el projecte al Windows després d'haver configurat Craft, el CMake hauria de detectar automàticament el compilador correcte:

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

En funció de com heu instal·lat el compilador, potser caldrà especificar un generador de CMake per al primer pas, depenent de si esteu utilitzant el Visual Studio (msvc) o el MinGW (make) per a compilar els projectes.

Si és Visual Studio, depenent del compilador que trieu instal·lar, podria ser:

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

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

Si és MinGW:

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

En els dos casos, el programa s'instal·larà a C:\CraftRoot\bin.

Si alguna vegada dubteu sobre el nom del compilador que s'ha d'utilitzar en la crida del cmake, executeu:

cmake -G

Llistarà tots els generadors disponibles.

Executar l'aplicació

Llavors podeu executar el programa kirigami-hello amb:

kirigami-hello # Al Linux, manualment
kde-builder --run kirigami-hello # Amb el «kde-builder»
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # Amb el «kdesrc-build»
kirigami-hello.exe # Al Windows

Heus aquí! Ara veureu aparèixer la vostra primera aplicació escrita amb el Kirigami.

Captura de pantalla de l'aplicació generada amb el Kirigami

Per a executar la nova aplicació QML en mode de mòbil, podeu utilitzar QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Si heu compilat el projecte manualment amb el CMake i per algun motiu voleu desinstal·lar el projecte, podeu executar:

cmake --build build/ --target uninstall

Nota

La pròxima vegada que vulgueu crear els fitxers i carpetes necessaris, podreu fer servir KAppTemplate o el KDevelop per a generar automàticament un projecte adequat per a començar. Estan disponibles en els repositoris de cada distribució. Aquestes aplicacions també generaran els fitxers que contenen les metadades d'AppStream i un fitxer .desktop que conté la informació sobre com s'ha de mostrar l'aplicació en un llançador d'aplicacions del Linux.

Gràcies a la màgia de CMakeLists, també podreu utilitzar un IDE com el KDevelop o el QtCreator per a desenvolupar aquesta aplicació dins d'un entorn còmode, amb un esforç mínim.

Explicar les pàgines