SketchUp Ruby API observer sinifları ilə model hadisələrini necə izləmək olar?

Bu bələdçidə nə öyrənəcəksiniz?

SketchUp Ruby API-də observer sinifləri müəyyən obyekt və ya kolleksiyada baş verən hadisələrə cavab vermək üçün istifadə olunur. Bu bələdçidə üç əhatə dairəsinə baxacağıq: həndəsə kolleksiyası üçün EntitiesObserver, model səviyyəsindəki hadisələr üçün ModelObserver və komponent tərifindəki nümunələr üçün DefinitionObserver. Addımlarda observer sinfinin necə yaradıldığını və izlənəcək obyektə necə qoşulduğunu görəcəksiniz.

Bu üsul plaginlərdə hadisələri qeydə almaq və ya istifadəçi əməliyyatlarını izləmək üçün yararlıdır. Bununla belə, observer-ləri hər hadisəni dərhal tutan və modeldə təhlükəsiz dəyişiklik edə bilən mexanizm kimi qəbul etmək olmaz. Xüsusilə əməliyyat callback-lərinin vaxtlaması, silinmiş obyektlərin vəziyyəti və bəzi alət əməliyyatlarının yaratdığı istisnalar tətbiqin dizaynına təsir edir.

Tələblər və əhatə dairəsinin seçilməsi

Nümunələr SketchUp Ruby API sənədlərindəki sinif və metodlara əsaslanır. Mənbələrdə EntitiesObserver və DefinitionObserver üçün SketchUp 6.0, onElementModified üçün SketchUp 8.0, aktiv kəsik müstəvisi callback-i üçün isə SketchUp 2014 versiya məlumatı verilir. ModelObserver sənədləri əməliyyat hadisələrinin SketchUp 2016-dan etibarən necə işlədiyini izah edir. Bunlar müvafiq API xüsusiyyətləri üçün mənbədə göstərilən versiya məlumatlarıdır; bələdçi üçün ayrıca müəyyən SketchUp versiyası, hesab növü, ödəniş və ya avadanlıq tələbi göstərilmir.

Əvvəlcə izlənəcək hadisənin hansı əhatə dairəsində baş verdiyini müəyyənləşdirin:

• Sketchup::Entities kolleksiyasındakı element hadisələri üçün EntitiesObserver istifadə olunur.

• Model səviyyəsində yadda saxlama, komponent yerləşdirmə və ya əməliyyat hadisələri üçün ModelObserver seçilir.

• Müəyyən komponent tərifinə aid nümunələrin əlavə edilməsi və silinməsi üçün DefinitionObserver istifadə olunur.

Observer sinfində izlənəcək hadisənin callback metodu müəyyən edilməlidir. Daha sonra sinfin nümunəsi müvafiq kolleksiyaya, modelə və ya komponent tərifinə əlavə olunur. Aşağıdakı nümunələr konsola mesaj yazır, beləliklə hansı callback-in işə düşdüyünü müşahidə etmək mümkündür.

1. Həndəsə kolleksiyasındakı dəyişiklikləri izləmək

EntitiesObserver bir Sketchup::Entities kolleksiyasında baş verən hadisələri izləyir. Aşağıdakı sinif kolleksiyaya element əlavə edilməsini, elementin dəyişdirilməsini və ya silinməsini ayrı-ayrılıqda bildirir. Kolleksiyadakı bir və ya bir neçə elementin silinməsi üçün də ayrıca callback müəyyən edir.

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)

Son sətirdə observer aktiv modelin entities kolleksiyasına qoşulur. onElementAdded bir element əlavə ediləndə, onElementModified isə kolleksiyadakı bir və ya bir neçə element dəyişdiriləndə çağırılır. onElementRemoved bir elementin silindiyini bildirir. Bu callback-ə ötürülən parametr silinmiş elementi yenidən istifadə etmək üçün deyil, silinmə hadisəsini tanımaq üçün nəzərdə tutulub. Sənədlərdə silinmiş elementdən bu məqsəddən başqa istifadə edilməməsi qeyd olunur.

Kəsik müstəvisinin vəziyyətini də izləmək lazımdırsa, sinfə onActiveSectionPlaneChanged(entities) metodu əlavə etmək olar. Bu callback müvafiq kolleksiyada kəsik müstəvisi aktivləşdiriləndə və ya aktiv müstəvi deaktiv ediləndə işə düşür. Callback daxilində entities.active_section_plane yoxlanaraq aktiv müstəvinin olub-olmadığı müəyyən edilə bilər. Bu metodu yalnız kəsik müstəvisi hadisələrini də izləmək lazım olduqda əlavə edin.

2. Model səviyyəsindəki hadisələri izləmək

Model üzrə ümumi hadisələr üçün Sketchup::ModelObserver alt sinfini yaradın. Aşağıdakı nümunə dəyişiklik olan əməliyyat başa çatdıqda, dəyişiklik edilmədən başa çatdıqda və ya ləğv edildikdə ayrı mesajlar çap edir.

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 modeldə dəyişiklik edən əməliyyat başa çatdıqda, onTransactionEmpty isə başladılıb heç bir dəyişiklik edilmədən tamamlanan əməliyyat zamanı çağırılır. onTransactionAbort əməliyyat ləğv edildikdə bildiriş verir. Eyni observer interfeysində komponentin yerləşdirilməsi, modelin yadda saxlanması və istifadəçinin qrupu və ya komponenti redaktə etmək üçün açması kimi başqa hadisələr üçün də callback-lər var.

Əməliyyat callback-lərinin vaxtlaması mühüm məqamdır. SketchUp 2016-dan etibarən əməliyyat daxilindəki observer hadisələri növbəyə alınır və əməliyyat commit edildikdən sonra ötürülür. Buna görə də onTransactionStart kimi callback-lər modelin redaktəsi başlayan kimi real vaxtda işləmir. Dəyişiklik olan əməliyyat üçün onTransactionCommit, dəyişiklik edilmədən başa çatan əməliyyat üçün isə onTransactionEmpty bildirişi commit mərhələsində gəlir. Ləğv barədə bildiriş ayrıca onTransactionAbort vasitəsilə verilir; bu callback-i commit və ya boş əməliyyat bildirişləri ilə eyni şəkildə başa düşməyin.

Sənədlərə görə API-də həmin anda əməliyyatın açıq olub-olmadığını sorğulayan metod yoxdur. Buna görə əməliyyat callback-ləri real vaxtda əməliyyat vəziyyətini izləmək üçün uyğun deyil. Mənbə bunlardan əsasən hesabat və sazlama məqsədilə istifadə etməyi tövsiyə edir. Callback daxilində modeli dəyişdirən yeni əməliyyata başlamayın: sənədlərdə belə dəyişikliklərin çökmə və ya modelin korlanması riski daşıya biləcəyi barədə xəbərdarlıq edilir. Konsola yazmaq və ya hadisələri qeydə almaq kimi müşahidəyə əsaslanan istifadə nümunələrə daha uyğundur.

3. Komponent tərifindəki nümunələri izləmək

Komponent tərifinə nümunə əlavə edilməsini və ya həmin tərifdəki nümunənin silinməsini izləmək üçün DefinitionObserver istifadə olunur. Aşağıdakı nümunədə observer aktiv modeldəki komponent tərifinə əlavə edilir.

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 izlənən tərifə yeni nümunə əlavə ediləndə çağırılır. onComponentInstanceRemoved isə tərifdəki nümunələrin silinməsi hadisəsini izləyir. Observer yalnız əlavə edildiyi tərifi izləyir; başqa tərif izlənəcəksə, observer həmin tərifə də əlavə edilməlidir. Nümunədəki definitions[0] aktiv modelin komponent təriflərindən birinə müraciət edir.

Silinmə callback-i üçün xüsusi istisna var: SketchUp-ın Move Tool-u tətbiq etmə üsuluna görə Move + Copy əməliyyatında, zahirən heç bir nümunə silinməsə də, onComponentInstanceRemoved işə düşə bilər. Buna görə callback-in işə düşməsini özlüyündə modeldən komponentin mütləq silindiyinin sübutu kimi qəbul etməyin.

Tez-tez rast gəlinən səhvlər və növbəti addımlar

İlk səhv hadisənin əhatə dairəsinə uyğun olmayan observer seçməkdir. Həndəsə kolleksiyasına element əlavə edilməsini izləmək ilə model səviyyəsində əməliyyatın başa çatmasını izləmək eyni ehtiyac deyil. Callback-i düzgün sinifdə müəyyənləşdirmək və observer-i hadisənin baş verdiyi kolleksiyaya, modelə və ya komponent tərifinə əlavə etmək lazımdır.

Digər səhv onElementRemoved parametrini hələ də istifadə edilə bilən element kimi qəbul etməkdir. Parametr silinmiş elementin identifikatorunu bildirir; sənədlərə görə silinmiş elementdən yalnız onun silindiyini anlamaq üçün istifadə olunmalıdır. DefinitionObserver daxilindəki silinmə hadisəsini şərh edərkən Move + Copy istisnasını da nəzərə alın.

Əməliyyat callback-ləri daxilində modeli redaktə etmək də risklidir. İlk sınaqlarda callback-ləri yalnız konsola məlumat yazdıracaq və ya hadisələri qeydə alacaq şəkildə qurun. Sonra hansı callback-in hansı istifadəçi əməliyyatı ilə işə düşdüyünü müşahidə edin. Əməliyyat axınındakı problemləri araşdırarkən başlanğıc, commit, boş əməliyyat və ləğv bildirişlərini bir-birindən ayırın; başlanğıc callback-inin əməliyyatın həqiqi başlanğıcını dərhal göstərmədiyini unutmayın.

Növbəti addım kimi bir hadisə növündən başlayıb əhatə dairəsini və vaxtlamanı yoxlayın. Ehtiyac dəqiqləşdikdə sinfə yalnız lazım olan callback-ləri əlavə edin. Bu üsul müşahidə kodunun məsuliyyətini məhdud saxlamağa və callback parametrlərinin nəyi ifadə etdiyini daha asan izləməyə kömək edir. Modeldə dəyişiklik edən iş axını lazımdırsa, observer callback-lərinin təhlükəsiz istifadə məhdudiyyətlərini ayrıca qiymətləndirin.

Mənbə və lisenziya

Bu bələdçi SketchUp Ruby API-nin EntitiesObserver, ModelObserver və DefinitionObserver sinifləri ilə bağlı rəsmi sənədlər əsasında hazırlanıb. Mənbələrin lisenziya bölməsində “sərbəst” məlumatı yer alır.