Object collections

Groups

Objects can be grouped together with

Function: group([obj, …])

where [obj, …] is a list of initial objects in the group and is allowed to be omitted/empty. Like all of the objects in the shape API, group accepts optional transform, conn_avoid, and key=value style parameters.

Groups are themselves objects and can be added to other groups. Furthermore, a group supports the same methods as a Python list. For example, additional objects can be added to a group by invoking its append method:

Example:

rad = 25
evens = group()
odds = group()
fills = ['cyan', 'yellow']
for i in range(8):
    sides = i + 3
    p = regular_polygon(sides, (i*rad*3 + rad*2, 3*rad), rad, fill=fills[i%2])
    if sides%2 == 0:
        evens.append(p)
    else:
        odds.append(p)

The preceding code draws regular polygons of an increasing number of sides. All polygons with an even number of sides are grouped together, and all polygons with an odd number of sides are grouped together.

An existing group can be completely or partially ungrouped by invoking its ungroup method:

Method: ungroup() or ungroup(obj) or ungroup([obj, …])

This method on a group object releases an object or a list of objects from the group and returns it/them to the document's top level. The first form releases all objects from the group and is analogous to Inkscape's Object → Ungroup operation. The second and third forms release a subset of objects from the group and are analogous to Inkscape's Object → Pop Selected Objects out of Group operation. In any case in which the group is empty after an ungroup invocation, the group itself is deleted.

While rarely useful, ungroup accepts a preserve_transform key as a final argument. When set to True (the default), any transforms that were applied to the group as a whole are propagated to the individual objects released from the group. This matches the behavior of Object → Ungroup in the Inkscape GUI. If preserve_transform is set to False, each released object loses its group's transforms but retains any transforms applied specifically to that object.

All forms of ungroup return a list of the objects that were released from the group.

Simple Inkscape Scripting provides a means of mapping from an object back to the group that contains it:

Method: get_parent()

get_parent returns the object's immediate parent or None if the object lies at the top level of the document.

Example:

# Draw rows of circles with each row in its own group.
colors = ['red', 'orange', 'yellow', 'green', 'blue']
diag = []
for j in range(5):
    gr = group()
    for i in range(5):
        c = circle((i*20 + 20, j*20 + 20), 8, fill=colors[j])
        gr.append(c)
        if i == j:
            diag.append(c)

# As a demonstration of get_parent, move all circles in the middle column to a new group.
diag_gr = group()
for c in diag:
    c.get_parent().ungroup(c)
    diag_gr.append(c)
diag_gr.translate((120, 0))

The first stanza of the preceding code draws five rows of five circles, grouping the circles in each row. The second stanza uses get_parent to acquire the group of each circle on the main diagonal then transfers those circles from their original group to a new group. The new group is then shifted to the right of all the row groups.

Layers

An Inkscape layer is really just a specially designated group. Simple Inkscape Scripting provides the following function for creating layers:

Function: layer(name, [obj, …])

where name is the name of the new layer and [obj, …] is a list of initial objects to move to the layer and can be omitted/empty.

Layers support the same methods as Python lists. Hence, additional objects can be added to a layer by passing them to the layer object's append or extend methods:

Example:

c1 = circle((canvas.width/2, canvas.height*3/4), 100, fill='red')
l2 = layer('My new layer')
c2 = circle((canvas.width/2, canvas.height/4), 100, fill='blue')
l2.append(c2)

The preceding code draws a red circle on the default layer then creates a new layer called "My new layer" and adds a blue circle to it.