Как отслеживать события модели с помощью observer-классов SketchUp Ruby API?

Что вы узнаете из этого руководства?

Observer-классы в SketchUp Ruby API используются для реакции на события, происходящие с определённым объектом или коллекцией. В этом руководстве рассмотрим три области: EntitiesObserver для коллекции геометрии, ModelObserver для событий на уровне модели и DefinitionObserver для экземпляров определения компонента. Вы узнаете, как создать класс observer и подключить его к объекту, за которым нужно следить.

Этот подход можно использовать в расширениях для регистрации событий или отслеживания действий пользователя. Однако не стоит воспринимать observer как механизм, который мгновенно перехватывает каждое событие и позволяет безопасно менять модель. На структуру приложения влияют, в частности, время вызова callback операций, состояние удалённых объектов и исключения, связанные с работой некоторых инструментов.

Требования и выбор области наблюдения

Примеры основаны на классах и методах из документации SketchUp Ruby API. В источниках указано, что EntitiesObserver и DefinitionObserver доступны с SketchUp 6.0, onElementModified — с SketchUp 8.0, а callback для активной секущей плоскости — с SketchUp 2014. В документации ModelObserver описано, как работают события операций начиная с SketchUp 2016. Это сведения о версиях, приведённые в источниках для соответствующих возможностей API; дополнительные требования к версии SketchUp, типу учётной записи, оплате или оборудованию для этого руководства не указаны.

Сначала определите, в какой области происходит событие:

• Для событий элементов в коллекции Sketchup::Entities используется EntitiesObserver.

• Для сохранения модели, размещения компонентов и событий операций на уровне модели подходит ModelObserver.

• Для отслеживания добавления и удаления экземпляров, принадлежащих определённому определению компонента, используется DefinitionObserver.

Класс observer должен определять метод callback для события, за которым нужно следить. Затем экземпляр класса добавляется к соответствующей коллекции, модели или определению компонента. Приведённые ниже примеры выводят сообщения в консоль, чтобы можно было увидеть, какой callback сработал.

1. Отслеживание изменений в коллекции геометрии

EntitiesObserver отслеживает события в коллекции Sketchup::Entities. Следующий класс отдельно сообщает о добавлении, изменении и удалении элементов из коллекции. Для удаления одного или нескольких элементов также определён отдельный callback.

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)

В последней строке observer подключается к коллекции entities активной модели. onElementAdded вызывается при добавлении одного элемента, а onElementModified — при изменении одного или нескольких элементов коллекции. onElementRemoved сообщает об удалении одного элемента. Параметр, передаваемый в этот callback, следует использовать для распознавания события удаления, а не для дальнейшей работы с удалённым элементом. В документации указано, что удалённый элемент не следует использовать для других целей.

Если нужно отслеживать состояние секущей плоскости, в класс можно добавить метод onActiveSectionPlaneChanged(entities). Этот callback срабатывает, когда в соответствующей коллекции активируется секущая плоскость или отключается активная плоскость. Проверив entities.active_section_plane внутри callback, можно определить, есть ли активная плоскость. Добавляйте этот метод, только если нужно отслеживать события секущей плоскости.

2. Отслеживание событий на уровне модели

Для событий модели создайте подкласс Sketchup::ModelObserver. Следующий пример выводит отдельное сообщение, когда завершается операция с изменениями, операция без изменений или операция отменяется.

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 вызывается после завершения операции, изменившей модель; onTransactionEmpty — когда операция была начата и завершена без изменений. onTransactionAbort сообщает об отмене операции. В том же интерфейсе observer есть и callback для других событий, например размещения компонента, сохранения модели и открытия пользователем группы или компонента для редактирования.

Время вызова callback операций — важная особенность. Начиная с SketchUp 2016 события observer внутри операции ставятся в очередь и передаются после commit операции. Поэтому callback вроде onTransactionStart не срабатывает в реальном времени сразу после начала редактирования модели. Для операции с изменениями уведомление onTransactionCommit, а для завершённой без изменений операции — onTransactionEmpty поступает на этапе commit. Уведомление об отмене передаётся отдельно через onTransactionAbort; не следует определять этот callback так же, как уведомления о commit или пустой операции.

Согласно документации, API не предоставляет метода для проверки того, открыта ли в данный момент операция. Поэтому callback операций не подходят для отслеживания состояния операции в реальном времени. Источник рекомендует использовать их прежде всего для отчётности и отладки. Не запускайте внутри callback новую операцию, меняющую модель: документация предупреждает, что такие изменения могут привести к сбою или повреждению модели. Для примеров лучше подходит наблюдение без вмешательства — например, вывод в консоль или ведение журнала событий.

3. Отслеживание экземпляров в определении компонента

Чтобы отслеживать добавление экземпляров к определению компонента или удаление экземпляра из него, используйте DefinitionObserver. В следующем примере observer добавляется к одному из определений компонентов активной модели.

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 вызывается, когда к отслеживаемому определению добавляется новый экземпляр. onComponentInstanceRemoved отслеживает удаление экземпляров из определения. Observer следит только за тем определением, к которому он добавлен; если нужно отслеживать другое определение, observer нужно добавить и к нему. Выражение definitions[0] в примере обращается к одному из определений компонентов активной модели.

Для callback удаления есть особое исключение: из-за особенностей работы Move Tool в SketchUp onComponentInstanceRemoved может сработать при операции Move + Copy, даже если внешне ни один экземпляр не был удалён. Поэтому сам факт вызова callback не следует считать доказательством того, что компонент действительно удалён из модели.

Распространённые ошибки и дальнейшие шаги

Первая ошибка — выбирать observer, не соответствующий области события. Отслеживание добавления элементов в коллекцию геометрии и наблюдение за завершением операции на уровне модели — это разные задачи. Нужно определить callback в правильном классе и добавить observer к коллекции, модели или определению компонента, где происходит событие.

Другая ошибка — считать параметр onElementRemoved всё ещё доступным для работы элементом. Параметр сообщает идентификатор удалённого элемента; согласно документации, удалённый элемент следует использовать только для того, чтобы определить, что он был удалён. При интерпретации события удаления в DefinitionObserver также учитывайте исключение для Move + Copy.

Изменение модели внутри callback операции тоже сопряжено с риском. Для начала настройте callback так, чтобы он только выводил сведения в консоль или записывал события. Затем проверьте, какой callback срабатывает при каждом действии пользователя. При поиске проблем в потоке операций различайте уведомления о начале, commit, пустой операции и отмене; помните, что callback начала не отражает реальное начало операции мгновенно.

В качестве следующего шага начните с одного типа событий и проверьте область и время срабатывания. Когда требования станут понятны, добавьте в класс только необходимые callback. Это поможет ограничить задачи кода наблюдения и упростит понимание того, что именно представляют параметры callback. Если рабочий процесс должен менять модель, отдельно оцените безопасные границы использования callback observer.

Источник и лицензия

Это руководство адаптировано на основе официальной документации SketchUp Ruby API по классам EntitiesObserver, ModelObserver и DefinitionObserver. В поле лицензии источников указано «свободно».