From 2dc9df3f40937f81bf91a8ee2044d5f0c0eb4b65 Mon Sep 17 00:00:00 2001
From: Matthias Koefferlein <matthias@klayout.de>
Date: Sun, 31 Mar 2024 22:23:23 +0200
Subject: [PATCH] Updated documentation with example

---
 src/edt/edt/gsiDeclEdtEditorHooks.cc | 107 ++++++++++++++++++++++++++-
 1 file changed, 106 insertions(+), 1 deletion(-)

diff --git a/src/edt/edt/gsiDeclEdtEditorHooks.cc b/src/edt/edt/gsiDeclEdtEditorHooks.cc
index 0373bdca9..589f7f20a 100644
--- a/src/edt/edt/gsiDeclEdtEditorHooks.cc
+++ b/src/edt/edt/gsiDeclEdtEditorHooks.cc
@@ -389,7 +389,112 @@ gsi::Class<EditorHooksImpl> decl_EditorHooks ("lay", "EditorHooks",
   "This class provides the basic interface. To implement callbacks, use the \\EditorHooks class. "
   "You should not need to instantiate this class.\n"
   "\n"
-  // @@@
+  "The following is an excample for editor hooks that add DRC space indicators for polygon-alike shapes:\n"
+  "\n"
+  "@code\n"
+  "class MyEditorHooks(pya.EditorHooks):\n"
+  "\n"
+  "  def __init__(self):\n"
+  "  \n"
+  "    self.register(\"editor_hooks_demo\")\n"
+  "    \n"
+  "    self.markers = []\n"
+  "    self.view = None\n"
+  "    self.layout = None\n"
+  "    self.space = 0.0\n"
+  "    \n"
+  "    self.spaces = {\n"
+  "      pya.LayerInfo(1, 0): ( 0.2, pya.Region.Euclidian ),\n"
+  "      pya.LayerInfo(2, 0): ( 0.5, pya.Region.Projection )\n"
+  "    }\n"
+  "    \n"
+  "    self.instance_space = 0.4\n"
+  "\n"
+  "  # Utilities\n"
+  "  \n"
+  "  def set_space_from_layer(self, layer_index):\n"
+  "    # pick the space value or None\n"
+  "    lp = self.layout.get_info(layer_index)\n"
+  "    if lp in self.spaces:\n"
+  "      (s, m) = self.spaces[lp]\n"
+  "      self.space = s / self.layout.dbu\n"
+  "      self.metrics = m\n"
+  "    else:\n"
+  "      self.space = None\n"
+  "      \n"
+  "  def add_marker_from_shape(self, shape, trans):\n"
+  "    if self.space is None:\n"
+  "      return\n"
+  "    p = shape.polygon\n"
+  "    if p is not None and p.num_points() < 100:\n"
+  "      r = pya.Region()\n"
+  "      # maintain 2-point polygons for the first edge drawn\n"
+  "      r.merged_semantics = (p.num_points() != 2)\n"
+  "      r.insert(p)\n"
+  "      r = r.drc_hull(self.metrics, self.space)\n"
+  "      for pp in r.each():\n"
+  "        m = pya.Marker(self.view)\n"
+  "        m.line_style = 2\n"
+  "        m.vertex_size = 0\n"
+  "        m.set_polygon(trans * pp)\n"
+  "        self.markers.append(m)\n"
+  "        \n"
+  "  # Shape creation protocol\n"
+  "  \n"
+  "  def begin_create_shapes(self, cv, layer):\n"
+  "    # setup session\n"
+  "    self.view = cv.view()\n"
+  "    self.layout = cv.layout()\n"
+  "    self.markers = []\n"
+  "    # pick the space value\n"
+  "    self.set_space_from_layer(layer.layer_index())\n"
+  "\n"
+  "  def begin_new_shapes(self):\n"
+  "    # create new markers\n"
+  "    self.markers = []\n"
+  "\n"
+  "  def create_shape(self, shape, trans):\n"
+  "    # create a marker with space halo\n"
+  "    self.add_marker_from_shape(shape, trans)\n"
+  "      \n"
+  "  def end_create_shapes(self):\n"
+  "    # cleanup\n"
+  "    self.markers = []\n"
+  "    self.view = None\n"
+  "    self.layout = None\n"
+  "    \n"
+  "  # Modification protocol\n"
+  "  \n"
+  "  def begin_edit(self, cv):\n"
+  "    # setup session\n"
+  "    self.view = cv.view()\n"
+  "    self.layout = cv.layout()\n"
+  "    self.markers = []\n"
+  "\n"
+  "  def begin_edits(self):\n"
+  "    # create new markers\n"
+  "    self.markers = []\n"
+  "\n"
+  "  def transformed(self, path, applied, trans):\n"
+  "    # transformation of a shape or instance\n"
+  "    if path.shape is not None:\n"
+  "      self.set_space_from_layer(path.layer)\n"
+  "      self.add_marker_from_shape(path.shape, trans * applied)\n"
+  "\n"
+  "  def modified(self, path, shape, trans):\n"
+  "    # modification of a shape\n"
+  "    self.set_space_from_layer(path.layer)\n"
+  "    self.add_marker_from_shape(shape, trans)\n"
+  "\n"
+  "  def end_edit(self):\n"
+  "    # cleanup\n"
+  "    self.markers = []\n"
+  "    self.view = None\n"
+  "    self.layout = None\n"
+  "\n"
+  "# instantiation of the hooks object\n"
+  "MyEditorHooks()\n"
+  "@/code\n"
   "\n"
   "The EditorHooks class has been introduced in version 0.29."
 );