Configurar i com començar

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

Instal·lar els paquets necessaris

Abans de començar, hem d’instal·lar algunes coses. Necessitem un compilador C++, els paquets de desenvolupament de les Qt i el Kirigami.

A l’Ubuntu, Debian i Neon podem instal·lar-los amb APT:

sudo apt install build-essential extra-cmake-modules cmake qtbase5-dev qtdeclarative5-dev libqt5svg5-dev qtquickcontrols2-5-dev qml-module-org-kde-kirigami2 kirigami2-dev libkf5i18n-dev gettext libkf5coreaddons-dev qml-module-qtquick-layouts

A les distribucions basades en Arch (com Manjaro) podem emprar Pacman:

sudo pacman -Syu base-devel extra-cmake-modules cmake kirigami2 kde-sdk-meta gettext

Per a la Fedora, emprarem DNF:

sudo dnf groupinstall "Development Tools" "Development Libraries"
sudo dnf install extra-cmake-modules cmake qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtquickcontrols2-devel kf5-kirigami2 kf5-kirigami2-devel kf5-ki18n-devel kf5-kcoreaddons-devel gettext

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

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
    ├── contents
    │   └── ui
    │       └── main.qml
    ├── main.cpp
    └── resources.qrc

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.

Aquesta és la 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
// Includes relevant modules used by the QML
import QtQuick 2.6
import QtQuick.Controls 2.0 as Controls
import QtQuick.Layouts 1.2
import org.kde.kirigami 2.13 as Kirigami

// Base element, provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
    // ID provides unique identifier to reference this element
    id: root

    // Window title
    // i18nc is useful for adding context for translators, also lets strings be changed for different languages
    title: i18nc("@title:window", "Hello World")

    // Initial page to be loaded on app load
    pageStack.initialPage: Kirigami.Page {

        Controls.Label {
            // Center label horizontally and vertically within parent element
            anchors.centerIn: parent
            text: i18n("Hello World!")
        }
    }
}

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

Si coneixeu quelcom 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 importem diversos mòduls importants:

QtQuick, la biblioteca estàndard utilitzada en les aplicacions QML.
QtQuick Controls, la qual proporciona una sèrie de controls estàndard que podem utilitzar perquè les nostres aplicacions siguin interactives.
QtQuick Layouts, la qual proporciona eines per a col·locar els components dins de la finestra de l’aplicació.
El Kirigami, el qual 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 , el qual 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 d’una Kirigami.ApplicationWindow 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” en 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 algun context als equips de traducció que treballen en l’aplicació. És per això que hem inclòs la cadena “@title” abans de “Hello World”.

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. Amb pageStack.initialPage: Kirigami.Page{...} establim la primera pàgina presentada en carregar l’aplicació a una Kirigami.Page, la qual 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 del nostre element pare. En aquest cas, el component principal d’un Controls.Label é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ó. 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
#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argc, char *argv[])
{
    QGuiApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
    QApplication app(argc, argv);
    KLocalizedString::setApplicationDomain("helloworld");
    QCoreApplication::setOrganizationName(QStringLiteral("KDE"));
    QCoreApplication::setOrganizationDomain(QStringLiteral("kde.org"));
    QCoreApplication::setApplicationName(QStringLiteral("Hello World"));

    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 a main.cpp, però la seva funció serà significativament més important una vegada en el futur decidim afegir una funcionalitat més complexa a la nostra aplicació. Si vols tirar endavant, podeu llegir més sobre com funciona aquest main.cpp en aquesta pàgina.

resources.qrc

resources.qrc 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.

Podeu llegir més sobre els detalls de com funciona el sistema de recursos de les Qt en la documentació de les Qt.

CMakeLists.txt

Els fitxers CMakeLists.txt són necessaris per a utilitzar el sistema de compilació triat pel KDE, CMake. El fitxer CMakeLists.txt que hi ha a la nostra 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-la.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
cmake_minimum_required(VERSION 3.16)
project(helloworld)

set(KF_MIN_VERSION "5.68.0")
set(QT_MIN_VERSION "5.12.0")

find_package(ECM ${KF_MIN_VERSION} REQUIRED NO_MODULE)

set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)

find_package(Qt5 ${QT_MIN_VERSION} REQUIRED NO_MODULE COMPONENTS Core Quick Test Gui QuickControls2 Widgets)
find_package(KF5 ${KF_MIN_VERSION} REQUIRED COMPONENTS Kirigami2 I18n CoreAddons)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

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 per 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 CMake al directori src, on es troba el nostre codi font. Allà aprofundirem en el fitxer CMakeLists.txt.

1
2
add_executable(helloworld main.cpp resources.qrc)
target_link_libraries(helloworld Qt5::Quick Qt5::Qml Qt5::Gui Qt5::QuickControls2 Qt5::Widgets KF5::Kirigami2 KF5::I18n)

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

add_executable crea un executable a partir dels fitxers font donats.
target_link_libraries vincula les biblioteques utilitzades en el nostre codi amb el nostre executable.

Nota

Cal tenir present que aquestes biblioteques han de coincidir amb els components que incloem en el nostre fitxer CMakeLists.txt anterior -en cas contrari, aquests components no s’inclouran i la nostra aplicació no compilarà-.

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ó. Per a fer això, hem d’entrar a la carpeta helloworld en la nostra aplicació de terminal i executar l’ordre següent:

cmake -B build/ . && cmake --build build/

I llanceu-la amb:

./build/bin/<project_name>

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

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

Nota

La pròxima vegada que vulgueu crear els fitxers i carpetes necessaris, podreu fer servir KAppTemplate o 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 de Linux.

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

Explicar les pàgines