الإعداد مع بايثون

المتطلبات الأساسية

قبل البدء، سنحتاج إلى تثبيت Kirigami وPySide على جهازنا.

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

إذا كنت على توزيعة بحزم PySide6 أو PyQt6 قديمة، فهذا الدليل يعمل مع بناء البرمجيات باستخدام distrobox.

هيكل المشروع

أولاً ننشئ مجلد مشروعنا (يمكنك استخدام الأوامر أدناه). سنسمي مجلدنا kirigami_python/.

kirigami_python/
├── README.md
├── LICENSE.txt
├── MANIFEST.in                        # لإضافة ملفات QML الخاصة بنا
├── pyproject.toml                     # الملف الرئيسي لإدارة المشروع
├── org.kde.kirigami_python.desktop
└── src/
    ├── __init__.py                    # لاستيراد دليل src/ كحزمة
    ├── __main__.py                    # لتحديد التطبيق كنقطة دخول
    ├── app.py
    └── qml/
        └── Main.qml

اسم الحزمة سيكون kirigami_python، والملف التنفيذي (سكريبت وحدة التحكم) سيُسمى kirigami_hello، ونقطة الدخول ستكون app.

لمشروع أكثر شمولاً يتناول تفاصيل إضافية عن هيكل الملفات هذا، انظر المشروع الكامل بلغة بايثون + كيريغامي.

pyproject.toml

تطبيقات بايثون الحديثة تحتاج فقط إلى ملف TOML واحد لتحديد جميع البيانات الوصفية ومعلومات الحزمة والتبعيات وفقًا لـ PEP 621. ما يلي يصلح كنقطة بداية جيدة لتطبيق ويمكن توسيعه لاحقًا.

معظم محتويات هذا الملف هي قالب أساسي، ويمكن رؤية نسخة أكثر اكتمالاً منه في بايثون مع كيريغامي: الهيكل العام.

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

لاحظ الأسطر المميزة. كما ذُكر تحت هيكل المشروع، اسم الحزمة هو kirigami_python، اسم الملف التنفيذي هو kirigami_hello، واسم نقطة الدخول هو app. على وجه الخصوص، يجب ملاحظة ما يلي:

• يتكون سكريبت المشروع من سكريبت نقطة دخول سيُولد بواسطة setuptools لتشغيل التطبيق، وفي هذه الحالة هو kirigami_hello.
• سكريبت المشروع المُولد kirigami_hello يشغّل الدالة main() في سكريبت app.py في حزمة kirigami_python.
• الدليل الافتراضي package-dir لمشاريع بايثون هو عادة الدليل الجذر. في هذه الحالة، يُستبدل هذا بالدليل الفرعي src/ ليعمل كالدليل الجذر للحزمة.
• بسبب package-dir، سكريبت المشروع المُولد يفعل kirigami_python → app بدلاً من kirigami_python → src → app.
• بسبب package-dir أيضًا، استدعاء importlib.resources.files() في app.py يفعل kirigami_python → qml → Main.qml بدلاً من kirigami_python → src → qml → Main.qml.

انظر التشغيل المباشر، كوحدة، وكسكريبت وحدة تحكم للتفاصيل.

org.kde.kirigami_python.desktop

الغرض الأساسي من ملفات إدخال سطح المكتب هو عرض تطبيقك على مشغل التطبيقات في لينكس. سبب آخر لامتلاكها هو الحصول على أيقونات النوافذ على Wayland، حيث إنها مطلوبة لإخبار المُركِّب "هذه النافذة تذهب مع هذه الأيقونة".

يجب أن يتبع نظام تسمية DNS العكسي متبوعًا بالامتداد .desktop مثل 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
21

[Desktop Entry]
Name=Kirigami Tutorial in Python
Name[ar]=درس كيريغامي ببايثون
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

هذا الملف هو ببساطة إعلان عن ملفات شيفرة مصدرية إضافية يجب أن تكون موجودة في الحزمة عند تشغيل التطبيق. بايثون افتراضيًا لا تتضمن ملفات QML في الحزم، ويجب أن تكون متاحة لتشغيل التطبيق.

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

بما أن هذا تطبيق واجهة رسومية، نريد أن تشتغل الدالة الرئيسية فقط عند تشغيل السكريبت، وليس عند استيراده، لذا نحتاج إلى الشرط if __name__ == "__main__" في نهاية الملف. انظر التشغيل المباشر، كوحدة، وكسكريبت وحدة تحكم للتفاصيل.

ننشئ QGuiApplication ونُهيئ محرك QML، ومع QGuiApplication.exec() سيستمر التطبيق في العمل حتى يُغلق. ثم importlib.resources.files() يلتقط المسار إلى ملف موجود في الحزمة، ألا وهو Main.qml. بذلك المسار، نُحمّل ملف QML في محرك QML كنقطة دخول رئيسية لواجهة التطبيق.

src/__init__.py

أنشئ ملفًا فارغًا kirigami_python/src/__init__.py. هذا الملف يحتاج فقط إلى الوجود لاستيراد دليل كحزمة.

touch __init__.py

src/__main__.py

أنشئ ملفًا kirigami_python/src/__main__.py بالمحتويات التالية:

1
2
3

from . import app

app.main()

يُضيف هذا ببساطة محتويات الدليل الحالي (src/) ويستوردها كوحدة باسم app، ثم يُشغّل فورًا دالة main() الخاصة بالتطبيق.

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

هنا سنتعامل مع الواجهة الأمامية لتطبيقنا.

إذا كنت تعرف بعض Javascript، فسيبدو لك الكثير من QML مألوفًا (رغم أن له خصائصه الخاصة). توثيق Qt يحتوي على كمية هائلة من المواد حول هذه اللغة إذا شعرت برغبة في تجربة شيء بنفسك. خلال هذه الدروس سنركز كثيرًا على شيفرة QML الخاصة بنا، حيث يمكننا استخدام Kirigami للاستفادة القصوى منها.

الآن، لنركز على Main.qml. أولاً نستورد عددًا من الوحدات المهمة:

• QtQuick، المكتبة القياسية المستخدمة في تطبيقات QML.
• QtQuick Controls، التي توفر عددًا من عناصر التحكم القياسية التي يمكننا استخدامها لجعل تطبيقاتنا تفاعلية.
• QtQuick Layouts، التي توفر أدوات لوضع المكونات داخل نافذة التطبيق.
• Kirigami، التي توفر عددًا من المكونات المناسبة لإنشاء تطبيقات تعمل عبر أجهزة بأشكال وأحجام مختلفة.

ثم نصل إلى العنصر الأساسي لدينا، Kirigami.ApplicationWindow، الذي يوفر بعض الميزات الأساسية اللازمة لجميع تطبيقات Kirigami. هذه هي النافذة التي ستحتوي كل صفحة من صفحاتنا، الأقسام الرئيسية لواجهة المستخدم لدينا.

ثم نضبط خاصية id للنافذة على "root". المعرفات مفيدة لأنها تسمح لنا بالإشارة بشكل فريد إلى مكون، حتى لو كان لدينا عدة مكونات من نفس النوع.

نضبط أيضًا خاصية title للنافذة على "Hello World".

ثم نضبط الصفحة الأولى من رصة الصفحات لدينا. معظم تطبيقات Kirigami منظمة كرصة من الصفحات، كل صفحة تحتوي على مكونات ذات صلة مناسبة لمهمة محددة. حاليًا، نبقي الأمر بسيطًا ونلتزم بصفحة واحدة. pageStack هي رصة صفحات فارغة في البداية مقدمة من Kirigami.ApplicationWindow، وباستخدام pageStack.initialPage: Kirigami.Page {...} نضبط الصفحة الأولى المعروضة عند تحميل التطبيق على Kirigami.Page. هذه الصفحة ستحتوي على كل محتوانا.

أخيرًا، نضمّن في صفحتنا Controls.Label الذي يتيح لنا وضع نص في صفحتنا. نستخدم anchors.centerIn: parent لتوسيط اللصيقة أفقيًا وعموديًا داخل العنصر الأب. في هذه الحالة، المكون الأب للصيقتنا هو Kirigami.Page. آخر ما علينا فعله هو ضبط نصها: text: "Hello World!".

تشغيل التطبيق

يمكنك تشغيل البرنامج النصي لوحدة التحكم kirigami_hello دون حاجة لتثبيته أولًا:

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

العلامة --system-site-packages ضرورية لجعل بايثون قادرًا على الوصول إلى حزم بايثون من توزيعتك. هذا مطلوب لأن كيريغامي وPySide يجب أن يكونا قد بُنيا ضد نفس إصدار كيوتي ليعملا، وهذا هو الحال عندما يأتي كلاهما من التوزيعة.

العلامة --spec تحدد المسار إلى شفرة المصدر أو حزمة العجلة التي تحتوي البرنامج، وkirigami_hello هو البرنامج النصي القابل للتنفيذ الذي سيُشغّل.

لبناء حزمة بايثون وتثبيتها، شغّل:

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

ستُثبّت الحزمة إلى ~/.local/share/pipx/venvs/kirigami-python، وسيُثبّت برنامج نصي قابل للتنفيذ إلى ~/.local/bin/kirigami_hello.

بعد هذا، يمكن إطلاق التطبيق بتشغيل:

kirigami_hello

لتشغيل تطبيق QML الجديد في وضع الجوال، يمكنك استخدام QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

هكذا! الآن سترى أول تطبيق Kirigami لك يظهر أمام عينيك.