Configurar i com començar

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.
• Construir el Kirigami amb «kdesrc-build»
• 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:

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

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

Si voleu construir el Kirigami amb les Qt6, actualment això no és possible amb només els paquets de la distribució Linux. En el seu lloc haureu de recórrer al «kdesrc-build».

Construcció del Kirigami amb «kdesrc-build»

KDE té una eina personalitzada per a construir fàcilment totes les seves biblioteques i programes: kdesrc-build. Es pot utilitzar per a construir el Kirigami al Linux i al FreeBSD.

Per a aquesta guia d'aprenentatge cal seguir les instruccions de configuració del «kdesrc-build», però fent servir un directori ~/kde5 en el seu lloc, després copiar el fitxer KF5 d'exemple al vostre directori d'inici:

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

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

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

I llavors podeu compilar els projectes del Kirigami en el mateix intèrpret d'ordres del terminal que heu utilitzat per a crear el fitxer de prefix. Si tanqueu el terminal, podeu tornar a crear el fitxer per a compilar la vostra aplicació.

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. L'anomenarem «helloworld».

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

Dins d'aquesta carpeta crearem una carpeta src/ i un fitxer CMakeLists.txt. En general, es considera una bona pràctica posar tots els nostres principals fitxers de codi en una carpeta src/. La nostra carpeta src/, al seu torn, contindrà una carpeta anomenada contents/, la qual conté una carpeta anomenada ui/. Aquí és on crearem els nostres fitxers QML.

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

Aquesta és una convenció del KDE, però no tots els projectes KDE utilitzen aquesta estructura. Podeu configurar les coses de manera diferent, però ho heu de tenir en compte en crear els fitxers CMakeLists.txt i resources.qrc.

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

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

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.

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.

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

main.cpp

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ó.

main.cpp també és 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

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

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ó. Si voleu avançar, podeu llegir més sobre com funciona aquest main.cpp en aquesta pàgina.

resources.qrc

resources.qrc és un fitxer de recursos Qt. Conté la llista de tots els fitxers QML, així com altres fitxers (com les icones personalitzades) que s'inclouran en el binari.

1
2
3
4
5

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

Observeu la línia <file alias="main.qml">contents/ui/main.qml</file>. Detalla quins fitxers QML s'inclouran en el procés de compilació. En el nostre cas, només estem fent servir main.qml, però si haguéssim d'afegir més fitxers QML al nostre codi, hauríem d'assegurar-nos incloure'ls en el fitxer resources.qrc afegint una altra línia com aquesta.

Aquest fitxer de recursos ens permet usar el camí «qrc:» + «/main.qml» en el main.cpp, en lloc de caldre especificar el camí sencer «contents/ui/main.qml».

CMakeLists.txt

Els fitxers CMakeLists.txt són necessaris per a utilitzar el sistema de compilació triat pel KDE, CMake. El fitxer CMakeLists.txt de la carpeta de nivell superior especifica algunes de les 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

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)

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 les Qt i dels Frameworks del KDE es gestionen amb find_package(). Haureu de modificar aquestes línies i incloure qualsevol component addicional que decidiu utilitzar durant el desenvolupament de la vostra aplicació.

L'última línia, add_subdirectory(src), apunta el CMake al directori helloworld/src/, on es troba el nostre codi font. Allà aprofundirem en el fitxer helloworld/src/CMakeLists.txt.

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

Aquest és molt més curt! Repassem el que fa:

• add_executable() crea un executable a partir dels fitxers font donats.
• target_link_libraries() enllaça dinàmicament les biblioteques utilitzades en el nostre codi amb el nostre executable.

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

Compilar i executar 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.

Si esteu executant el vostre projecte en el Linux, haureu d'especificar el lloc on s'instal·larà el programa. Per a fer-ho, necessitem canviar els directoris a la nostra carpeta helloworld/ a l'aplicació de terminal de la nostra elecció i executar les ordres següents:

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

El programa s'instal·larà a ~/kde5/usr/bin.

Si esteu compilant el projecte amb el Craft en el Windows, potser necessitareu especificar un generador de CMake per al primer pas, depenent de si esteu utilitzant el Visual Studio 2019 (msvc) o el MinGW (make) per a compilar els projectes.

Si és Visual Studio:

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

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.

Llavors podeu executar el programa «helloworld» amb:

helloworld # Al Linux
helloworld.exe # Al Windows

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