Comment suivre les événements d’un modèle avec les classes observer de l’API Ruby de SketchUp ?

Ce que vous allez apprendre dans ce guide

Dans l’API Ruby de SketchUp, les classes observer servent à réagir aux événements qui se produisent sur un objet ou une collection donnés. Ce guide aborde trois niveaux : EntitiesObserver pour les collections de géométrie, ModelObserver pour les événements liés au modèle et DefinitionObserver pour les instances d’une définition de composant. Vous verrez comment créer une classe observer et l’associer à l’objet à surveiller.

Cette méthode peut servir à consigner des événements dans des extensions ou à suivre les actions de l’utilisateur. Toutefois, les observers ne doivent pas être considérés comme un mécanisme capable de détecter immédiatement chaque événement et de modifier le modèle sans risque. Le moment où les callbacks d’opération sont exécutés, l’état des objets supprimés et les exceptions liées à certains outils influent notamment sur la conception de l’application.

Prérequis et choix du périmètre

Les exemples s’appuient sur les classes et méthodes de la documentation de l’API Ruby de SketchUp. Les sources indiquent SketchUp 6.0 pour EntitiesObserver et DefinitionObserver, SketchUp 8.0 pour onElementModified, et SketchUp 2014 pour le callback du plan de coupe actif. La documentation de ModelObserver explique quant à elle le fonctionnement des événements d’opération à partir de SketchUp 2016. Il s’agit des informations de version mentionnées dans les sources pour les fonctionnalités API concernées ; aucun prérequis particulier concernant la version de SketchUp, le type de compte, le tarif ou le matériel n’est indiqué pour ce guide.

Commencez par déterminer à quel niveau se produit l’événement à suivre :

• Utilisez EntitiesObserver pour les événements liés aux éléments d’une collection Sketchup::Entities.

• Privilégiez ModelObserver pour les événements au niveau du modèle, comme l’enregistrement, l’insertion d’un composant ou les opérations.

• Utilisez DefinitionObserver pour suivre l’ajout ou la suppression d’instances associées à une définition de composant donnée.

La classe observer doit définir la méthode callback correspondant à l’événement à surveiller. Une instance de cette classe est ensuite ajoutée à la collection, au modèle ou à la définition de composant concerné. Les exemples ci-dessous affichent un message dans la console afin de permettre de voir quel callback est exécuté.

1. Suivre les modifications d’une collection de géométrie

EntitiesObserver surveille les événements qui se produisent dans une collection Sketchup::Entities. La classe ci-dessous signale séparément l’ajout, la modification et la suppression d’un élément. Elle définit également un callback distinct pour la suppression d’un ou de plusieurs éléments de la collection.

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)

La dernière ligne associe l’observer à la collection entities du modèle actif. onElementAdded est appelé lorsqu’un élément est ajouté ; onElementModified, lorsqu’un ou plusieurs éléments de la collection sont modifiés. onElementRemoved signale la suppression d’un élément. Le paramètre transmis à ce callback doit servir à identifier l’événement de suppression, et non à réutiliser l’élément supprimé. La documentation précise que l’élément supprimé ne doit pas être utilisé à d’autres fins.

Si vous devez également suivre l’état du plan de coupe, vous pouvez ajouter la méthode onActiveSectionPlaneChanged(entities) à la classe. Ce callback est exécuté lorsqu’un plan de coupe de la collection concernée est activé ou lorsque le plan actif est désactivé. Vous pouvez vérifier entities.active_section_plane dans le callback pour déterminer si un plan est actif. N’ajoutez cette méthode que si vous avez aussi besoin de suivre les événements liés aux plans de coupe.

2. Suivre les événements au niveau du modèle

Pour les événements concernant le modèle dans son ensemble, créez une sous-classe de Sketchup::ModelObserver. L’exemple ci-dessous affiche des messages différents lorsqu’une opération comportant des modifications se termine, lorsqu’elle se termine sans modification ou lorsqu’elle est annulée.

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 est appelé lorsqu’une opération ayant modifié le modèle se termine ; onTransactionEmpty est exécuté lorsqu’une opération a été démarrée puis terminée sans aucune modification. onTransactionAbort signale quant à lui l’annulation d’une opération. La même interface observer comprend également des callbacks pour d’autres événements, comme l’insertion d’un composant, l’enregistrement du modèle ou l’ouverture d’un groupe ou d’un composant par l’utilisateur afin de le modifier.

Le moment d’exécution des callbacks d’opération est un point important. Depuis SketchUp 2016, les événements observer survenant au cours d’une opération sont mis en file d’attente et transmis après le commit de l’opération. Ainsi, des callbacks comme onTransactionStart ne sont pas exécutés en temps réel dès le début de la modification du modèle. Pour une opération comportant des modifications, la notification onTransactionCommit est transmise au moment du commit ; pour une opération terminée sans modification, c’est onTransactionEmpty qui l’est. La notification d’annulation est fournie séparément par onTransactionAbort : ne définissez pas ce callback de la même manière que les notifications de commit ou d’opération vide.

Selon la documentation, l’API ne dispose pas de méthode permettant de vérifier si une opération est actuellement ouverte. Les callbacks d’opération ne conviennent donc pas au suivi en temps réel de l’état d’une opération. La source recommande de les utiliser principalement à des fins de rapport et de débogage. Évitez de démarrer une nouvelle opération qui modifie le modèle depuis un callback : la documentation avertit que de telles modifications peuvent entraîner un plantage ou une corruption du modèle. Les usages axés sur l’observation, comme l’écriture dans la console ou la consignation d’événements, sont mieux adaptés aux exemples.

3. Suivre les instances d’une définition de composant

Utilisez DefinitionObserver pour suivre l’ajout d’instances à une définition de composant ou la suppression d’une instance de cette définition. Dans l’exemple ci-dessous, l’observer est ajouté à une définition de composant du modèle actif.

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 est appelé lorsqu’une nouvelle instance est ajoutée à la définition surveillée. onComponentInstanceRemoved suit la suppression d’instances de cette définition. L’observer ne surveille que la définition à laquelle il a été ajouté ; pour suivre une autre définition, vous devez également y ajouter un observer. Dans l’exemple, definitions[0] accède à l’une des définitions de composants du modèle actif.

Il existe une exception particulière pour le callback de suppression : en raison du fonctionnement de l’outil Move de SketchUp, onComponentInstanceRemoved peut être exécuté lors d’une opération Move + Copy, même si aucune instance ne semble avoir été supprimée. Ne considérez donc pas le déclenchement du callback comme une preuve suffisante qu’un composant a effectivement été supprimé du modèle.

Erreurs courantes et prochaines étapes

La première erreur consiste à choisir un observer dont le périmètre ne correspond pas à l’événement. Suivre l’ajout d’un élément à une collection de géométrie et surveiller la fin d’une opération au niveau du modèle ne répondent pas au même besoin. Il faut définir le callback dans la bonne classe et ajouter l’observer à la collection, au modèle ou à la définition de composant où l’événement se produit.

Une autre erreur consiste à traiter le paramètre de onElementRemoved comme un élément toujours utilisable. Ce paramètre indique l’identifiant de l’élément supprimé ; selon la documentation, l’élément supprimé ne doit pas être utilisé autrement que pour constater sa suppression. Tenez également compte de l’exception Move + Copy lorsque vous interprétez un événement de suppression dans DefinitionObserver.

Modifier le modèle depuis des callbacks d’opération comporte aussi des risques. Pour vos premiers essais, configurez les callbacks uniquement pour afficher des informations dans la console ou consigner des événements. Observez ensuite quel callback est déclenché par chaque action de l’utilisateur. Lorsque vous examinez des problèmes liés au déroulement des opérations, distinguez les notifications de démarrage, de commit, d’opération vide et d’annulation ; gardez à l’esprit que le callback de démarrage ne signale pas en temps réel le début effectif de l’opération.

Pour la suite, commencez par un seul type d’événement et vérifiez son périmètre et son timing. Lorsque le besoin est clair, ajoutez uniquement les callbacks nécessaires à la classe. Cette méthode aide à limiter le rôle du code d’observation et à mieux comprendre ce que représentent les paramètres des callbacks. Si votre flux de travail nécessite de modifier le modèle, évaluez séparément les limites d’une utilisation sûre des callbacks observer.

Source et licence

Ce guide est adapté de la documentation officielle de l’API Ruby de SketchUp consacrée aux classes EntitiesObserver, ModelObserver et DefinitionObserver. La rubrique consacrée aux licences des sources indique « libre ».