Kirigami s Pytonom

Predpogoji

Preden začnemo, bomo morali namestiti Kirigami in PySide na naš računalnik.

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

Če uporabljate distribucijo s starimi paketi PySide6 ali PyQt6, ta vadnica deluje z Building software with distrobox.

Struktura projekta

Najprej ustvarimo našo projektno mapo (uporabite lahko spodnje ukaze). Našo vadnico bomo imenovali kirigami_python/.

kirigami_python/
├── README.md
├── LICENSE.txt
├── MANIFEST.in                        # Za dodajanje naših datotek QML
├── pyproject.toml                     # Glavna datoteka za upravljanje projekta
├── org.kde.kirigami_python.desktop
└── src/
    ├── __init__.py                    # Za uvoz imenika src/ kot paket
    ├── __main__.py                    # Za signalizacijo aplikacije kot vstopne točke
    ├── app.py
    └── qml/
        └── Main.qml

Ime paketa bo kirigami_python, "izvršljiva datoteka" (konzolni skript) se bo imenovala kirigami_hello, in vstopna točka bo app.

Za bolj obsežen projekt, ki gre v nadaljnje podrobnosti s to strukturo datoteke, glejte Celoten projekt v Python + Kirigami.

pyproject.toml

Sodobne aplikacije Python potrebujejo samo eno datoteko TOML, da določijo vsemetapodatke, informacije o paketu in odvisnosti od PEP 621. Naslednje služi kot dober začetek za aplikacijo in se lahko kasneje podaljša.

Večina vsebine v tej datoteki je okvirna in njeno bolj popolno različico si lahko ogledate v 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"]

Upoštevajte osvetljene vrstice. Kot je navedeno pod Project structure, je ime paketa je kirigami_python,ime izvršljive datoteke je kirigami_hello, ime vstopne točke je app. Zlasti je treba opozoriti na naslednje:

• Projektni skript je sestavljen iz skripta vstopne točke, ki bo ustvarjens setuptools za zagon aplikacije, v tem primeru kirigami_hello.
• Ustvarjeni projektni skript kirigami_hello zažene funkcijo main() v skriptu app.py v paketu kirigami_python.
• Privzeti package-dir za projekte v Pythonu je običajno korenski imenik.V tem primeru je to preglašeno s podimenikom src/, tako da deluje, kot da je korenski imenik paketa.
• package-dir je razlog, zakaj ustvarjeni skript projekta deluje kot kirigami_python→ app namesto kirigami_python → src → app.
• package-dir je tudi razlog, zakaj klic importlib.resources.files() v app.py deluje kot kirigami_python → qml → Main.qml namesto kot kirigami_python → src → qml → Main.qml.

Glejte Running directly, as a module, and as a console script za podrobnosti.

org.kde.kirigami_python.desktop

Glavni namen datotek za vnos na namizje je prikaz vaše aplikacije v zaganjalniku aplikacij v Linuxu. Drug razlog za njihovo uporabo so ikone oken v Waylandu, saj morajo sestavljalcu sporočiti, da »to okno spada k tej ikoni«.

Slediti mora shemi poimenovanja obratne DNS - reverse-DNS naming scheme, ki mu sledi končnica .desktop, kot je npr.org.kde.kirigami_python.desktop:

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

[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[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

Ta datoteka je preprosto deklaracija dodatnih datotek izvorne kode, kimora biti prisoten v paketu, ko se aplikacija izvaja. Privzeto Python ne vključuje datotek QML v paketih in morajo biti na voljo da se aplikacija izvaja.

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

Ker je to aplikacija GUI, želimo, da se glavna funkcija izvaja samo, ko se izvaja skript in ne, ko je uvožen, zato potrebujemo pogoj if __name__ == "__main__" na koncu datoteke. Glejte [Tek neposredno kot modul in kot konzolni skript - Running directly, as a module, and as a console script(/docs/getting-started/python/python-package#running-directly-as-a-module-and-as-a-console-script) za podrobnosti.

Ustvarimo aplikacijo QGuiApplication in inicializiramo stroj QML ter zQGuiApplication.exec() aplikacija bo delovala, dokler se ne zapre.Nato importlib.resources.files() zagrabi pot do datoteke, ki je prisotnav paketu namreč našo Main.qml. S to potjo naložimo datoteko QMLv stroj QML kot glavno vstopno točko za aplikacijski vmesnik.

src/__init__.py

Ustvarite prazno datoteko kirigami_python/src/__init__.py. Ta datoteka mora biti samo prisotna, da lahko uvozite imenik kot paket.

touch __init__.py

src/__main__.py

Ustvarite kirigami_python/src/__main__.py z naslednjo vsebino:

1
2
3

from . import app

app.main()

To preprosto doda vsebino trenutnega imenika (src/) in jo uvozikot modul z imenom app, nato takoj zažene funkcijo main() aplikacije.

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

Tukaj bomo delali na ospredju naše aplikacije.

Če poznate nekaj Javascripta, se vam bo večina QML zdela znana (čeprav ima svoje posebnosti). Dokumentacija Qt vsebuje obsežno količino gradiva o tem jeziku, če želite nekaj poskusiti sami. Med temi učbenki bomo veliko pozornosti namenili naši kodi QML, kjer lahko uporabimo Kirigami, da ga kar najbolje izkoristimo.

Za zdaj se osredotočimo na Main.qml. Najprej uvozimo številne pomembne module:

• QtQuick je standardna knjižnica, ki se uporablja v aplikacijah QML.
• QtQuick Controls, ki zagotavlja številne standardne kontrole, s katerimi lahko naše aplikacije naredimo interaktivne.
• QtQuick Layouts, ki ponuja orodja za postavitev komponent v okno aplikacij.
• Kirigami, ki zagotavlja številne komponente primerne za ustvarjanje aplikacij, ki delujejo po napravah različnih oblik in velikosti.

Nato pridemo do našega osnovnega elementa 'Kirigami.ApplicationWindow', ki zagotavlja nekaj osnovnih funkcij, ki so potrebne za vse Kirigami aplikacije. To je okno, ki bo vsebovalo vsako od naših strani, glavne odseke našega uporabniškega vmesnika.

Nato določimo lastnost okna določilnik 'id' na 'root'. Določilniki so uporabni, ker nam dovolijo edinstveno sklicevanje na komponento, tudi če jih imamo več iste vrste.

Nastavili smo tudi lastnost okna title na "Hello World".

Nato nastavimo prvo stran našega sklada strani. Večina aplikacij Kirigami je organiziranih kot sklad strani, pri čemer vsaka stran vsebuje povezane komponente, primerne za določeno nalogo. Zaenkrat bomo ohranili preprostost in se držali ene same strani. pageStack je začetno prazen sklad strani, ki ga zagotavlja Kirigami.ApplicationWindow, in z pageStack.initialPage: Kirigami.Page {...} nastavimo prvo stran, ki se prikaže ob nalaganju aplikacije, na Kirigami.Page. Ta stran bo vsebovala vso našo vsebino.

Na koncu na naši strani vključimo v Controls.Label, ki nam dovoli, da besedilo postavimo na našo stran. Uporabljamo 'anchors.centerIn: parent' za centriranje naše oznake vodoravno in navpično znotraj našega nadrejenega elementa. V tem primeru je nadrejena komponenta oznake stran Kirigami.Page. Zadnja stvar, ki jo moramo storiti je, da nastavimo besedilo: text: "Hello World!".

Zagon aplikacije

Konzolni skript kirigami_hello lahko zaženete, ne da bi vam ga bilo treba najprej namestiti:

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

Zastavica --system-site-packages je potrebna, da ima Python dostop do paketov Pythona iz vaše distribucije. To je potrebno, ker morata biti Kirigami in PySide zgrajena na isti različici Qt, da bi delovalo, kar oboje velja takrat, ko oba prihajata iz distribucije.

Zastavica --spec določa pot do izvorne kode ali kolesnega paketa, ki ima program, kirigami_hello pa je izvršljivi skript, ki naj bi tekel.

Za izgradnjo in namestitev Pythonovega paketa, zaženite:

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

Paket bo nameščen v ~/.local/share/pipx/venvs/kirigami-python in izvajalni skript bo nameščen v ~/.local/bin/kirigami_hello.

Po tem lahko aplikacijo startate tako, da zaženete:

kirigami_hello

Za zagon nove aplikacije QML v mobilnem načinu lahko uporabite QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Voilà! Zdaj boste videli, da se vaša prva Kirigami aplikacija pojavi pred vašimi očmi.