شرح PyQt5 في Python هنا يعتمد نافذة صغيرة تطلب اسم المستخدم وتعرض رسالة عند الضغط على زر. نتعلم عناصر الواجهة والتخطيط والإشارات بدل وضع عناصر تجميلية لا تنفذ سلوكًا. PyQt5 يربط Python بإطار Qt 5؛ لا تخلط استيراداته مع PySide أو PyQt6 لأن أسماء الدوال وبعض قواعد التشغيل تختلف. تحتاج جلسة سطح مكتب عادية لعرض النافذة، بينما يمكن اختبار المنطق في وضع offscreen دون فتحها.
التجهيز والمتطلبات
python -m pip install PyQt5QApplication ودورة الأحداث
ينشأ QApplication واحد قبل عناصر الواجهة، ثم تبقى دورة الأحداث app.exec_ في انتظار النقر والكتابة وإعادة الرسم. تحتفظ الشيفرة بمرجع window حتى لا يتخلص Python من النافذة قبل انتهاء البرنامج. ترجع دالة create_window العناصر المهمة كي يمكن اختبارها وإعادة استخدامها. عند إغلاق النافذة الرئيسية تنتهي الحلقة ويعاد رمز الخروج للنظام؛ لا تحتاج حلقة while يدوية لفحص الزر.
التخطيط وإشارة clicked
يضع QVBoxLayout العناصر عموديًا ويتولى توزيع المسافات وتغيير المقاسات عند تكبير النافذة. هذا أكثر مرونة من إحداثيات ثابتة تتداخل عند اختلاف الخطوط. توصل clicked بالدالة greet دون أقواس؛ كتابة greet() ستنفذها فور بناء الواجهة بدل انتظار النقر. تقرأ الدالة النص وقت الضغط، وتحذف الفراغات الزائدة ثم تعرض تحية أو تطلب إدخال الاسم. لا نعتمد متغيرًا قديمًا قرئ قبل كتابة المستخدم.
المثال البرمجي الكامل
import sys
from PyQt5.QtWidgets import QApplication, QWidget, QVBoxLayout, QLabel, QLineEdit, QPushButton
def create_window():
window = QWidget()
window.setWindowTitle("Geecoders - PyQt5")
window.resize(380, 180)
layout = QVBoxLayout(window)
name = QLineEdit()
name.setPlaceholderText("Enter your name")
greeting = QLabel("Welcome")
button = QPushButton("Show greeting")
def greet():
value = name.text().strip()
greeting.setText(f"Hello, {value}" if value else "Please enter a name")
button.clicked.connect(greet)
layout.addWidget(name)
layout.addWidget(button)
layout.addWidget(greeting)
return window, name, button, greeting
if __name__ == "__main__":
app = QApplication(sys.argv)
window, name, button, greeting = create_window()
window.show()
sys.exit(app.exec_())
التشغيل والتحقق من الإدخال
احفظ الملف باسم gui_demo.py وشغله باستخدام مفسر البيئة التي ثبتت فيها PyQt5. اضغط الزر والحقل فارغ ثم اكتب Ali واضغط مرة أخرى؛ يجب أن تتغير النتيجة. يمكن تعريب العبارات وضبط اتجاه العناصر لاحقًا وفق التصميم. تغيير النص لا يحتاج إعادة إنشاء نافذة أو QApplication. إذا أغلق البرنامج مباشرة فتأكد من تشغيل كتلة main ومن عدم حذف استدعاء دورة الأحداث.
من المثال إلى تطبيق حقيقي
عند إضافة OCR أو قراءة ملفات كبيرة لا تنفذ عملًا طويلًا مباشرة داخل دالة الزر لأن الواجهة ستتوقف عن الاستجابة. انقل العمل إلى عامل مناسب وأعد النتيجة بإشارات، مع إبقاء تحديث عناصر الواجهة في خيطها الرئيسي. للتوزيع التجاري راجع ترخيص PyQt5 ومتطلبات Qt. أما أخطاء platform plugin فقد تتعلق ببيئة العرض أو تثبيت متداخل؛ ابدأ ببيئة نظيفة بدل نسخ ملفات DLL من مواقع عشوائية.
لماذا تعود الدالة بعدة عناصر؟
إرجاع النافذة والحقل والزر والنتيجة يجعل المثال قابلًا للاختبار دون البحث عن العناصر بالإحداثيات أو الأسماء. يمكن للاختبار تعيين نص ثم استدعاء click على الزر وقراءة محتوى QLabel. هذه خطوة بسيطة قبل تحويل الواجهة إلى فئة مخصصة عند نمو التطبيق. لا تحتاج إنشاء فئة كبيرة منذ السطر الأول، لكن ينبغي فصل منطق معالجة البيانات عن تكوين العناصر حتى لا يصعب اختبار الحسابات دون فتح الواجهة.
كيف أتعامل مع الخطأ داخل حدث الزر؟
افحص المدخلات أولًا وأظهر رسالة مفهومة بدل ترك استثناء يصل إلى المستخدم. إذا كان الزر يستدعي ملفًا أو خدمة، احصر نوع الخطأ المتوقع ولا تخف كل الأخطاء تحت عبارة نجاح. يمكن تعطيل الزر أثناء عمل طويل ثم تفعيله عند الاكتمال أو الفشل. لا تحدث عناصر النافذة مباشرة من خيط خلفي؛ استخدم إشارات لإرجاع النتيجة إلى خيط الواجهة. بهذه البنية تستطيع إضافة شريط تقدم لاحقًا دون تجميد الشاشة.
هل يعمل المثال مع Qt Designer؟
يمكن تصميم العناصر في Qt Designer ثم تحميلها أو تحويل ملفها، لكن يجب الحفاظ على الفصل بين الملف المولد والسلوك الذي تضيفه. إعادة توليد كود الواجهة قد تمحو تعديلات يدوية وضعت داخله، لذلك ضع منطق البرنامج في ملف مستقل. المثال اليدوي هنا يوضح العناصر والإشارات دون الاعتماد على ملف خارجي، ويمكن نقل الفكرة إلى تصميم بصري بعد فهم من ينشئ QApplication وأين تبدأ دورة الأحداث.
المراجع
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.







