SketchUp Ruby API: Modellereignisse mit Observer-Klassen überwachen

Was erfahren Sie in diesem Leitfaden?

Observer-Klassen der SketchUp Ruby API reagieren auf Ereignisse, die an einem bestimmten Objekt oder in einer Sammlung auftreten. Dieser Leitfaden behandelt drei Bereiche: EntitiesObserver für Geometriesammlungen, ModelObserver für Ereignisse auf Modellebene und DefinitionObserver für Instanzen einer Komponentendefinition. Sie erfahren, wie Sie eine Observer-Klasse erstellen und sie mit dem zu überwachenden Objekt verknüpfen.

Diese Methode kann in Erweiterungen dazu dienen, Ereignisse zu protokollieren oder Benutzeraktionen nachzuverfolgen. Observer sollten jedoch nicht als Mechanismus verstanden werden, der jedes Ereignis sofort erfasst und sichere Änderungen am Modell erlaubt. Insbesondere der Zeitpunkt von Transaktions-Callbacks, der Zustand gelöschter Objekte und Ausnahmen bei bestimmten Werkzeugaktionen beeinflussen das Anwendungsdesign.

Voraussetzungen und Auswahl des Geltungsbereichs

Die Beispiele basieren auf Klassen und Methoden aus der Dokumentation der SketchUp Ruby API. Für EntitiesObserver und DefinitionObserver ist in den Quellen SketchUp 6.0 angegeben, für onElementModified SketchUp 8.0 und für den Callback zur aktiven Schnittebene SketchUp 2014. Die Dokumentation zu ModelObserver erläutert, wie Transaktionsereignisse ab SketchUp 2016 funktionieren. Das sind die in den Quellen genannten Versionsangaben zu den jeweiligen API-Funktionen; für den Leitfaden werden keine zusätzlichen Anforderungen an eine bestimmte SketchUp-Version, einen Kontotyp, Kosten oder Hardware genannt.

Legen Sie zunächst fest, in welchem Geltungsbereich das zu überwachende Ereignis auftritt:

• Für Ereignisse zu Elementen in einer Sketchup::Entities-Sammlung wird EntitiesObserver verwendet.

• Für Speichern, das Platzieren von Komponenten oder Transaktionsereignisse auf Modellebene eignet sich ModelObserver.

• Zum Hinzufügen und Entfernen von Instanzen einer bestimmten Komponentendefinition wird DefinitionObserver verwendet.

Die Observer-Klasse muss die Callback-Methode für das zu überwachende Ereignis definieren. Anschließend wird eine Instanz der Klasse der jeweiligen Sammlung, dem Modell oder der Komponentendefinition hinzugefügt. Die folgenden Beispiele geben eine Meldung in der Konsole aus, sodass sich beobachten lässt, welcher Callback aufgerufen wird.

1. Änderungen an einer Geometriesammlung überwachen

EntitiesObserver überwacht Ereignisse in einer Sketchup::Entities-Sammlung. Die folgende Klasse meldet separat, wenn der Sammlung ein Element hinzugefügt, ein Element geändert oder entfernt wird. Für das Löschen eines oder mehrerer Elemente in der Sammlung ist ebenfalls ein eigener Callback definiert.

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)

In der letzten Zeile wird der Observer mit der entities-Sammlung des aktiven Modells verknüpft. onElementAdded wird aufgerufen, wenn ein einzelnes Element hinzugefügt wird; onElementModified, wenn ein oder mehrere Elemente in der Sammlung geändert werden. onElementRemoved meldet das Entfernen eines einzelnen Elements. Der an diesen Callback übergebene Parameter sollte nicht dazu verwendet werden, das entfernte Element weiterzuverwenden, sondern dient dazu, das Entfernen zu erkennen. Die Dokumentation weist darauf hin, dass das gelöschte Element darüber hinaus nicht verwendet werden sollte.

Wenn Sie auch den Status der Schnittebene überwachen müssen, können Sie der Klasse die Methode onActiveSectionPlaneChanged(entities) hinzufügen. Dieser Callback wird aufgerufen, wenn eine Schnittebene in der betreffenden Sammlung aktiviert oder die aktive Ebene deaktiviert wird. Mit entities.active_section_plane im Callback lässt sich prüfen, ob eine aktive Ebene vorhanden ist. Fügen Sie diese Methode nur hinzu, wenn Sie auch Ereignisse zu Schnittebenen benötigen.

2. Ereignisse auf Modellebene verfolgen

Erstellen Sie für Ereignisse auf Modellebene eine Unterklasse von Sketchup::ModelObserver. Das folgende Beispiel gibt bei einer abgeschlossenen Transaktion mit Änderungen, einer abgeschlossenen Transaktion ohne Änderungen und einer abgebrochenen Transaktion jeweils eine eigene Meldung aus.

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 wird aufgerufen, wenn eine Transaktion mit Änderungen am Modell abgeschlossen wird; onTransactionEmpty wird bei einer gestarteten, aber ohne Änderungen abgeschlossenen Transaktion aufgerufen. onTransactionAbort meldet dagegen, dass eine Transaktion abgebrochen wurde. Dieselbe Observer-Schnittstelle bietet auch Callbacks für weitere Ereignisse, etwa das Platzieren einer Komponente, das Speichern des Modells und das Öffnen einer Gruppe oder Komponente zur Bearbeitung durch den Benutzer.

Der Zeitpunkt der Transaktions-Callbacks ist ein wichtiger Aspekt. Seit SketchUp 2016 werden Observer-Ereignisse innerhalb einer Transaktion in eine Warteschlange gestellt und erst nach dem Commit der Transaktion übermittelt. Daher werden Callbacks wie onTransactionStart nicht in Echtzeit aufgerufen, sobald die Modellbearbeitung beginnt. Bei einer Transaktion mit Änderungen wird onTransactionCommit in der Commit-Phase ausgelöst, bei einer ohne Änderungen abgeschlossenen Transaktion onTransactionEmpty. Für einen Abbruch gibt es separat onTransactionAbort; dieser Callback sollte nicht wie die Benachrichtigungen für einen Commit oder eine leere Transaktion behandelt werden.

Laut Dokumentation gibt es in der API keine Methode, um abzufragen, ob gerade eine Transaktion geöffnet ist. Transaktions-Callbacks eignen sich daher nicht zur Echtzeitüberwachung des Transaktionsstatus. Die Quelle empfiehlt, sie vor allem für Berichte und zum Debuggen zu verwenden. Vermeiden Sie es, im Callback eine neue Transaktion zu starten, die das Modell verändert: Die Dokumentation warnt, dass solche Änderungen zum Absturz oder zur Beschädigung des Modells führen können. Beobachtende Einsatzzwecke wie Konsolenausgaben oder Ereignisprotokolle eignen sich besser.

3. Instanzen einer Komponentendefinition überwachen

Mit DefinitionObserver lässt sich verfolgen, ob einer Komponentendefinition eine Instanz hinzugefügt oder eine Instanz aus dieser Definition entfernt wird. Im folgenden Beispiel wird der Observer einer Komponentendefinition im aktiven Modell hinzugefügt.

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 wird aufgerufen, wenn der überwachten Definition eine neue Instanz hinzugefügt wird. onComponentInstanceRemoved überwacht das Entfernen von Instanzen aus der Definition. Der Observer verfolgt nur die Definition, der er hinzugefügt wurde; soll eine andere Definition überwacht werden, muss der Observer auch dieser hinzugefügt werden. Das Beispiel greift mit definitions[0] auf eine der Komponentendefinitionen des aktiven Modells zu.

Für den Callback zum Entfernen gibt es eine besondere Ausnahme: Aufgrund der Implementierung des Move Tools in SketchUp kann onComponentInstanceRemoved bei Move + Copy ausgelöst werden, selbst wenn dem Anschein nach keine Instanz entfernt wurde. Werten Sie den Aufruf dieses Callbacks daher nicht allein als Beweis dafür, dass eine Komponente tatsächlich aus dem Modell gelöscht wurde.

Häufige Fehler und nächste Schritte

Ein häufiger Fehler ist die Wahl eines Observers, der nicht zum Geltungsbereich des Ereignisses passt. Das Hinzufügen eines Elements zu einer Geometriesammlung zu verfolgen, ist nicht dasselbe wie den Abschluss einer Transaktion auf Modellebene zu überwachen. Definieren Sie den Callback in der passenden Klasse und fügen Sie den Observer der Sammlung, dem Modell oder der Komponentendefinition hinzu, in der das Ereignis auftritt.

Ein weiterer Fehler ist, den Parameter von onElementRemoved wie ein weiterhin verwendbares Element zu behandeln. Der Parameter gibt die ID des entfernten Elements an; laut Dokumentation sollte das gelöschte Element nur dazu verwendet werden, das Entfernen zu erkennen. Berücksichtigen Sie bei der Auswertung des Entfernungsereignisses in DefinitionObserver auch die Move + Copy-Ausnahme.

Auch Modelländerungen innerhalb von Transaktions-Callbacks sind riskant. Richten Sie die Callbacks bei ersten Versuchen so ein, dass sie nur Ausgaben in der Konsole erzeugen oder Ereignisse protokollieren. Beobachten Sie anschließend, welcher Callback durch welche Benutzeraktion ausgelöst wird. Wenn Sie Probleme im Transaktionsablauf untersuchen, unterscheiden Sie zwischen Benachrichtigungen zu Start, Commit, leerer Transaktion und Abbruch. Beachten Sie dabei, dass der Start-Callback den tatsächlichen Beginn der Transaktion nicht in Echtzeit anzeigt.

Beginnen Sie als Nächstes mit einem einzelnen Ereignistyp und überprüfen Sie dessen Geltungsbereich und Zeitpunkt. Sobald der Bedarf klar ist, fügen Sie der Klasse nur die benötigten Callbacks hinzu. So bleibt die Zuständigkeit des Beobachtungscodes begrenzt, und es lässt sich leichter nachvollziehen, wofür die Callback-Parameter stehen. Wenn ein Workflow Änderungen am Modell erfordert, sollten Sie die sicheren Einsatzgrenzen von Observer-Callbacks gesondert prüfen.

Quelle und Lizenz

Dieser Leitfaden basiert auf der offiziellen Dokumentation der SketchUp Ruby API zu den Klassen EntitiesObserver, ModelObserver und DefinitionObserver. In den Lizenzangaben der Quellen steht „frei“.