How to Track Model Events with SketchUp Ruby API Observer Classes

What will you learn in this guide?

In the SketchUp Ruby API, observer classes respond to events that occur on a specific object or collection. This guide covers three scopes: EntitiesObserver for geometry collections, ModelObserver for model-level events, and DefinitionObserver for instances in a component definition. You’ll learn how to create an observer class and attach it to the object you want to monitor.

This approach can be used in extensions to log events or track user actions. However, observers shouldn’t be treated as a mechanism that instantly catches every event and can safely modify the model. In particular, transaction callback timing, the state of removed objects, and exceptions caused by certain tool operations can all affect how an extension is designed.

Requirements and choosing a scope

The examples are based on classes and methods in the SketchUp Ruby API documentation. The sources list SketchUp 6.0 for EntitiesObserver and DefinitionObserver, SketchUp 8.0 for onElementModified, and SketchUp 2014 for the active section plane callback. The ModelObserver documentation explains how transaction events work from SketchUp 2016 onward. These are the version details specified in the sources for the relevant API features; no particular SketchUp version, account type, fee, or hardware requirement is otherwise specified for this guide.

First, determine the scope in which the event you want to track occurs:

• Use EntitiesObserver for item events in a Sketchup::Entities collection.

• Use ModelObserver for model-level saving, component placement, or transaction events.

• Use DefinitionObserver to track instances being added to or removed from a specific component definition.

The observer class must define the callback method for the event you want to track. Then, add an instance of the class to the relevant collection, model, or component definition. The examples below print messages to the console so you can see which callback runs.

1. Track changes in a geometry collection

EntitiesObserver tracks events that occur in a Sketchup::Entities collection. The class below reports when an item is added, modified, or removed. It also defines a separate callback for when one or more items in the collection are erased.

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 the final line, the observer is attached to the active model’s entities collection. onElementAdded runs when an item is added; onElementModified runs when one or more items in the collection are modified. onElementRemoved reports the removal of a single item. Its parameter should be used to identify the removal event, not to reuse the removed item. The documentation says the deleted item should not be used for any other purpose.

If you also need to track section plane status, you can add an onActiveSectionPlaneChanged(entities) method to the class. This callback runs when a section plane in the relevant collection is activated or when the active plane is deactivated. You can check entities.active_section_plane inside the callback to determine whether an active plane exists. Add this method only if you also need section plane events.

2. Track model-level events

For model-wide events, create a subclass of Sketchup::ModelObserver. The example below prints a separate message when a transaction with changes is completed, when a transaction is completed without changes, or when a transaction is aborted.

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 runs when a transaction that modifies the model is completed; onTransactionEmpty runs when a transaction is started and completed without any changes. onTransactionAbort reports when a transaction is aborted. The same observer interface also includes callbacks for other events, such as component placement, saving the model, and the user opening a group or component for editing.

Transaction callback timing is an important detail. Since SketchUp 2016, observer events inside a transaction are queued and delivered after the transaction is committed. As a result, callbacks such as onTransactionStart don’t run in real time as soon as model editing begins. For a transaction with changes, onTransactionCommit is reported at commit time; for a transaction completed without changes, onTransactionEmpty is reported at commit time. Aborted transactions are reported separately through onTransactionAbort; don’t treat this callback as equivalent to the commit or empty-transaction notifications.

According to the documentation, the API doesn’t provide a method for checking whether a transaction is currently open. For this reason, transaction callbacks aren’t suitable for tracking transaction state in real time. The sources recommend using them primarily for reporting and debugging. Avoid starting a new transaction that modifies the model inside a callback: the documentation warns that such edits may risk a crash or model corruption. Observation-focused uses, such as writing to the console or logging events, are better suited to these callbacks.

3. Track instances in a component definition

Use DefinitionObserver to track instances being added to a component definition or an instance in that definition being removed. In the example below, the observer is added to a component definition in the active model.

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 runs when a new instance is added to the observed definition. onComponentInstanceRemoved tracks the removal of instances from the definition. An observer monitors only the definition to which it was added; to monitor another definition, add the observer to that definition as well. In the example, definitions[0] accesses one of the active model’s component definitions.

There is a special case for the removal callback: due to how SketchUp’s Move Tool is implemented, onComponentInstanceRemoved may run during a Move + Copy operation even though no instance appears to have been removed. So don’t treat the callback being triggered, by itself, as proof that a component was definitively deleted from the model.

Common mistakes and next steps

The first mistake is choosing an observer that doesn’t match the scope of the event. Tracking an item being added to a geometry collection is not the same need as tracking the completion of a model-level transaction. Define the callback in the right class and add the observer to the collection, model, or component definition where the event occurs.

Another mistake is treating the onElementRemoved parameter as an item that can still be used. The parameter identifies the removed item; according to the documentation, the deleted item should only be used to determine that it was deleted. When interpreting a removal event in DefinitionObserver, also account for the Move + Copy exception.

Modifying the model inside transaction callbacks is also risky. In early tests, configure callbacks to only print to the console or log events. Then observe which callback is triggered by each user action. When investigating issues in the transaction flow, distinguish between start, commit, empty-transaction, and abort notifications; remember that the start callback doesn’t report the actual start of a transaction in real time.

As a next step, start with a single event type and verify its scope and timing. Once your needs are clear, add only the callbacks you need. This helps keep observation code focused and makes it easier to understand what each callback parameter represents. If your workflow needs to modify the model, assess the safe-use limits of observer callbacks separately.

Source and license

This guide is adapted from the official SketchUp Ruby API documentation for the EntitiesObserver, ModelObserver, and DefinitionObserver classes. The sources list the license as “free.”