كيف تراقب أحداث النموذج باستخدام فئات observer في SketchUp Ruby API؟

ما الذي ستتعلمه في هذا الدليل؟

تُستخدم فئات observer في SketchUp Ruby API للاستجابة للأحداث التي تقع على كائن أو مجموعة محددة. في هذا الدليل، نتناول ثلاثة نطاقات: EntitiesObserver لمجموعة هندسية، وModelObserver لأحداث مستوى النموذج، وDefinitionObserver للنسخ المرتبطة بتعريف مكوّن. سترى في الخطوات كيفية إنشاء فئة observer وربطها بالكائن المراد تتبّعه.

يمكن استخدام هذه الطريقة لتسجيل الأحداث في الإضافات أو تتبّع إجراءات المستخدم. لكن لا ينبغي اعتبار observers آلية تلتقط كل حدث فور وقوعه وتتيح إجراء تغييرات آمنة على النموذج. فتوقيت callback الخاصة بالعمليات، وحالة الكائنات التي أُزيلت، والاستثناءات التي تسببها بعض عمليات الأدوات، كلها عوامل تؤثر في تصميم التطبيق.

المتطلبات واختيار النطاق

تستند الأمثلة إلى الفئات والطرائق الواردة في وثائق SketchUp Ruby API. تذكر المصادر SketchUp 6.0 لكل من EntitiesObserver وDefinitionObserver، وSketchUp 8.0 لـonElementModified، وSketchUp 2014 لـcallback مستوى القطع النشط. أما وثائق ModelObserver فتشرح كيفية عمل أحداث العمليات منذ SketchUp 2016. هذه معلومات الإصدارات المذكورة في المصادر لميزات API المعنية؛ ولا يحدد الدليل متطلبات إضافية لإصدار SketchUp بعينه أو نوع حساب أو رسوم أو عتاد.

ابدأ بتحديد نطاق الحدث الذي تريد تتبّعه:

• تُستخدم EntitiesObserver لأحداث العناصر في مجموعة Sketchup::Entities.

• يُفضّل استخدام ModelObserver لأحداث مستوى النموذج، مثل الحفظ وإضافة المكوّنات وأحداث العمليات.

• تُستخدم DefinitionObserver لإضافة النسخ المرتبطة بتعريف مكوّن محدد وإزالتها.

يجب أن تعرّف فئة observer طريقة callback الخاصة بالحدث المراد تتبّعه. بعد ذلك، أضف نسخة من الفئة إلى المجموعة أو النموذج أو تعريف المكوّن المعني. تطبع الأمثلة أدناه رسائل في وحدة التحكم، ما يتيح لك ملاحظة callback التي يجري استدعاؤها.

1. تتبّع التغييرات في مجموعة هندسية

تراقب EntitiesObserver الأحداث التي تقع ضمن مجموعة Sketchup::Entities. وتُبلغ الفئة أدناه على نحو منفصل عن إضافة عنصر إلى المجموعة أو تعديله أو إزالته. كما تعرّف callback منفصلة لحذف عنصر واحد أو أكثر من المجموعة.

class EntityEvents < Sketchup::EntitiesObserver
  def onElementAdded(entities, entity)
    puts "Eklendi: #{entity}"
  end

  def onElementModified(entities, entity)
    puts "Değiştirildi: #{entity}"
  end

  def onElementRemoved(entities, entity_id)
    puts "Kaldırıldı; kimlik: #{entity_id}"
  end

  def onEraseEntities(entities)
    puts "Koleksiyondaki öğeler silindi: #{entities}"
  end
end

model = Sketchup.active_model
model.entities.add_observer(EntityEvents.new)

في السطر الأخير، يُربط observer بمجموعة entities الخاصة بالنموذج النشط. تُستدعى onElementAdded عند إضافة عنصر واحد، بينما تُستدعى onElementModified عند تعديل عنصر واحد أو أكثر في المجموعة. وتُبلغ onElementRemoved عن إزالة عنصر واحد. ينبغي استخدام المعامل الوارد إلى callback للتعرّف على حدث الإزالة، لا لإعادة استخدام العنصر الذي أُزيل. وتشير الوثائق إلى أنه لا ينبغي استخدام العنصر المحذوف لأي غرض آخر.

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

2. تتبّع أحداث مستوى النموذج

لرصد الأحداث العامة للنموذج، أنشئ فئة فرعية من Sketchup::ModelObserver. يطبع المثال أدناه رسائل منفصلة عند اكتمال عملية تتضمن تغييرات، أو اكتمالها دون تغييرات، أو إلغائها.

class ModelEvents < Sketchup::ModelObserver
  def onTransactionCommit(model)
    puts "Model değişikliği içeren işlem tamamlandı."
  end

  def onTransactionEmpty(model)
    puts "İşlem tamamlandı; modelde değişiklik yok."
  end

  def onTransactionAbort(model)
    puts "İşlem iptal edildi."
  end
end

Sketchup.active_model.add_observer(ModelEvents.new)

تُستدعى onTransactionCommit عند اكتمال عملية تُجري تغييرات على النموذج، بينما تُستدعى onTransactionEmpty عند بدء عملية واكتمالها دون إجراء أي تغيير. أما onTransactionAbort فتُرسل إشعارًا عند إلغاء العملية. وتضم واجهة observer نفسها أيضًا callback لأحداث أخرى، مثل إضافة مكوّن وحفظ النموذج وفتح مجموعة أو مكوّن لتحريره.

توقيت callback الخاصة بالعمليات تفصيل مهم. فمنذ SketchUp 2016، تُوضَع أحداث observer داخل العملية في قائمة انتظار، ثم تُرسل بعد تنفيذ commit للعملية. لذلك لا تعمل callback مثل onTransactionStart آنيًا عند بدء تحرير النموذج. ويصل إشعار onTransactionCommit للعملية التي تتضمن تغييرات، وإشعار onTransactionEmpty للعملية التي اكتملت دون تغييرات، في مرحلة commit. أما إشعار الإلغاء فيُرسل منفصلًا عبر onTransactionAbort؛ فلا تخلط بين هذه callback وإشعارات commit أو العملية الفارغة.

وفقًا للوثائق، لا توجد في API طريقة للاستعلام عمّا إذا كانت هناك عملية مفتوحة في تلك اللحظة. لذلك لا تصلح callback الخاصة بالعمليات لتتبّع حالة العملية في الوقت الفعلي. وتوصي المصادر باستخدامها أساسًا لأغراض إعداد التقارير وتصحيح الأخطاء. تجنّب بدء عملية جديدة لتعديل النموذج من داخل callback: إذ تحذّر الوثائق من أن مثل هذه التعديلات قد تؤدي إلى تعطل التطبيق أو تلف النموذج. ويُعد الاستخدام المخصص للمراقبة، مثل الطباعة في وحدة التحكم أو تسجيل الأحداث، أنسب للأمثلة.

3. تتبّع النسخ المرتبطة بتعريف مكوّن

استخدم DefinitionObserver لتتبّع إضافة نسخة إلى تعريف مكوّن أو إزالة نسخة منه. في المثال أدناه، يُضاف observer إلى تعريف مكوّن في النموذج النشط.

class ComponentEvents < Sketchup::DefinitionObserver
  def onComponentInstanceAdded(definition, instance)
    puts "Bileşen örneği eklendi: #{instance}"
  end

  def onComponentInstanceRemoved(definition, instance)
    puts "Bileşen örneği kaldırıldı: #{instance}"
  end
end

definition = Sketchup.active_model.definitions[0]
definition.add_observer(ComponentEvents.new)

تُستدعى onComponentInstanceAdded عند إضافة نسخة جديدة إلى التعريف الذي تتم مراقبته. أما onComponentInstanceRemoved فتراقب إزالة النسخ المرتبطة بالتعريف. ولا يتتبّع observer سوى التعريف الذي أُضيف إليه؛ لذا يجب إضافته إلى أي تعريف آخر تريد مراقبته. يتيح definitions[0] في المثال الوصول إلى أحد تعريفات المكوّنات في النموذج النشط.

هناك استثناء خاص بـcallback الإزالة: بسبب طريقة تنفيذ أداة Move في SketchUp، قد تُستدعى onComponentInstanceRemoved أثناء عملية Move + Copy حتى إن لم تُزل أي نسخة ظاهريًا. لذلك لا تعتبر استدعاء callback وحده دليلًا قاطعًا على حذف مكوّن من النموذج.

الأخطاء الشائعة والخطوات التالية

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

ومن الأخطاء الأخرى التعامل مع المعامل الوارد إلى onElementRemoved كما لو كان عنصرًا لا يزال قابلًا للاستخدام. فهو يُبلغ عن معرّف العنصر الذي أُزيل؛ وتشير الوثائق إلى أنه لا ينبغي استخدام العنصر المحذوف إلا لمعرفة أنه أُزيل. وعند تفسير حدث الإزالة في DefinitionObserver، ضع استثناء Move + Copy في الحسبان أيضًا.

كما أن تعديل النموذج داخل callback الخاصة بالعملية ينطوي على مخاطر. في التجارب الأولى، اجعل callback تكتفي بطباعة مخرجات في وحدة التحكم أو تسجيل الأحداث. ثم راقب أي callback تُستدعى مع إجراءات المستخدم المختلفة. وعند البحث في مشكلات تدفّق العمليات، ميّز بين إشعارات البدء وcommit والعملية الفارغة والإلغاء؛ وتذكّر أن callback البدء لا تعرض لحظة البداية الفعلية للعملية.

ابدأ بعد ذلك بنوع واحد من الأحداث، وتحقق من نطاقه وتوقيته. وعندما تتضح الحاجة، أضف إلى الفئة callback المطلوبة فقط. يساعد ذلك على حصر مسؤولية كود المراقبة وتسهيل متابعة مدلول معاملات callback. وإذا كان سير العمل يتطلب إجراء تغييرات على النموذج، فقيّم على نحو منفصل حدود الاستخدام الآمن لـcallback الخاصة بـobserver.

المصادر والترخيص

أُعدّ هذا الدليل بالاستناد إلى الوثائق الرسمية لفئات EntitiesObserver وModelObserver وDefinitionObserver في SketchUp Ruby API. وتذكر خانة الترخيص في المصادر أن الاستخدام «حر».