Configurazione con Python

Prerequisiti

Prima di iniziare, dovremo installare Kirigami e PySide sul nostro computer.

ManjaroArch	sudo pacman -S python-pipx python-pyqt6 pyside6 kirigami flatpak-builder qqc2-desktop-style appstream
OpenSUSE	sudo zypper install python3-pipx python3-qt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style AppStream-compose
Fedora	sudo dnf install pipx python3-pyqt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style appstream-compose

Se utilizzi una distribuzione con vecchi pacchetti PySide6 o PyQt6, questo tutorial funziona con Creazione di software con distrobox.

Struttura del progetto

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

kirigami_python/
├── README.md
├── LICENSE.txt
├── MANIFEST.in                        # Per aggiungere i nostri file QML
├── pyproject.toml                     # Il file principale per gestire il progetto
├── org.kde.kirigami_python.desktop
└── src/
    ├── __init__.py                    # Per importare la directory src/ come pacchetto
    ├── __main__.py                    # Per segnalare l'applicazione come punto di ingresso
    ├── app.py
    └── qml/
        └── Main.qml

Il nome del pacchetto sarà "kirigami_python", l'"eseguibile" (script della console) si chiamerà "kirigami_hello" e il punto di ingresso sarà "app".

Per un progetto più completo che approfondisca ulteriormente questa struttura di file, vedere Progetto completo in Python + Kirigami.

pyproject.toml

Le moderne applicazioni Python necessitano di un solo file TOML per specificare tutti i metadati, le informazioni sui pacchetti e le dipendenze a partire da PEP 621. Quanto segue costituisce un buon punto di partenza per un'applicazione e può essere esteso in seguito.

La maggior parte dei contenuti di questo file sono standard e una versione più completa può essere vista in Python with Kirigami: General Structure.

 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

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "kirigami_python"
version = "0.1"
authors = [
    {name = "Konqi", email = "konqi@example.com"}
]
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
    "Intended Audience :: End Users/Desktop",
    "Topic :: Utilities",
    "Programming Language :: Python",
    "Operating System :: POSIX :: Linux",
]

[project.scripts]
kirigami_hello = "kirigami_python.app:main"

[tool.setuptools]
packages = ["kirigami_python"]
package-dir = {kirigami_python = "src"}
include-package-data = true

[tool.setuptools.data-files]
"share/applications" = ["org.kde.kirigami_python.desktop"]

Nota le linee evidenziate. Come menzionato in Struttura del progetto, il nome del pacchetto è "kirigami_python", il nome dell'eseguibile è "kirigami_hello" e il nome del punto di ingresso è "app". In particolare si segnala quanto segue:

• Lo script del progetto è costituito da uno script entrypoint che verrà generato da setuptools per l'esecuzione dell'applicazione, in questo caso kirigami_hello.
• Lo script del progetto generato kirigami_hello esegue la funzione main() nello script app.py nel pacchetto kirigami_python.
• La "dir-pacchetto" predefinita per i progetti Python è solitamente la directory root. In questo caso, questa viene sostituita dalla sottodirectory src/ quindi funziona come se fosse la directory root del pacchetto.
• La dir-pacchetto è il motivo per cui lo script del progetto generato esegue kirigami_python → app invece di kirigami_python → src → app.
• package-dir è anche il motivo per cui la chiamata importlib.resources.files() in app.py esegue kirigami_python → qml → Main.qml invece di kirigami_python → src → qml → Main.qml.

Vedi Esecuzione diretta, come modulo e come script della console per i dettagli.

org.kde.kirigami_python.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.kirigami_python.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

[Desktop Entry]
Name=Kirigami Tutorial in Python
Name[ca]=Guia d'aprenentatge del Kirigami en Python
Name[eo]=Lernilo pri Kirigami en Python
Name[es]=Tutorial de Kirigami en Python
Name[fr]=Tutoriel pour Kirigami en Python
Name[it]=Esercitazione di Kirigami in Python
Name[nl]=Kirigami handleiding in Python
Name[pt_BR]=Tutorial do Kirigami em Python
Name[ro]=Îndrumar Kirigami în Python
Name[sl]=Učbenik Kirigami v Pythonu
Name[sv]=Kirigami-handledning i Python
Name[tr]=Python ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Python
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

MANIFEST.in

Questo file è semplicemente una dichiarazione di file di codice sorgente aggiuntivi che dovrebbero essere presenti nel pacchetto quando viene eseguita l'applicazione. Python per impostazione predefinita non include file QML nei pacchetti e devono essere disponibili affinché l'applicazione possa essere eseguita.

1

include src/qml/*.qml

src/app.py

 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

#!/usr/bin/env python3

import os
import sys
import signal
from importlib.resources import files

from PySide6.QtGui import QGuiApplication
from PySide6.QtCore import QUrl
from PySide6.QtQml import QQmlApplicationEngine

def main():
    app = QGuiApplication(sys.argv)
    engine = QQmlApplicationEngine()

    """Needed to close the app with Ctrl+C"""
    signal.signal(signal.SIGINT, signal.SIG_DFL)

    """Needed to get proper KDE style outside of Plasma"""
    if not os.environ.get("QT_QUICK_CONTROLS_STYLE"):
        os.environ["QT_QUICK_CONTROLS_STYLE"] = "org.kde.desktop"

    base_path = files('kirigami_python').joinpath('qml', 'Main.qml')
    url = QUrl(f"{base_path}")
    engine.load(url)

    app.exec()

if __name__ == "__main__":
    main()

Poiché si tratta di un'applicazione GUI, vogliamo che la funzione main venga eseguita solo quando viene eseguito lo script, non quando viene importato, quindi abbiamo bisogno della condizione if __name__ == "__main__" alla fine del file. Vedi Esecuzione diretta, come modulo e come script della console per i dettagli.

Creiamo una QGuiApplication e inizializziamo il motore QML, e con QGuiApplication.exec() l'applicazione continuerà a funzionare fino alla chiusura. Quindi importlib.resources.files() prende il percorso di un file presente nel pacchetto, vale a dire il nostro Main.qml. Con questo percorso carichiamo il file QML nel motore QML come punto di ingresso principale per l'interfaccia dell'applicazione.

src/__init__.py

Crea un file kirigami_python/src/__init__.py vuoto. Questo file deve solo essere presente per importare una directory come pacchetto.

touch __init__.py

src/__main__.py

Crea un kirigami_python/src/__main__.py con il seguente contenuto:

1
2
3

from . import app

app.main()

Questo aggiunge semplicemente il contenuto della directory corrente (src/) e lo importa come modulo chiamato app, quindi esegue immediatamente la funzione main() dell'applicazione.

src/qml/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

// 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
    title: "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: "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.

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à title della finestra su "Hello World".

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: "Hello World!".

Esecuzione dell'applicazione

Puoi eseguire lo script della console kirigami_hello senza doverlo prima installare:

pipx run --system-site-packages --spec . kirigami_hello

Il flag --system-site-packages è necessario per consentire a Python di accedere ai pacchetti Python dalla tua distribuzione. Ciò è necessario perché Kirigami e PySide devono essere costruiti sulla stessa versione Qt per funzionare, come nel caso in cui entrambi provengono dalla distribuzione.

Il flag "--spec" determina il percorso del codice sorgente o del pacchetto wheel che contiene il programma e "kirigami_hello" è lo script eseguibile da eseguire.

Per creare e installare il pacchetto Python, esegui:

pipx install --force --system-site-packages .

Il pacchetto verrà installato in "/.local/share/pipx/venvs/kirigami-python" e uno script eseguibile verrà installato in "/.local/bin/kirigami_hello".

Successivamente, l'applicazione può essere avviata eseguendo:

kirigami_hello

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

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

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