مكتبة graphics — الرسوميات

مكتبة الرسوميات في لغة ص توفّر واجهة عربية متكاملة للرسم ثنائي البعد وإنشاء واجهات رسومية تفاعلية. تعتمد المكتبة على SDL2 + OpenGL في الخلفية، مما يجعلها متوافقة مع أنظمة التشغيل المختلفة (ويندوز، لينكس، ماك). تتيح لك المكتبة إنشاء نوافذ، رسم الأشكال الهندسية، عرض النصوص والصور، ومعالجة أحداث المستخدم مثل النقر وتحريك الماوس ولوحة المفاتيح.

الاستيراد

استورد رسوميات من "stdlib/graphics"

ملخص الدوال

الدالة	الوصف
رسوميات.إنشاء_نافذة(عنوان، عرض، ارتفاع)	إنشاء نافذة رسومية جديدة
نافذة.احصل_على_رسام()	الحصول على كائن الرسام للنافذة
نافذة.مفتوحة()	التحقق من أن النافذة لا تزال مفتوحة
نافذة.عرض()	تحديث الشاشة وإظهار الرسومات
نافذة.معالجة_الأحداث()	معالجة أحداث النظام والمستخدم
نافذة.أغلق()	إغلاق النافذة وتحرير الموارد
رسام.امسح(لون)	مسح الشاشة بلون معين
رسام.ارسم_نقطة(س، ص، لون)	رسم نقطة (بكسل) واحدة
رسام.ارسم_خط(س1، ص1، س2، ص2، لون)	رسم خط مستقيم
رسام.ارسم_مستطيل(س، ص، عرض، ارتفاع، لون)	رسم مستطيل (إطار)
رسام.ارسم_مستطيل_ممتلئ(س، ص، عرض، ارتفاع، لون)	رسم مستطيل مملوء
رسام.ارسم_دائرة(س، ص، نصف_قطر، لون)	رسم دائرة (إطار)
رسام.ارسم_دائرة_ممتلئة(س، ص، نصف_قطر، لون)	رسم دائرة مملوءة
رسام.ارسم_نص(نص، س، ص، لون)	رسم نص على الشاشة
رسام.ارسم_صورة(مسار، س، ص)	رسم صورة من ملف

---

إدارة النوافذ

رسوميات.إنشاء_نافذة(عنوان، عرض، ارتفاع)

تنشئ هذه الدالة نافذة رسومية جديدة بالأبعاد المحددة وتعرض عنوانًا في شريط العنوان. النافذة هي الحاوية الأساسية التي يتم فيها كل الرسم والتفاعل. يمكنك تحديد عرض وارتفاع النافذة بالبكسل، والنافذة تظهر فور إنشائها. يُعاد كائن النافذة الذي يمكنك من خلاله الوصول إلى الرسام ومعالجة الأحداث.

استورد رسوميات من "stdlib/graphics"

# إنشاء نافذة لعرض نتائج حساب الزكاة
متغير نافذة = رسوميات.إنشاء_نافذة("حاسبة الزكاة"، 800، 600)
اطبع_سطر("تم إنشاء النافذة بنجاح")

نافذة.احصل_على_رسام()

تُرجع كائن الرسام (Renderer) المرتبط بالنافذة. الرسام هو الأداة التي تستخدمها لرسم الأشكال والنصوص والصور على سطح النافذة. يجب استدعاء هذه الدالة بعد إنشاء النافذة مباشرة، حيث أن جميع عمليات الرسم تتم من خلال كائن الرسام.

متغير نافذة = رسوميات.إنشاء_نافذة("الرسام العربي"، 640، 480)
متغير رسام = نافذة.احصل_على_رسام()

نافذة.مفتوحة()

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

متغير نافذة = رسوميات.إنشاء_نافذة("تطبيقي"، 800، 600)
متغير رسام = نافذة.احصل_على_رسام()

بينما (نافذة.مفتوحة())
    نافذة.معالجة_الأحداث()
    # رسم المحتوى هنا
    نافذة.عرض()
نهاية

نافذة.عرض()

تقوم بتحديث الشاشة وإظهار كل ما تم رسمه منذ آخر استدعاء لها. تعمل المكتبة بنظام التخزين المؤقت المزدوج (Double Buffering)، حيث يتم الرسم على مخزن مؤقت خلفي ثم يُعرض دفعة واحدة عند استدعاء عرض(). هذا يمنع الوميض ويضمن عرضًا سلسًا.

# الرسم يتم على المخزن الخلفي
رسام.امسح(رسوميات.أبيض)
رسام.ارسم_دائرة(400، 300، 100، رسوميات.أخضر)

# عرض كل شيء دفعة واحدة
نافذة.عرض()

نافذة.معالجة_الأحداث()

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

بينما (نافذة.مفتوحة())
    # معالجة الأحداث أولاً
    نافذة.معالجة_الأحداث()
    
    # ثم الرسم
    رسام.امسح(رسوميات.أسود)
    رسام.ارسم_نص("اضغط X للإغلاق"، 300، 280، رسوميات.أبيض)
    نافذة.عرض()
نهاية

نافذة.أغلق()

تُغلق النافذة وتحرر جميع الموارد المرتبطة بها (الذاكرة، مقابض النظام، إلخ). يمكنك استدعاؤها لإغلاق النافذة برمجيًا بدلاً من انتظار المستخدم. بعد الإغلاق، تُرجع نافذة.مفتوحة() القيمة خطأ.

# إغلاق النافذة بعد 5 ثوانٍ
رسام.ارسم_نص("سيتم الإغلاق تلقائيًا..."، 250، 280، رسوميات.أبيض)
نافذة.عرض()
انتظر(5000)
نافذة.أغلق()

---

الرسم الأساسي

رسام.امسح(لون)

تمسح كامل سطح الرسم وتملؤه باللون المحدد. تُستدعى عادة في بداية كل إطار (frame) قبل رسم أي شيء جديد، لضمان عدم تراكم الرسومات من الإطارات السابقة. اللون يمكن أن يكون أحد الألوان المعرفة مسبقًا أو لونًا مخصصًا.

# مسح الشاشة باللون الأبيض (مثل ورقة بيضاء)
رسام.امسح(رسوميات.أبيض)

# مسح الشاشة باللون الأسود (الوضع الليلي)
رسام.امسح(رسوميات.أسود)

رسام.ارسم_نقطة(س، ص، لون)

ترسم نقطة واحدة (بكسل) في الموقع المحدد بالإحداثيات (س، ص). النقطة هي أصغر وحدة رسم ممكنة. تُستخدم في الرسم الدقيق مثل رسم المنحنيات الرياضية أو أنماط النقاط.

# رسم نمط نقاط على شكل شبكة
متغير س = 0
بينما (س < 800)
    متغير ص = 0
    بينما (ص < 600)
        رسام.ارسم_نقطة(س، ص، رسوميات.رمادي)
        ص = ص + 20
    نهاية
    س = س + 20
نهاية

رسام.ارسم_خط(س1، ص1، س2، ص2، لون)

ترسم خطًا مستقيمًا بين نقطتين: من (س1، ص1) إلى (س2، ص2). الخط يُرسم بعرض بكسل واحد باللون المحدد. يُستخدم لرسم الحدود والأعمدة والمحاور في الرسوم البيانية.

# رسم محاور إحداثية لرسم بياني
رسام.امسح(رسوميات.أبيض)

# المحور الأفقي
رسام.ارسم_خط(50، 500، 750، 500، رسوميات.أسود)

# المحور العمودي
رسام.ارسم_خط(50، 500، 50، 50، رسوميات.أسود)

---

الأشكال الهندسية

رسام.ارسم_مستطيل(س، ص، عرض، ارتفاع، لون)

ترسم مستطيلًا فارغًا (إطار فقط) في الموقع (س، ص) بالأبعاد المحددة. النقطة (س، ص) هي الزاوية العلوية اليسرى للمستطيل. يُرسم الإطار بعرض بكسل واحد. مناسب لرسم الحدود والإطارات.

# رسم إطار حول عنوان
رسام.ارسم_مستطيل(100، 50، 600، 80، رسوميات.ذهبي)
رسام.ارسم_نص("بسم الله الرحمن الرحيم"، 220، 75، رسوميات.أسود)

رسام.ارسم_مستطيل_ممتلئ(س، ص، عرض، ارتفاع، لون)

ترسم مستطيلًا مملوءًا بالكامل باللون المحدد. تُستخدم لإنشاء الخلفيات، الأزرار، أشرطة التقدم، وأعمدة الرسوم البيانية. المعاملات مطابقة لدالة ارسم_مستطيل لكن المستطيل يكون مملوءًا.

# رسم أعمدة بيانية لحضور طلاب حلقة القرآن
متغير أيام = ["السبت"، "الأحد"، "الاثنين"، "الثلاثاء"، "الأربعاء"]
متغير حضور = [15، 18، 12، 20، 16]

رسام.امسح(رسوميات.أبيض)
رسام.ارسم_نص("حضور حلقة القرآن الأسبوعي"، 200، 30، رسوميات.أسود)

لكل ي في [0، 1، 2، 3، 4]
    متغير ارتفاع_عمود = حضور[ي] * 20
    رسام.ارسم_مستطيل_ممتلئ(100 + ي * 130، 500 - ارتفاع_عمود، 100، ارتفاع_عمود، رسوميات.أخضر)
    رسام.ارسم_نص(أيام[ي]، 110 + ي * 130، 510، رسوميات.أسود)
نهاية

رسام.ارسم_دائرة(س، ص، نصف_قطر، لون)

ترسم دائرة فارغة (إطار فقط) مركزها في النقطة (س، ص) بنصف القطر المحدد. ترسم محيط الدائرة فقط بعرض بكسل واحد. تُستخدم في الرسوم التوضيحية والأنماط الهندسية.

# رسم أنماط هندسية إسلامية — دوائر متداخلة
رسام.امسح(رسوميات.أبيض)
متغير ي = 1
بينما (ي <= 8)
    رسام.ارسم_دائرة(400، 300، ي * 30، رسوميات.أزرق)
    ي = ي + 1
نهاية

رسام.ارسم_دائرة_ممتلئة(س، ص، نصف_قطر، لون)

ترسم دائرة مملوءة بالكامل باللون المحدد. تُستخدم لرسم النقاط الكبيرة، الكرات، الأيقونات الدائرية، وعناصر واجهة المستخدم المستديرة. مثالية لرسم رسوم بيانية دائرية (Pie Charts).

# رسم اتجاه القبلة — بوصلة بسيطة
رسام.امسح(رسوميات.أبيض)

# الخلفية الدائرية
رسام.ارسم_دائرة_ممتلئة(400، 300، 150، رسوميات.أزرق_فاتح)

# المركز
رسام.ارسم_دائرة_ممتلئة(400، 300، 10، رسوميات.أحمر)

# علامة الشمال
رسام.ارسم_دائرة_ممتلئة(400، 160، 8، رسوميات.أسود)
رسام.ارسم_نص("ش"، 394، 140، رسوميات.أسود)

---

رسم النصوص والصور

رسام.ارسم_نص(نص، س، ص، لون)

ترسم نصًا على الشاشة في الموقع المحدد باللون المعطى. تدعم المكتبة النصوص العربية واليونيكود بشكل كامل. النقطة (س، ص) تمثل الزاوية العلوية اليسرى لمربع النص. يُستخدم لعرض العناوين، القيم الرقمية، الرسائل، والمعلومات على الشاشة.

# عرض معلومات المسجد
رسام.امسح(رسوميات.أبيض)
رسام.ارسم_نص("المسجد الأقصى المبارك"، 250، 50، رسوميات.أسود)
رسام.ارسم_نص("الموقع: القدس، فلسطين"، 250، 100، رسوميات.رمادي)
رسام.ارسم_نص("سنة البناء: 705م"، 250، 140، رسوميات.رمادي)
رسام.ارسم_نص("المساحة: 144,000 متر مربع"، 250، 180، رسوميات.رمادي)

رسام.ارسم_صورة(مسار، س، ص)

تحمّل صورة من ملف وترسمها على الشاشة في الموقع المحدد. تدعم صيغ الصور الشائعة مثل PNG وJPG وBMP. النقطة (س، ص) تمثل الزاوية العلوية اليسرى للصورة. الصورة تُرسم بحجمها الأصلي.

# عرض صورة خلفية للتطبيق
رسام.ارسم_صورة("صور/خلفية.png"، 0، 0)
رسام.ارسم_صورة("صور/شعار.png"، 350، 20)

---

الألوان المعرفة مسبقًا

توفر المكتبة مجموعة من الألوان الجاهزة للاستخدام المباشر:

اللون	الاسم
رسوميات.أسود	أسود
رسوميات.أبيض	أبيض
رسوميات.أحمر	أحمر
رسوميات.أخضر	أخضر
رسوميات.أزرق	أزرق
رسوميات.أصفر	أصفر
رسوميات.رمادي	رمادي
رسوميات.ذهبي	ذهبي
رسوميات.أزرق_فاتح	أزرق فاتح

---

مثال شامل — تطبيق رسم بياني لتوزيع الصدقات

استورد رسوميات من "stdlib/graphics"

# بيانات توزيع الصدقات الشهرية (بالريال)
متغير الأشهر = ["محرم"، "صفر"، "ربيع١"، "ربيع٢"، "جمادى١"، "جمادى٢"]
متغير المبالغ = [5000، 7500، 4200، 8000، 6300، 9100]

# إنشاء النافذة
متغير نافذة = رسوميات.إنشاء_نافذة("توزيع الصدقات الشهري"، 900، 600)
متغير رسام = نافذة.احصل_على_رسام()

بينما (نافذة.مفتوحة())
    نافذة.معالجة_الأحداث()
    رسام.امسح(رسوميات.أبيض)

    # العنوان
    رسام.ارسم_نص("توزيع الصدقات — النصف الأول من العام"، 250، 30، رسوميات.أسود)

    # المحاور
    رسام.ارسم_خط(80، 520، 850، 520، رسوميات.أسود)
    رسام.ارسم_خط(80، 520، 80، 70، رسوميات.أسود)

    # رسم الأعمدة
    لكل ي في [0، 1، 2، 3، 4، 5]
        متغير ارتفاع = المبالغ[ي] / 20
        متغير س = 120 + ي * 120
        متغير ص = 520 - ارتفاع

        # العمود
        رسام.ارسم_مستطيل_ممتلئ(س، ص، 80، ارتفاع، رسوميات.أخضر)
        رسام.ارسم_مستطيل(س، ص، 80، ارتفاع، رسوميات.أسود)

        # اسم الشهر
        رسام.ارسم_نص(الأشهر[ي]، س + 15، 530، رسوميات.أسود)

        # القيمة
        رسام.ارسم_نص(لنص(المبالغ[ي])، س + 10، ص - 25، رسوميات.أزرق)
    نهاية

    # المجموع
    متغير المجموع = 0
    لكل م في المبالغ
        المجموع = المجموع + م
    نهاية
    رسام.ارسم_نص("المجموع: " + لنص(المجموع) + " ريال"، 600، 560، رسوميات.أحمر)

    نافذة.عرض()
نهاية

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

مكتبة الرسوميات تتطلب تثبيت SDL2 على النظام. يتم تضمينها تلقائيًا عند بناء لغة ص من المصدر.

نظام الإحداثيات

نقطة الأصل (0، 0) هي الزاوية العلوية اليسرى من النافذة. المحور الأفقي (س) يزداد نحو اليمين، والمحور العمودي (ص) يزداد نحو الأسفل.