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.

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
ManjaroArch
sudo pacman -S base-devel extra-cmake-modules cmake qt5-base qt5-declarative qt5-quickcontrols2 kirigami2 ki18n kcoreaddons breeze
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-breeze-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-breeze-style

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
    ├── 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.

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 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 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
#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argc, char *argv[])
{
    QCoreApplication::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 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
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 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
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:

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/ amb l'aplicació de terminal i executar les ordres següents:

cmake -B build/
cmake --build build/

I llanceu-la amb:

./build/bin/helloworld

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

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