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

Kaynak: https://3dsinifi.com/haber/sketchup-ruby-api-observer-siniflariyla-model-olaylari · Kategori: Eğitimler · Yayın: 14 Kasım 2026

> SketchUp Ruby API’deki EntitiesObserver, ModelObserver ve DefinitionObserver; geometri, model işlemleri ve bileşen olaylarını izlemeye yarıyor. Bu rehberde kurulum adımları ve callback’lerin önemli sınırları ele alınıyor.

## Kısaca
- EntitiesObserver ile bir Entities koleksiyonuna öğe ekleme, değiştirme ve kaldırma olayları izlenebilir.
- ModelObserver; kaydetme, bileşen yerleştirme ve işlem tamamlanması gibi model olayları için callback’ler sunar.
- İşlem değişikliklerinin commit ve boş işlem bildirimleri commit aşamasında iletilir; işlem iptali için onTransactionAbort callback’i bulunur.
- DefinitionObserver, bileşen tanımına örnek eklenmesi veya kaldırılması olaylarını takip edebilir.

## 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.

```ruby
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.

```ruby
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.

```ruby
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.

## Pro ipucu
İlk denemede callback’leri yalnızca konsola kayıt yazdıracak şekilde kurun; işlem observer’larının içinde model düzenlemesi yapmayın.

## 3dsınıfı yorumu
Türkiye’deki mimarlık ofisleri ve görselleştirme ekipleri için observer’lar, SketchUp eklentilerinde model olaylarını takip etmeyi ve hata ayıklamayı daha düzenli hâle getirebilir. Geometri veya bileşen hareketlerini izleyen araçlar geliştirenler, doğru observer kapsamını seçerek işe başlayabilir.

Kaynaklar ücret, donanım gereksinimi veya dağıtım koşulları hakkında bilgi vermiyor; bu nedenle bu başlıklarda genelleme yapmak doğru olmaz. Uygulamada özellikle işlem callback’lerinin gecikmeli çalışmasına ve callback içinde model düzenlemenin riskine dikkat edilmeli. Bu yaklaşım, gerçek zamanlı kontrol yerine olay kaydı ve izleme ihtiyacına daha uygun görünüyor.

## Kaynaklar
- [ruby.sketchup.com](https://ruby.sketchup.com/Sketchup/EntitiesObserver.html) (özet)
- [ruby.sketchup.com](https://ruby.sketchup.com/Sketchup/ModelObserver.html) (özet)
- [ruby.sketchup.com](https://ruby.sketchup.com/Sketchup/DefinitionObserver.html) (özet)

_Yapay zekâ ile yazıldı, kaynaklarla doğrulandı. © 3dsınıfı_