Provide a clone function to produce linked clones of an object

README.md

@@ -116,6 +116,11 @@ Append to a previous piece of text (created with `text` or `more_text`), possibl
 
 Include an image.  `fname` is the name of the file to include.  A variety of image formats are supported, but only PNG, JPEG, and SVG are guaranteed to be supported by all SVG viewers.  The upper-left corner of the image will lie at coordinates `(x, y)`.  If `embed` is `True` (the default), the image data will be embedded in the SVG file.  This results in a larger SVG file, but it can be viewed without access to the original image file.  If `embed` is `False`, the SVG file will merely reference the named file.  This results in a smaller SVG file, but it requires access to the image file.  If the image file is moved or deleted, it will no longer appear in the SVG file.  `fname` can be a URL.  In this case, `embed` must be set to `False`.  *Example*: `image('https://media.inkscape.org/static/images/inkscape-logo.png', (0, 0), embed=False)`
 
+* `clone(obj)`
+
+Return a linked clone of an object.  Modifications made in the Inkscape GUI to the original object propagate to all clones.  (This applies only to certain modifications such as rotations, style properties, and path control-point locations.)  *Example*: `r1 = rect((100, 100), (200, 200), fill='#668000')
+r2 = clone(r1, transform='translate(200, 0)')`
+
 ### Transformations
 
 All of the functions presented under [Shape API](#shape-api) accept an additional `transform` parameter.  `transform` takes a string representing an [SVG transform](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform) (`rotate`, `scale`, etc.) and applies that transform to the object.

examples/clone_wave.py

@@ -0,0 +1,10 @@
+# Use Simple Inkscape Scripting to draw a wave of cloned objects.
+#
+# Try rotating, scaling, or recoloring the original (leftmost) object
+# and seeing how all the other objects change accordingly.
+
+mark = regular_polygon(5, (0, height/2), 10, fill='#55ddff')
+for a in range(5, 360, 5):
+    x = a*width/360
+    y = sin(a*pi/180)*height/2 + height/2
+    clone(mark, transform='translate(%.5g, %.5g) translate(0, %.5g)' % (x, y, -height/2))

simple_inkscape_scripting.inx

@@ -9,7 +9,7 @@
              gui-description="See the help tab for more information" />
       <hbox>
         <spacer size="expand" />
-        <label>– or –</label>
+        <label>– and/or –</label>
         <spacer size="expand" />
       </hbox>
       <param name="program" type="string" appearance="multiline"
@@ -43,6 +43,7 @@
 • text(msg, base)
 • more_text(msg, [base])
 • image(fname, ul, [embed])
+• clone(obj)
 • group([obj1, obj2, …])
 • inkex_object(iobj)
       </label>
@@ -52,10 +53,10 @@
         ang, angt, angb, round, random, and curve are floats.  sides
         is an integer.  Each elt is either a string or a float.  msg,
         fname, and ctype are strings, but ctype must be either
-        "polyline" or "orthogonal".  embed is a bool.  obj1 and obj2
-        are objects returned from any of the object-creation functions
-        listed above.  iobj is an arbitrary object created using
-        Inkscape's core API.
+        "polyline" or "orthogonal".  embed is a bool.  obj, obj1, and
+        obj2 are objects returned from any of the object-creation
+        functions listed above.  iobj is an arbitrary object created
+        using Inkscape's core API.
       </label>
       <label />
       <label>

simple_inkscape_scripting.py

@@ -360,6 +360,13 @@ def image(fname, ul, embed=True, transform=None, conn_avoid=False, **style):
     return SimpleObject(obj, transform, conn_avoid, {}, style)
 
 
+def clone(obj, transform=None, conn_avoid=False, **style):
+    'Return a linked clone of the object.'
+    c = inkex.Use(obj._inkscape_obj)
+    c.href = obj._inkscape_obj.get_id()
+    return SimpleObject(c, transform, conn_avoid, {}, style)
+
+
 def group(objs=[], transform=None, conn_avoid=False, **style):
     'Create a container for other objects.'
     g = inkex.Group()