¿Cómo seguir los eventos del modelo con observers de SketchUp Ruby API?

¿Qué aprenderás en esta guía?

En SketchUp Ruby API, las clases observer se utilizan para responder a eventos que tienen lugar en un objeto o una colección determinados. En esta guía veremos tres ámbitos: EntitiesObserver para una colección de geometría, ModelObserver para eventos del modelo y DefinitionObserver para instancias de definiciones de componentes. En los pasos, aprenderás a crear una clase observer y asociarla al objeto que quieres supervisar.

Este método puede utilizarse en extensiones para registrar eventos o seguir las acciones del usuario. Sin embargo, no conviene considerar los observers un mecanismo que detecta todos los eventos de inmediato y permite modificar el modelo de forma segura. En particular, el momento en que se ejecutan los callbacks de operaciones, el estado de los objetos eliminados y las excepciones generadas por algunas herramientas pueden influir en el diseño de la aplicación.

Requisitos y elección del ámbito

Los ejemplos se basan en las clases y los métodos de la documentación de SketchUp Ruby API. Las fuentes indican SketchUp 6.0 para EntitiesObserver y DefinitionObserver, SketchUp 8.0 para onElementModified y SketchUp 2014 para el callback del plano de sección activo. La documentación de ModelObserver explica cómo funcionan los eventos de operación desde SketchUp 2016. Estas son las versiones indicadas en las fuentes para las funciones pertinentes de la API; la guía no especifica requisitos adicionales de versión de SketchUp, tipo de cuenta, precio ni hardware.

Primero, determina en qué ámbito se produce el evento que quieres seguir:

• Para eventos de elementos de una colección Sketchup::Entities, utiliza EntitiesObserver.

• Para eventos del modelo, como guardar, insertar componentes o finalizar operaciones, elige ModelObserver.

• Para seguir la adición y eliminación de instancias de una definición de componente específica, utiliza DefinitionObserver.

La clase observer debe definir el método callback correspondiente al evento que quieres seguir. Después, se añade una instancia de la clase a la colección, el modelo o la definición de componente correspondiente. Los siguientes ejemplos escriben mensajes en la consola para que puedas observar qué callback se ejecuta.

1. Seguir cambios en una colección de geometría

EntitiesObserver sigue los eventos que tienen lugar en una colección Sketchup::Entities. La siguiente clase informa por separado cuando se añade, modifica o elimina un elemento de la colección. También define un callback independiente para la eliminación de uno o varios elementos.

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)

En la última línea, el observer se asocia a la colección entities del modelo activo. onElementAdded se ejecuta cuando se añade un elemento; onElementModified, cuando se modifica uno o varios elementos de la colección. onElementRemoved informa de la eliminación de un único elemento. El parámetro recibido por este callback debe servir para identificar el evento de eliminación, no para volver a utilizar el elemento eliminado. La documentación indica que el elemento eliminado no debe utilizarse para ningún otro fin.

Si también necesitas seguir el estado del plano de sección, puedes añadir a la clase el método onActiveSectionPlaneChanged(entities). Este callback se ejecuta cuando se activa un plano de sección de la colección correspondiente o cuando se desactiva el plano activo. Dentro del callback, puedes comprobar si hay un plano activo mediante entities.active_section_plane. Añade este método solo si también necesitas eventos de planos de sección.

2. Seguir eventos del modelo

Para los eventos generales del modelo, crea una subclase de Sketchup::ModelObserver. El siguiente ejemplo escribe mensajes distintos cuando finaliza una operación con cambios, cuando termina sin cambios o cuando se cancela.

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 se ejecuta cuando finaliza una operación que modifica el modelo; onTransactionEmpty, cuando una operación iniciada termina sin que se haya realizado ningún cambio. onTransactionAbort informa cuando se cancela una operación. La misma interfaz observer incluye también callbacks para otros eventos, como insertar componentes, guardar el modelo y abrir un grupo o componente para editarlo.

El momento en que se ejecutan los callbacks de operaciones es un detalle importante. Desde SketchUp 2016, los eventos observer de una operación se ponen en cola y se envían después de que se confirme la operación. Por eso, callbacks como onTransactionStart no se ejecutan en tiempo real en cuanto comienza la edición del modelo. Para una operación con cambios, la notificación onTransactionCommit; para una operación que termina sin cambios, la notificación onTransactionEmpty se envía durante la fase de commit. La cancelación se notifica por separado mediante onTransactionAbort; no trates este callback como si fuera igual a las notificaciones de commit o de operación vacía.

Según la documentación, la API no cuenta con un método para consultar si hay una operación abierta en ese momento. Por eso, los callbacks de operaciones no son adecuados para seguir en tiempo real el estado de una operación. La fuente recomienda utilizarlos principalmente para informar y depurar. Evita iniciar una nueva operación que modifique el modelo dentro de un callback: la documentación advierte que este tipo de cambios puede provocar fallos o daños en el modelo. Los usos centrados en la observación, como escribir en la consola o registrar eventos, son más apropiados para estos ejemplos.

3. Seguir instancias de una definición de componente

Utiliza DefinitionObserver para seguir la adición de instancias a una definición de componente o la eliminación de una instancia de esa definición. En el siguiente ejemplo, el observer se añade a una definición de componente del modelo activo.

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 se ejecuta cuando se añade una instancia a la definición supervisada. onComponentInstanceRemoved sigue la eliminación de instancias de esa definición. El observer solo supervisa la definición a la que se ha añadido; si quieres seguir otra definición, también debes añadirle el observer. En el ejemplo, definitions[0] accede a una de las definiciones de componente del modelo activo.

Hay una excepción específica para el callback de eliminación: debido a la forma en que SketchUp implementa Move Tool, durante una operación Move + Copy puede ejecutarse onComponentInstanceRemoved aunque aparentemente no se haya eliminado ninguna instancia. Por tanto, no consideres que la ejecución del callback demuestra por sí sola que un componente se haya eliminado definitivamente del modelo.

Errores frecuentes y próximos pasos

El primer error consiste en elegir un observer que no corresponde al ámbito del evento. Seguir la adición de elementos a una colección de geometría no es lo mismo que seguir la finalización de una operación a nivel del modelo. Debes definir el callback en la clase adecuada y añadir el observer a la colección, el modelo o la definición de componente donde se produce el evento.

Otro error es tratar el parámetro de onElementRemoved como si siguiera siendo un elemento utilizable. El parámetro identifica el elemento eliminado; según la documentación, el objeto borrado no debe utilizarse más que para reconocer que se eliminó. Al interpretar el evento de eliminación de DefinitionObserver, ten en cuenta también la excepción de Move + Copy.

Modificar el modelo dentro de los callbacks de operaciones también entraña riesgos. En las primeras pruebas, configura los callbacks para que solo escriban en la consola o registren eventos. Después, observa qué callbacks se activan con cada acción del usuario. Al investigar problemas en el flujo de operaciones, distingue entre las notificaciones de inicio, commit, operación vacía y cancelación; recuerda que el callback de inicio no refleja en tiempo real el inicio efectivo de la operación.

Como siguiente paso, empieza con un solo tipo de evento y comprueba su ámbito y el momento en que se ejecuta. Cuando tengas claro lo que necesitas, añade únicamente los callbacks necesarios. Así podrás mantener acotada la responsabilidad del código de observación y comprender con mayor facilidad qué representa cada parámetro de callback. Si necesitas un flujo de trabajo que modifique el modelo, evalúa por separado los límites de uso seguro de los callbacks observer.

Fuentes y licencia

Esta guía se ha adaptado de la documentación oficial de SketchUp Ruby API sobre las clases EntitiesObserver, ModelObserver y DefinitionObserver. En el campo de licencia de las fuentes figura la información «libre».