Configurazione con C++

Crea la tua prima applicazione Kirigami con C++

Installazione di Kirigami

Prima di iniziare, dovremo installare Kirigami sulla nostra macchina. Ci sono tre modi per farlo:

Installazione di Kirigami dai depositi della tua distribuzione
Uso di kde-builder
Installazione di Kirigami con Craft

Se utilizzi una distribuzione sufficientemente aggiornata come Debian Testing, l'ultima versione di Ubuntu non LTS, Fedora, openSUSE Tumbleweed o Arch, puoi installare Kirigami dalla tua distribuzione.

Se utilizzi una distribuzione non aggiornata come Debian Stable o LTS Ubuntu, dovresti usare kde-builder per questo tutorial. Dovrebbe utilizzare al massimo 2 GB di spazio di archiviazione.

Installazione di Kirigami dai depositi della tua distribuzione

Abbiamo bisogno di un compilatore C++, pacchetti di sviluppo Qt e Kirigami. Apri un'applicazione terminale ed esegui una delle seguenti operazioni, a seconda della distribuzione Linux che stai utilizzando:

Kubuntu KDE Neon	sudo apt install build-essential cmake extra-cmake-modules libkirigami-dev libkf6i18n-dev libkf6coreaddons-dev libkf6iconthemes-dev qt6-base-dev qt6-declarative-dev libkf6qqc2desktopstyle-dev
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 install @development-tools @development-libs 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

Ulteriori informazioni per altre distribuzioni sono disponibili in Installazione delle dipendenze di build.

Usare kde-builder

Configura il tuo ambiente di sviluppo con kde-builder. Ciò ti fornirà gli strumenti di sviluppo necessari e le librerie sottostanti e creerà i framework KDE da zero.

Crea una cartella ~/kde/src/kirigami-tutorial. In quella cartella inserirai i file del codice sorgente di questo tutorial.

Aggiungere quanto segue alla fine di ~/.config/kde-builder.yaml:

project kirigami-tutorial:
  no-src: true

⏳ Con kdesrc-build...

Fai clic qui per sapere come è stato fatto con kdesrc-build

Questo passaggio veniva eseguito scrivendo in ~/.config/kdesrc-buildrc invece con una sintassi diversa:

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

Installazione di Kirigami con Craft

KDE dispone di uno strumento personalizzato per installare facilmente la maggior parte delle sue librerie e programmi: Craft. Può essere utilizzato per installare Kirigami su Windows, Android e macOS.

Sebbene Craft sia disponibile anche per Linux e FreeBSD, la sua destinazione d'uso è solo per AppImage e pacchetti.

Dovrai seguire le istruzioni di configurazione per Craft. Alla fine della configurazione, dovresti aver eseguito un file di configurazione dell'ambiente (craftenv.ps1 su Windows o craftenv.sh su tutte le altre piattaforme), che ti fornirà una shell terminale in cui compilerai la tua applicazione Kirigami.

Successivamente, puoi eseguire quanto segue su un terminale:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Ci vorrà del tempo per finire alla prima esecuzione. Se chiudi il terminale, puoi eseguire il file di configurazione dell'ambiente per preparare nuovamente il terminale.

Struttura del progetto

Sebbene esistano degli strumenti che possono impostare facilmente i file, li creeremo manualmente. Questo ci consentirà di capire meglio tutti i pezzi che costituiranno la nostra nuova applicazione.

Per prima cosa creiamo la cartella del nostro progetto (puoi utilizzare i comandi seguenti). Chiameremo il nostro "kirigami-tutorial/".

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

All'interno di questa cartella creeremo una cartella src/ e CMakeLists.txt. Generalmente è considerata una buona pratica posizionare tutti i nostri principali file di codice C++ in una cartella src/. Inseriamo anche il file Main.qml poiché verrà eseguito insieme all'eseguibile.

Suggerimento

Puoi creare rapidamente questa struttura di file con:

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

Nel caso in cui desideri creare automaticamente il progetto con kde-builder, il nome del modulo personalizzato dovrebbe essere lo stesso della cartella radice del progetto (nel nostro caso sarà "kirigami-tutorial"), altrimenti dovresti personalizzare la dir-origine o la dir-dest per il modulo. Supponiamo che il percorso del tuo main.cpp sia ~/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!")
        }
    }
}

Ecco dove gestiremo l'interfaccia della nostra applicazione.

Se conosci un po' di Javascript, allora la gran parte di QML ti sembrerà familiare (sebbene abbia delle sue caratteristiche proprie)). Se hai voglia di provare a fare qualcosa da solo la documentazione di Qt ha un'ampia quantità di materiale su questo linguaggio. In queste esercitazioni focalizzeremo la nostra attenzione principalmente sul codice QML, nel quale possiamo utilizzare Kirigami per ottenerne il massimo.

Per ora concentriamoci su Main.qml. Per prima cosa importiamo una serie di moduli importanti:

QtQuick, la libreria standard utilizzata nelle applicazioni QML.
QtQuick Controls, che fornisce una serie di controlli standard che possiamo utilizzare per rendere interattive le nostre applicazioni.
QtQuick Layouts, che fornisce strumenti per posizionare i componenti all'interno della finestra dell'applicazione.
Kirigami, che fornisce una serie di componenti adatti per creare applicazioni che funzionano su dispositivi di diverse forme e dimensioni.

Nota

Mettere i controlli QtQuick e le importazioni Kirigami in spazi dei nomi separati utilizzando la parola chiave "as" è una best practice che garantisce che nessun componente con lo stesso nome possa entrare in conflitto. Potresti vedere nomi diversi per i controlli QtQuick in natura, come "QQC" o "QQC2". Utilizzeremo i "Controlli" in questo tutorial per chiarezza.

Arriviamo quindi al nostro elemento di base, Kirigami.ApplicationWindow, che fornisce alcune funzionalità di base necessarie per tutte le applicazioni Kirigami. Questa è la finestra che conterrà ciascuna delle nostre pagine, le sezioni principali della nostra UI.

Successivamente impostiamo la proprietà id della finestra su "root". Gli ID sono utili perché ci consentono di fare riferimento in modo univoco a un componente, anche se ne abbiamo diversi dello stesso tipo.

Impostiamo anche la proprietà della finestra title su "Hello World". Noterai che abbiamo racchiuso la nostra stringa "Hello World" in una funzione chiamata i18nc(), dove dettagliamo il contesto della stringa così come la stringa stessa.

Nota

Le funzioni i18n() rendono la tua app più facilmente traducibile, poiché restituiscono una versione della stringa fornita nella lingua dell'utente (a condizione che la tua app sia stata localizzata per quella lingua). Mentre un utente inglese potrebbe vedere il titolo della nostra finestra come "Hello World", un utente spagnolo vedrebbe "Hola Mundo".

i18nc() si basa sulla funzione i18n() consentendo agli sviluppatori di fornire contesto ai traduttori che lavorano sull'applicazione. Qui chiariamo che il componente dell'interfaccia utente è il titolo della finestra dell'applicazione, quindi abbiamo incluso la stringa "@title:window" prima di "Hello World". Consulta la Guida per programmatori Ki18n per maggiori dettagli.

Impostiamo quindi la prima pagina del nostro stack di pagine. La maggior parte delle applicazioni Kirigami sono organizzate come una pila di pagine, ciascuna pagina contenente componenti correlati adatti a un'attività specifica. Per ora, manteniamo le cose semplici e ci atteniamo a una singola pagina. pageStack è una pila di pagine inizialmente vuota fornita da Kirigami.ApplicationWindow, e con pageStack.initialPage: Kirigami.Page {...} impostiamo la prima pagina presentata dopo aver caricato l'applicazione su una Kirigami.Page. Questa pagina conterrà tutti i nostri contenuti.

Infine, includiamo nella nostra pagina un Controls.Label che ci consente di inserire del testo nella nostra pagina. Usiamo anchors.centerIn: parent per centrare la nostra etichetta orizzontalmente e verticalmente all'interno del nostro elemento genitore. In questo caso, il componente principale della nostra etichetta è Kirigami.Page. L'ultima cosa che dobbiamo fare è impostarne il testo: text: i18n("Hello World!").

org.kde.tutorial.desktop

Lo scopo principale dei file Desktop Entry è mostrare la tua app nell'avviatore applicazioni su Linux. Un altro motivo per averli è avere le icone delle finestre su Wayland, poiché sono necessarie per dire al compositore "questa finestra va con questa icona".

Deve seguire uno schema di denominazione DNS inverso seguito dall'estensione .desktop come org.kde.tutorial.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
[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[pt_BR]=Tutorial do Kirigami
Name[ro]=Îndrumar Kirigami
Name[sl]=Učbenik Kirigami
Name[sv]=Kirigami-handledning
Name[tr]=Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami
Name[zh_TW]=Kirigami 教學
Exec=kirigami-hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

Nota

Le icone della finestra e della barra delle applicazioni funzioneranno in una sessione Wayland solo se i file desktop delle app sono posizionati in "~/.local/share/applications" o "/usr/share/applications". Per far funzionare le icone in questo tutorial, copia lì il file desktop dell'applicazione o passa a una sessione di sviluppo come indicato nel tutorial su kde-builder. Alcune applicazioni KDE potrebbero avere icone funzionanti se fossero già installate nel sistema.

CMakeLists.txt

I file "CMakeLists.txt" sono necessari per utilizzare il sistema di compilazione scelto da KDE, CMake. Il nostro file kirigami-tutorial/CMakeLists.txt specificherà alcune delle caratteristiche della nostra applicazione. Include anche alcune delle dipendenze di cui abbiamo bisogno per compilare il nostro progetto.

 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)

Il file CMakeLists.txt definisce come costruire i tuoi progetti. La maggior parte del contenuto qui serve solo per avviare il tuo progetto. Puoi leggere una spiegazione approfondita riga per riga di ciò che fa questo file CMakeLists qui.

La cosa più importante da tenere a mente è che le dipendenze di build C++ di Qt e KDE Frameworks sono gestite con find_package() e le dipendenze di runtime QML sono gestite con ecm_find_qml_module(). Dovrai modificare queste righe e includere eventuali componenti aggiuntivi che deciderai di utilizzare durante lo sviluppo della tua applicazione.

La riga con add_subdirectory(src) punta CMake alla directory kirigami-tutorial/src/, dove si trova il nostro codice sorgente.

La riga con install() indica a CMake dove installare il file desktop.

Esaminiamo il file kirigami-tutorial/src/CMakeLists.txt lì dentro.

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

Questo file è composto da cinque passaggi:

crea un eseguibile
modificare l'eseguibile in un modulo QML che accetta file QML
aggiungere file C++ e QML all'eseguibile
collegare le librerie necessarie per l'esecuzione dell'eseguibile
installare l'eseguibile nel posto giusto

La prossima volta che avrai bisogno di aggiungere altri file QML, aggiungili alla chiamata ecm_target_qml_sources() esistente. I file C++ che utilizzano la parola chiave QML_ELEMENT che vedremo più avanti nel tutorial possono essere aggiunti utilizzando target_sources().

Ora che CMake se n'è preso cura, vediamo i file su cui lavoreremo di più.

main.cpp

Il file kirigami-tutorial/src/main.cpp gestisce la "logica di business" della nostra applicazione. Il C++ è utile perché è flessibile e veloce, anche se è più complicato rispetto ad altri linguaggi di programmazione.

Funziona anche come punto di accesso alla nostra applicazione. Le due parti del nostro progetto, il backend e l'interfaccia utente, sono entrambe impostate e avviate qui.

 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 ora, non abbiamo bisogno di entrare troppo nei dettagli su cosa fa il nostro codice main.cpp, ma il suo ruolo diventerà molto più importante una volta che decideremo di aggiungere funzionalità più complesse alla nostra applicazione in futuro.

Temi su Windows

Fai clic qui per leggere di più

L'applicazione deve impostare il tema delle icone, QStyle e lo stile dei controlli QtQuick su Breeze per poter essere visualizzato su Windows. Per ulteriori informazioni, vedere Capire main.cpp.

Se vuoi andare avanti, puoi leggere di più su come funziona questo main.cpp in Capire main.cpp.

Se vuoi vedere alcuni modi su come migliorare il codice C++, come usare KAboutData per metadati dell'applicazione traducibili, assicurati di controllare il nostro tutorial KXmlGui.

Per ora la parte che ci interessa è questa riga:

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

Il primo argomento è l'URI impostato in kirigami-tutorial/src/CMakeLists.txt e il secondo argomento è il nome del modulo QML che vogliamo utilizzare ("Main, derivante dal nome del nostro file Main.qml`, che deve iniziare con una lettera maiuscola).

Il vecchio metodo

Potresti incontrare questo modo alternativo per caricare file QML in codice reale!

Il vecchio metodo di caricamento dei file QML presentava alcuni svantaggi e dopo Qt6 diventava eccessivamente prolisso:

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

Questo URI risorsa Qt sopra segue il modello "<resource_prefix><import_URI><optional_QML_dir>". In questo caso:

prefisso risorsa = predefinito / in Qt5, /qt/qml in Qt6
import URI = /org/kde/tutorial, che corrisponde all'URI org.kde.tutorial
opzionale QML dir = /qml, necessario se i file QML sono archiviati in una directory chiamata qml/
file = il file QML

Compilazione ed installazione dell'applicazione

Siamo quasi al traguardo. L'ultima cosa che dobbiamo fare è creare ed eseguire la nostra applicazione. Ciò dipenderà dalla piattaforma su cui ti trovi.

Linux o FreeBSD

Compilazione con kde-builder

Assicurati di aver seguito le istruzioni in Utilizzo di kde-builder.

Compila le dipendenze di compilazione necessarie con kde-builder, quindi compila kirigami-tutorial eseguendo i seguenti comandi in un terminale:

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

Compilazione manuale

Passa alle directory della cartella principale del progetto, quindi esegui il seguente comando in un terminale:

cmake -B build/ --install-prefix ~/.local
cmake --build build/
cmake --install build/

Il programma verrà installato in "~~/.local/bin" e la sua voce sul desktop in "~~/.local/share/applications".

Windows

Se stai compilando il tuo progetto su Windows dopo aver impostato Craft, CMake dovrebbe rilevare automaticamente il compilatore giusto:

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

A seconda di come hai installato il compilatore, potresti dover specificare un generatore CMake per il primo passaggio, a seconda che tu stia utilizzando Visual Studio (msvc) o MinGW (make) per compilare i tuoi progetti.

Se Visual Studio, a seconda del compilatore che hai scelto di installare, potrebbe essere:

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

Oppure:

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

Se MinGW:

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

In entrambi i casi, il programma verrà installato in C:\CraftRoot\bin.

Se hai dubbi sul nome del compilatore da utilizzare nella chiamata cmake, esegui:

cmake -G

Elencherà tutti i generatori disponibili.

Esecuzione dell'applicazione

Puoi avviare il programma kirigami-hello con:

kirigami-hello # Su Linux, manualmente
kde-builder --run kirigami-hello # Con kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # Con kdesrc-build
kirigami-hello.exe # In Windows

Voilà! Ora vedrai la tua primissima app Kirigami apparire davanti ai tuoi occhi.

Schermata dell'applicazione in Kirigami generata

Per eseguire la nuova applicazione QML in modalità mobile, puoi utilizzare QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Se hai compilato manualmente il progetto con CMake e per qualche motivo desideri disinstallare il progetto, puoi eseguire:

cmake --build build/ --target uninstall

Nota

La prossima volta che desideri creare i file e le cartelle necessari, puoi utilizzare KAppTemplate o KDevelop per generare automaticamente un progetto adatto da cui iniziare. Sono disponibili nei repository di ciascuna delle principali distribuzioni. Queste applicazioni genereranno anche file contenenti metadati AppStream e un file .desktop che contiene informazioni su come l'applicazione dovrebbe essere visualizzata in un launcher di applicazioni Linux.

Grazie alla magia di CMakeLists, puoi anche utilizzare IDE come KDevelop o QtCreator per sviluppare questa applicazione in un ambiente confortevole con il minimo sforzo.

Configurazione con Python