🎨 واجهاتُ SadUIيعملُ بحدودٍ مُعلَنةكلُّ المجالات

الأحداثُ والحالةُ والتنقّل

وصفةٌ لمهمّةٍ واحدة: أن يستجيبَ العنصرُ لفعلِ المستعمِل، فتتغيّرَ الحالةُ، فتُعادَ الشجرةُ رسمًا، أو تُبدَّلَ الصفحة.

١ · اربِطْ معالِجًا

كلُّ معدّلٍ يبدأُ بالبادئةِ عند_ يُسجّلُ معالِجَ حدث. واللاحقةُ بعدَها تُحَلُّ في ui_events.yaml — ٣٢ نوعَ حدثٍ مُعلَنًا زائدَ مخصص احتياطيًّا.

دالة سُجِّل()
    اطبع_سطر("نُقِر")
نهاية

متغير ز = زر("احفظ").عند_النقر(سُجِّل)

الأكثرُ استعمالًا:

الحدث	متى
عند_النقر	نقرة/ضغطة على العنصر
عند_التغيير	تغيُّرُ قيمةِ حقلٍ أو منزلق
عند_الإدخال	إدخالُ نصّ
عند_التحويم · عند_الخروج	دخولُ المؤشِّرِ وخروجُه
عند_التركيز · عند_فقد_التركيز	التركيز
عند_الإرسال	إرسالُ نموذج
عند_ضغط_مفتاح · عند_رفع_مفتاح	لوحةُ المفاتيح
عند_الظهور · عند_الاختفاء	دورةُ حياةِ العقدة

مقيس: مرِّرِ اسمَ دالّةٍ من كتابتِك

تمريرُ اسمِ مدمَجةٍ مباشرةً يُرفَض. زر("رجوع").عند_النقر(عودة) يخفقُ بـ[SEM001] المتغير 'عودة' غير معرَّف — فالمدمَجةُ ليست قيمةً تُمرَّر. لُفَّها في دالّة (المثالُ في §٣).

٢ · غيِّرِ الحالةَ ثمّ اطلُبْ إعادةَ الرسم

الحالةُ في لغةِ ص متغيّراتٌ عاديّة. والذي يُميّزُ الواجهةَ سطرٌ واحد: تحديث_حالة() — يُعلِمُ الحلقةَ بأنّ الشجرةَ تغيّرت.

متغير العدد = 0
متغير العرض = نص_عنصر("العدد: 0").حجم_خط(28).لون("#FFFFFF")

دالة زِد()
    العدد = العدد + 1
    عين_النص(العرض، "العدد: " + العدد)
    تحديث_حالة()
نهاية

حدٌّ مقيسٌ على عين_النص

طباعة_شجرة بعدَ ندائها يُظهِرُ خاصّيّةً جديدةً باسمِ text بجوارِمحتوى لا بدلًا منها. وأيُّ القيمتَينِ تفوزُ عندَ الرسمِ لم يُقَسْ — انظر شجرةُ الواجهة.

وثمّةَ صياغةٌ ثانيةٌ تُغني عن التعديلِ الموضعيّ: مرِّرْ دالّةً بانيةً إلى تشغيل_تطبيق بدلَ عقدةٍ ثابتة، فتُستدعى كلَّ رسمٍ وتُبنى الشجرةُ من الحالةِ الجارية — وهي الصياغةُ المُعلَنةُ في وصفِ معاملِ تشغيل_تطبيق نفسِه، ومقيسٌ أنّها تُترجَمُ وتفتحُ النافذة:

🧩 مقتطفٌ يُتِمُّ برنامجَ الأعلى — لا يُترجَمُ وحدَه.

دالة ابنِ()
    ارجع عمود(
        نص_عنصر("العدد: " + العدد).حجم_خط(28)،
        زر("زِد").عند_النقر(زِد)
    ).حشوة(24)
نهاية

تشغيل_تطبيق(ابنِ)

مكوّنٌ تصريحيٌّ بحالةٍ خاصّة

واجهة … نهاية تُصرِّحُ مكوّنًا يحملُ حالتَه بوسمِ @حالة، ودالّةُ بناء() تُرجِعُ شجرتَه.

واجهة عدّاد
    @حالة عدد: رقم = 0

    دالة بناء()
        ارجع عمود(
            نص_عنصر("العدّاد: " + هذا.عدد)،
            زر("زيادة")
        )
    نهاية

    دالة زِد()
        هذا.عدد = هذا.عدد + 1
    نهاية
نهاية

متغير ع = عدّاد()
ع.زِد()
ع.زِد()
طباعة_شجرة(ع.بناء())

المخرَجُ المقيس: نص_عنصر(محتوى: "العدّاد: 2").

٣ · تنقّلْ بينَ الصفحات

UICore يملكُ مكدَّسَ صفحاتٍ: انتقل تدفع، وعودة تسحب، وعودة_للبداية تُفرِغُ إلى الجذر، واستبدل تُبدِّلُ الحاليّةَ بلا دفع. وعدد_الصفحات والصفحة_الحالية يقرآنِ حالَ المكدَّس.

دالة إلى_الخلف()
    عودة()
نهاية

متغير الثانية = عمود(
    نص_عنصر("الصفحةُ الثانية").لون("#FFFFFF")،
    زر("رجوع").عند_النقر(إلى_الخلف)
).لون_خلفية("#123456").حشوة(24).تباعد(16)

دالة إلى_الأمام()
    انتقل(الثانية)
نهاية

وللانتقالِ بتأثير: انتقل_بتحريك(صفحة، نوع، مدّة)، وانتقل_بتحريك_كامل تفصلُ تأثيرَ الدخولِ عن الخروج، وعودة_بتحريك نظيرُها في الرجوع.

٤ · الانتشار — الاشتراكُ صريحٌ لا ضمنيّ

الطورُ مُعلَنٌ على المعالِجِ لا على الحدث (نموذجُ DOM). والافتراضُ لا_انتشار: بلا معدّلِ تفرع لا يستقبلُ الجدُّ أحداثَ أحفادِه البتّة.

الطور	المعنى
لا_انتشار	الهدفُ وحدَه — الافتراض
فقاعة	يستقبلُ أحداثَ الأبناءِ صعودًا نحوَ الجذر
التقاط	يستقبلُها نزولًا من الجذرِ قبلَ بلوغِ الهدف
كلاهما	الطورانِ معًا

🧩 مقتطفٌ يُتِمُّ برنامجَ الأعلى — لا يُترجَمُ وحدَه.

دالة سمعت_الأم()
    اطبع_سطر("الأمُّ سمعت")
نهاية

متغير الأولى = عمود(
    زر("زِد").عند_النقر(زِد)
)
    .حشوة(40)
    .عند_النقر(سمعت_الأم)
    .تفرع("فقاعة")

تفرع تُعدِّلُ آخرَ معالِجٍ سُجِّل، كما تُعدِّلُ مدة آخرَ حركةٍ بدأت — فموضعُها بعدَ عند_* مباشرةً ليس تجميلًا.

حدٌّ مقيس

.تفرع("فقاعة") تُترجَمُ ولا تُرفَض، ومخرَجُ طباعة_شجرة لا يعرضُ الطور — فلا سبيلَ إلى تأكيدِ الفقاعاتِ نصّيًّا. والتحقّقُ اليومَ نقرةٌ بشريّةٌ على نافذةٍ مفتوحة، لا بوّابةٌ آليّة.

٥ · وأمّا التحريك

حرك تبدأُ سلسلةً، وما بعدَها يُعدِّلُها. وui_animations.yaml يُعلِنُ ٢٧ نوعَ حركة (ظهور · اختفاء · دوران · نبض · ارتداد …)، وui_easings.yaml سبعةَ منحنيات (خطي · تسارع · تباطؤ · تسارع_وتباطؤ · ارتداد · مرن · نابض).

متغير ب = نص_عنصر("مرحبًا")
    .حرك("ظهور")
    .مدة(0.5)
    .منحنى("مرن")
    .تأخير(0.2)
    .تكرار(3)

والسلسلةُ تظهرُ في مخرَجِ الشجرة — وهذا مقيس:

نص_عنصر(محتوى: "مرحبًا") {حركة:ظهور/0.5ث/مرن تأخير:0.2ث تكرار:3}

ماذا يُحرَسُ ههنا وماذا لا

تسجيلُ المعالِجِ وسلسلةُ التحريكِ يظهرانِ في نصِّ الشجرةِ فيُقارَنان. أمّا إطلاقُ المعالِجِ عندَ النقرِ وإعادةُ الرسمِ فلم يُقَسْ في هذه الصفحة، ولا بذرةَ في tests/behavior تستدعي تشغيل_تطبيق.