Jednotka Kirigami

Predpoklady

Pred začiatkom budeme musieť nainštalovať Kirigami a PySide na náš počítač.

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

Ak ste na distribúcii so starými balíkmi PySide6 alebo PyQt6, tento tutoriál funguje s Zostavenie softvéru s distrobox.

Štruktúra projektu

Najprv vytvoríme priečinok nášho projektu (môžete použiť nižšie uvedené príkazy). Náš budeme volať kirigami_python/.

kirigami_python/
├── README.md
├── LICENSE.txt
├── MANIFEST.in                        # Na pridanie našich súborov QML
├── pyproject.toml                     # Hlavný súbor na správu projektu
├── org.kde.kirigami_python.desktop
└── src/
    ├── __init__.py                    # Na import adresára src/ ako balíčka
    ├── __main__.py                    # Na označenie app ako vstupného bodu
    ├── app.py
    └── qml/
        └── Main.qml

Názov balíka bude kirigami_python, "spustiteľný súbor" (konzolový skript) sa bude volať kirigami_hello a vstupný bod bude app.

Pre komplexnejší projekt, ktorý ide do väčších detailov o tejto štruktúre súborov, pozrite Kompletný projekt v Pythone + Kirigami.

pyproject.toml

Moderné aplikácie Python potrebujú iba jeden TOML súbor na špecifikáciu všetkých metadát, informácií o balíku a závislostí od PEP 621. Nasledujúci slúži ako dobrý štartér pre aplikáciu a dá sa neskôr rozšíriť.

Väčšina obsahu v tomto súbore je šablónový a jeho kompletnejšiu verziu nájdete v časti Python s Kirigami: Všeobecná štruktúra.

 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"]

Všimnite si zvýraznené riadky. Ako je uvedené v časti Štruktúra projektu, názov balíka je kirigami_python, názov spustiteľného súboru je kirigami_hello a názov vstupného bodu je app. Konkrétne je potrebné poznamenať nasledovné:

• Skript projektu pozostáva zo vstupného skriptu, ktorý bude vygenerovaný nástrojom setuptools na spustenie aplikácie, v tomto prípade kirigami_hello.
• Vygenerovaný skript projektu kirigami_hello spúšťa funkciu main() v skripte app.py v balíku kirigami_python.
• Predvolený package-dir pre projekty Python je zvyčajne koreňový adresár. V tomto prípade je prepísaný podadresárom src/, takže funguje, akoby bol koreňovým adresárom balíka.
• package-dir je dôvod, prečo vygenerovaný skript projektu robí kirigami_python → app namiesto kirigami_python → src → app.
• package-dir je tiež dôvod, prečo volanie importlib.resources.files() v app.py robí kirigami_python → qml → Main.qml namiesto kirigami_python → src → qml → Main.qml.

Podrobnosti nájdete v časti Spúšťanie priamo, ako modul a ako konzolový skript.

org.kde.kirigami_python.desktop

Primárnym účelom súborov Desktop Entry je zobraziť vašu aplikáciu v spúšťači aplikácií v Linuxe. Ďalším dôvodom mať ich je mať ikony okien na Waylande, pretože sú potrebné na to, aby povedali kompozitoru "toto okno patrí k tejto ikone".

Musí nasledovať schému pomenovania s obráteným DNS s príponou .desktop, ako napríklad org.kde.kirigami_python.desktop:

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

[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[sk]=Tutoriál Kirigami v Pythone
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

Tento súbor je jednoducho deklaráciou dodatočných súborov zdrojového kódu, ktoré by mali byť prítomné v balíku pri spustení aplikácie. Python predvolene nezahŕňa QML súbory do balíkov a musia byť dostupné, aby aplikácia fungovala.

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

Keďže toto je GUI aplikácia, chceme, aby hlavná funkcia bežala iba keď sa skript spúšťa, nie keď sa importuje, takže potrebujeme podmienku if __name__ == "__main__" na konci súboru. Podrobnosti nájdete v časti Spúšťanie priamo, ako modul a ako konzolový skript.

Vytvoríme QGuiApplication a inicializujeme QML engine a pomocou QGuiApplication.exec() bude aplikácia bežať, kým sa nezatvorí. Potom importlib.resources.files() získa cestu k súboru, ktorý je prítomný v balíku, konkrétne náš Main.qml. S touto cestou načítame QML súbor do QML engine ako hlavný vstupný bod pre rozhranie aplikácie.

src/__init__.py

Vytvorte prázdny súbor kirigami_python/src/__init__.py. Tento súbor jednoducho musí byť prítomný, aby bolo možné importovať adresár ako balík.

touch __init__.py

src/__main__.py

Vytvorte kirigami_python/src/__main__.py s nasledujúcim obsahom:

1
2
3

from . import app

app.main()

Toto jednoducho pridá obsah aktuálneho adresára (src/) a importuje ho ako modul s názvom app, potom okamžite spustí funkciu main() aplikácie.

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

Tu budeme spracovávať frontend našej aplikácie.

Ak poznáte trochu Javascript, potom sa vám veľa z QML bude zdať povedomé (aj keď má svoje zvláštnosti). Dokumentácia Qt má rozsiahle množstvo materiálu o tomto jazyku, ak chcete skúsiť niečo na vlastnú päsť. V priebehu týchto tutoriálov sa zameriame veľkú časť pozornosti na náš QML kód, kde môžeme využiť Kirigami na maximum.

Zatiaľ sa zameriame na Main.qml. Najprv importujeme niekoľko dôležitých modulov:

• QtQuick, štandardná knižnica používaná v aplikáciách QML.
• QtQuick Controls, ktorá poskytuje množstvo štandardných ovládacích prvkov, ktoré môžeme použiť na interaktívnosť našich aplikácií.
• QtQuick Layouts, ktorá poskytuje nástroje na umiestňovanie komponentov v rámci okna aplikácie.
• Kirigami, ktorá poskytuje množstvo komponentov vhodných na vytváranie aplikácií fungujúcich na zariadeniach rôznych tvarov a veľkostí.

Potom sa dostávame k nášmu základnému prvku, Kirigami.ApplicationWindow, ktorý poskytuje niektoré základné funkcie potrebné pre všetky aplikácie Kirigami. Toto je okno, ktoré bude obsahovať každú z našich stránok, hlavné sekcie nášho UI.

Potom nastavíme vlastnosť id okna na "root". ID sú užitočné, pretože nám umožňujú jednoznačne odkazovať na komponent, aj keď máme niekoľko rovnakého typu.

Tiež nastavíme vlastnosť title okna na "Hello World".

Potom nastavíme prvú stránku nášho zásobníka stránok. Väčšina aplikácií Kirigami je organizovaná ako zásobník stránok, pričom každá stránka obsahuje súvisiace komponenty vhodné pre konkrétnu úlohu. Zatiaľ to udržujeme jednoduché a zostávame pri jednej stránke. pageStack je pôvodne prázdny zásobník stránok poskytovaný Kirigami.ApplicationWindow a pomocou pageStack.initialPage: Kirigami.Page {...} nastavíme prvú stránku prezentovanú pri načítaní aplikácie na Kirigami.Page. Táto stránka bude obsahovať všetok náš obsah.

Nakoniec zahrnieme na našu stránku Controls.Label, ktorý nám umožní umiestniť text na stránku. Používame anchors.centerIn: parent na vycentrovanie nášho popisku horizontálne a vertikálne v rámci rodičovského prvku. V tomto prípade je rodičovským komponentom nášho popisku Kirigami.Page. Posledná vec, ktorú musíme urobiť, je nastaviť jeho text: text: "Hello World!".

Spustenie aplikácie

Konzolový skript kirigami_hello môžete spustiť bez potreby ho najprv inštalovať:

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

Príznak --system-site-packages je potrebný na to, aby mal Python prístup k balíkom Python z vašej distribúcie. Toto je vyžadované, pretože Kirigami a PySide musia byť zostavené proti rovnakej verzii Qt, aby fungovali, čo je prípad, keď oba pochádzajú z distribúcie.

Príznak --spec určuje cestu k zdrojovému kódu alebo balíku wheel, ktorý obsahuje program, a kirigami_hello je spustiteľný skript, ktorý sa má spustiť.

Na zostavenie a inštaláciu balíčka Python spustite:

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

Balík bude nainštalovaný do ~/.local/share/pipx/venvs/kirigami-python a spustiteľný skript bude nainštalovaný do ~/.local/bin/kirigami_hello.

Potom je možné aplikáciu spustiť spustením:

kirigami_hello

Na spustenie novej QML aplikácie v mobilnom režime môžete použiť QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Voilà! Teraz uvidíte vašu úplne prvú aplikáciu Kirigami priamo pred vašimi očami.