My favorites | English | Sign in

Google SketchUp Ruby API

ModelObserver

interface

Parent: Object

Introduction

SketchUp 6.0+

This observer interface is implemented to react to model events. To implement this observer, create a Ruby class of this type, override the desired methods, and add an instance of the observer to the model.

Note that the observers related to transactions (aka undoable operations) are primarily for reporting and debugging. Performing any edit operations of your own (such as modifying the model) inside the observer callback should be avoided, as it could cause crashes or model corruption. The most common use for these callbacks is to help debug problems where your Ruby script's Model.start_operation and Model.commit_operation calls are somehow conflicting with Sketchup's native undo operations. You can set up an observer set to watch precisely what is going on.

     # This is an example of an observer that watches the materials collection
     # for new materials and shows a messagebox.
     class MyModelObserver < Sketchup::ModelObserver
       def onMaterialAdd(materials, material)
         UI.messagebox("onMaterialAdd: " + material.to_s)
       end
     end

     # Attach the observer.
     Sketchup.active_model.add_observer(MyModelObserver.new)

Methods

ModelObserver.onActivePathChangedSketchUp 7.0+

The onActivePathChanged method is invoked when the user opens or closes a Component or Group for editing.

When in "edit mode" (aka a Component is being edited), the Ruby API returns object transformations and locations in context of the "local" component axes instead of the global axes. If you plugin is actively manipulating entities in global space, then you will need to correct your transformations to account for the different coordinate systems at play.

See Model.active_path and Model.edit_transform for methods that report the current edit origin vs. the global origin, etc.

By using this observer callback, you can keep track of the various nested transformations as your users double click to drill into and out of component edits.

Arguments:

model
A Model object.

Returns:

nil
 # As the user double clicks into component edits, show the "path" along
 # the model hierarchyu they have followed to get here.
 def onActivePathChanged(model)
   UI.messagebox("onActivePathChanged: " + model.active_path.to_s)
 end

ModelObserver.onAfterComponentSaveAsSketchUp 7.0+

The onAfterComponentSaveAs method is invoked when the user context-clicks > Save As on a component instance. It is called just after the component is written to disk, so you can restore the component to some state before returning control to the user.

See ModelObserver.onBeforeComponentSaveAs for more details.

Arguments:

model
A Model object.

Returns:

nil
 def onAfterComponentSaveAs(model)
   UI.messagebox("onAfterComponentSaveAs: " + model.to_s)
 end

ModelObserver.onBeforeComponentSaveAsSketchUp 7.0+

The onBeforeComponentSaveAs method is invoked when the user context-clicks > Save As on a component instance. It is called just before the component is written to disk, so you can make changes within the handler and it will make it into the save.

For example, you may decide that you want to add some attribute to every component that is saved out, but you do not want that attribute sticking around inside the current model. Within onBeforeComponentSaveAs you could add the attribute, and within onAfterComponentSaveAs you could delete that attribute.

The callback is not sent the component that is to be saved, but the model's selection will contain it.

Arguments:

model
A Model object.

Returns:

nil
 # Show which component is about to be saved.
 def onBeforeComponentSaveAs(model)
   UI.messagebox("onBeforeComponentSaveAs: " + model.selection[0].to_s)
 end

ModelObserver.onDeleteModelSketchUp 6.0+

The onDeleteModel method is invoked when a model is deleted.

Arguments:

model
A Model object.

Returns:

nil
 def onDeleteModel(model)
   UI.messagebox("onDeleteModel: " + model.to_s)
 end

ModelObserver.onEraseAllSketchUp 6.0+

The onEraseAll method is invoked when everything in a model is erased.

Arguments:

model
A Model object.

Returns:

nil
 def onEraseAll(model)
   UI.messagebox("onEraseAll: " + model.to_s)
 end

ModelObserver.onExplodeSketchUp 7.0+

The onExplode method is invoked whenever a component anywhere in this model is exploded. This is an easier way to watch explode events vs. attaching an InstanceObserver to every instance in the model.

Since the callback does not return what was exploded, one solution is to place a selection observer that keeps track of which entities whose explosion you are interested in are in the selection. Since SketchUp's user interface only provides a means of exploding the selection, this method is a reliable way to know what was just exploded.

Another method would be to watch the definition.count_instances to determine what just changed, as any components that were exploded will now be less an instance.

Arguments:

model
A Model object.

Returns:

nil
 def onExplode(model)
   UI.messagebox("onExplode: " + model.to_s)
 end

ModelObserver.onPlaceComponentSketchUp 7.0+

The onPlaceComponent method is invoked when a component is "placed" into the model, meaning it is dragged from the Component Browser.

Arguments:

instance
A ComponentInstance object.

Returns:

nil
 def onPlaceComponent(instance)
   UI.messagebox("onPlaceComponent: " + instance.to_s)
 end

ModelObserver.onSaveModelSketchUp 6.0+

The onSaveModel method is invoked when a model is saved to disk.

Arguments:

model
A Model object.

Returns:

nil
 def onSaveModel(model)
   UI.messagebox("onSaveModel: " + model.to_s)
 end

ModelObserver.onTransactionAbortSketchUp 6.0+

The onTransactionAbort method is invoked when a transaction is aborted. See Model.abort_operation.

Arguments:

model
A Model object.

Returns:

nil
 def onTransactionAbort(model)
   UI.messagebox("onTransactionAbort: " + model.to_s)
 end

ModelObserver.onTransactionCommitSketchUp 6.0+

The onTransactionCommit method is invoked when a transaction is completed. See model.commit_operation.

Arguments:

model
A Model object.

Returns:

nil
 def onTransactionCommit(model)
   UI.messagebox("onTransactionCommit: " + model.to_s)
 end

ModelObserver.onTransactionEmptySketchUp 6.0+

The onTransactionEmpty method is invoked when a transaction (aka an undoable operation) starts and then is committed without anything being altered in between. See Model.start_operation.

Arguments:

model
A Model object.

Returns:

nil
 def onTransactionEmpty(model)
   UI.messagebox("onTransactionEmpty: " + model.to_s)
 end

ModelObserver.onTransactionRedoSketchUp 6.0+

The onTransactionRedo method is invoked when the user "redoes" a transaction (aka undo operation.) You can programatically fire a redo by calling Sketchup.sendAction("editRedo").

Arguments:

model
A Model object.

Returns:

nil
 def onTransactionRedo(model)
   UI.messagebox("onTransactionRedo: " + model.to_s)
 end

ModelObserver.onTransactionStartSketchUp 6.0+

The onTransactionStart method is invoked when a transaction (aka an undoable operation) starts. See Model.start_operation.

Arguments:

model
A Model object.

Returns:

nil
 def onTransactionStart(model)
   UI.messagebox("onTransactionStart: " + model.to_s)
 end

ModelObserver.onTransactionUndoSketchUp 6.0+

The onTransactionUndo method is invoked when the user "undoes" a transaction (aka undo operation.) You can programatically fire an undo by calling Sketchup.sendAction("editUndo").

Arguments:

model
A Model object.

Returns:

nil
 def onTransactionUndo(model)
   UI.messagebox("onTransactionUndo: " + model.to_s)
 end