SketchUp Ruby API observer sınıflarıyla model olayları nasıl izlenir?

Bu rehberde ne öğreneceksiniz?

SketchUp Ruby API’de observer sınıfları, belirli bir nesne veya koleksiyonda gerçekleşen olaylara yanıt vermek için kullanılır. Bu rehberde üç kapsamı ele alacağız: geometri koleksiyonu için EntitiesObserver, model düzeyindeki olaylar için ModelObserver ve bileşen tanımındaki örnekler için DefinitionObserver. Adımlarda observer sınıfının nasıl oluşturulacağını ve izlenecek nesneye nasıl bağlanacağını göreceksiniz.

Bu yöntem, eklentilerde olayları kaydetmek veya kullanıcı işlemlerini takip etmek için kullanılabilir. Ancak observer’ları her olayı anında yakalayan ve model üzerinde güvenle değişiklik yapabilen bir mekanizma gibi değerlendirmemek gerekir. Özellikle işlem callback’lerinin zamanlaması, kaldırılmış nesnelerin durumu ve bazı araç işlemlerinin oluşturduğu istisnalar uygulama tasarımını etkiler.

Gereksinimler ve kapsamı seçme

Örnekler SketchUp Ruby API dokümantasyonundaki sınıf ve metotlara dayanır. Kaynaklarda EntitiesObserver ve DefinitionObserver için SketchUp 6.0, onElementModified için SketchUp 8.0, etkin kesit düzlemi callback’i için SketchUp 2014 sürüm bilgisi veriliyor. ModelObserver dokümantasyonu ise işlem olaylarının SketchUp 2016’dan itibaren nasıl çalıştığını açıklıyor. Bunlar ilgili API özelliklerinin kaynakta belirtilen sürüm bilgileridir; rehber için ayrıca belirli bir SketchUp sürümü, hesap türü, ücret veya donanım gereksinimi belirtilmiyor.

Önce izlenecek olayın hangi kapsamda gerçekleştiğini belirleyin:

• Bir Sketchup::Entities koleksiyonundaki öğe olayları için EntitiesObserver kullanılır.

• Model düzeyindeki kaydetme, bileşen yerleştirme veya işlem olayları için ModelObserver tercih edilir.

• Belirli bir bileşen tanımına ait örneklerin eklenmesi ve kaldırılması için DefinitionObserver kullanılır.

Observer sınıfı, izlenecek olayın callback metodunu tanımlamalıdır. Ardından sınıfın bir örneği ilgili koleksiyona, modele veya bileşen tanımına eklenir. Aşağıdaki örnekler konsola mesaj yazar; böylece hangi callback’in çalıştığı gözlemlenebilir.

1. Geometri koleksiyonundaki değişiklikleri izleme

EntitiesObserver, bir Sketchup::Entities koleksiyonunda gerçekleşen olayları izler. Aşağıdaki sınıf; koleksiyona öğe eklenmesini, öğenin değiştirilmesini veya kaldırılmasını ayrı ayrı bildirir. Koleksiyondaki bir ya da daha fazla öğenin silinmesi için de ayrı bir callback tanımlar.

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 satırda observer, aktif modelin entities koleksiyonuna bağlanır. onElementAdded, tek bir öğe eklendiğinde; onElementModified, koleksiyondaki bir veya daha fazla öğe değiştirildiğinde çağrılır. onElementRemoved tek bir öğenin kaldırılmasını bildirir. Bu callback’e gelen parametre, kaldırılmış öğeyi yeniden kullanmak için değil, kaldırılma olayını tanımak için değerlendirilmelidir. Dokümantasyon, silinen öğenin bu amaç dışında kullanılmaması gerektiğini belirtiyor.

Kesit düzlemi durumunu da izlemek gerekiyorsa sınıfa onActiveSectionPlaneChanged(entities) metodu eklenebilir. Bu callback, ilgili koleksiyondaki bir kesit düzlemi etkinleştirildiğinde veya etkin düzlem devre dışı bırakıldığında çalışır. Callback içinde entities.active_section_plane kontrol edilerek etkin bir düzlem bulunup bulunmadığı anlaşılabilir. Bu metodu yalnızca kesit düzlemi olaylarına da ihtiyaç varsa ekleyin.

2. Model düzeyindeki olayları takip etme

Model genelindeki olaylar için Sketchup::ModelObserver alt sınıfı oluşturun. Aşağıdaki örnek, değişiklik içeren bir işlem tamamlandığında, değişiklik olmadan tamamlandığında veya işlem iptal edildiğinde ayrı mesajlar yazdırır.

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, modelde değişiklik yapan bir işlem tamamlandığında; onTransactionEmpty, başlatılıp herhangi bir değişiklik yapılmadan tamamlanan işlemde çağrılır. onTransactionAbort ise işlem iptal edildiğinde bildirim verir. Aynı observer arayüzünde bileşen yerleştirme, modelin kaydedilmesi ve kullanıcının bir grup ya da bileşeni düzenlemek üzere açması gibi başka olaylar için de callback’ler bulunur.

İşlem callback’lerinin zamanlaması önemli bir ayrıntıdır. SketchUp 2016’dan beri işlem içindeki observer olayları sıraya alınır ve işlem commit edildikten sonra iletilir. Bu nedenle onTransactionStart gibi callback’ler, model düzenlemesi başlar başlamaz gerçek zamanlı olarak çalışmaz. Değişiklik içeren işlem için onTransactionCommit, değişiklik yapılmadan tamamlanan işlem için onTransactionEmpty bildirimi commit aşamasında gelir. İptal bildirimi ise ayrı olarak onTransactionAbort üzerinden sağlanır; bu callback’i commit veya boş işlem bildirimleriyle aynı şekilde tanımlamayın.

Dokümantasyona göre API’de o sırada bir işlemin açık olup olmadığını sorgulayan bir metot bulunmuyor. Bu yüzden işlem callback’leri gerçek zamanlı işlem durumu takibi için uygun değildir. Kaynak, bunların öncelikle raporlama ve hata ayıklama amacıyla kullanılmasını öneriyor. Callback içinde modeli değiştiren yeni bir işlem başlatmaktan kaçının: dokümantasyon bu tür düzenlemelerin çökme veya model bozulması riski taşıyabileceği uyarısını yapıyor. Konsola yazmak veya olay kaydı tutmak gibi gözlem odaklı kullanım örneklere daha uygundur.

3. Bileşen tanımındaki örnekleri izleme

Bir bileşen tanımına örnek eklenmesini ya da bu tanımdaki bir örneğin kaldırılmasını takip etmek için DefinitionObserver kullanılır. Aşağıdaki örnekte observer, aktif modeldeki bir bileşen tanımına ekleniyor.

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, izlenen tanıma yeni bir örnek eklendiğinde çağrılır. onComponentInstanceRemoved ise tanımdaki örneklerin kaldırılması olayını izler. Observer yalnızca eklendiği tanımı takip eder; başka bir tanım izlenecekse observer o tanıma da eklenmelidir. Örnekteki definitions[0], aktif modelin bileşen tanımlarından birine erişir.

Kaldırılma callback’i için özel bir istisna vardır: SketchUp’ın Move Tool uygulama biçimi nedeniyle Move + Copy işleminde, görünürde bir örnek kaldırılmamış olsa bile onComponentInstanceRemoved çalışabilir. Bu nedenle callback’in tetiklenmesini tek başına modelden bir bileşenin kesin olarak silindiğinin kanıtı olarak değerlendirmeyin.

Yaygın hatalar ve sonraki adımlar

İlk hata, olay kapsamına uymayan observer seçmektir. Geometri koleksiyonuna öğe eklenmesini takip etmek ile model düzeyindeki işlem tamamlanmasını izlemek aynı ihtiyaç değildir. Callback’i doğru sınıfta tanımlamak ve observer’ı olayın gerçekleştiği koleksiyona, modele ya da bileşen tanımına eklemek gerekir.

Bir diğer hata, onElementRemoved parametresini hâlâ kullanılabilir bir öğe gibi ele almaktır. Parametre kaldırılan öğenin kimliğini bildirir; dokümantasyona göre silinmiş öğe, silindiğini anlamak dışında kullanılmamalıdır. DefinitionObserver içindeki kaldırılma olayını yorumlarken Move + Copy istisnasını da hesaba katın.

İşlem callback’leri içinde model düzenlemek de risklidir. İlk denemelerde callback’leri yalnızca konsola çıktı verecek veya olayları kaydedecek şekilde kurun. Ardından hangi callback’in hangi kullanıcı işlemiyle tetiklendiğini gözlemleyin. İşlem akışındaki sorunları araştırırken başlangıç, commit, boş işlem ve iptal bildirimlerini birbirinden ayırın; başlangıç callback’inin gerçek işlem başlangıcını anlık olarak göstermediğini unutmayın.

Sonraki adım olarak tek bir olay türüyle başlayıp kapsamı ve zamanlamayı doğrulayın. İhtiyaç netleştiğinde sınıfa yalnızca gereken callback’leri ekleyin. Bu yöntem, gözlem kodunun sorumluluğunu sınırlı tutmaya ve callback parametrelerinin neyi temsil ettiğini daha kolay izlemeye yardımcı olur. Model üzerinde değişiklik yapan bir iş akışı gerekiyorsa, observer callback’lerinin güvenli kullanım sınırlarını ayrıca değerlendirin.

Kaynak ve lisans

Bu rehber, SketchUp Ruby API’nin EntitiesObserver, ModelObserver ve DefinitionObserver sınıflarına ilişkin resmi dokümantasyonundan uyarlanmıştır. Kaynakların lisans alanında “serbest” bilgisi yer alıyor.