Working with Selections

A selection represents a collection of objects in the project, typically used for performing some operation on those objects. The active selection in an application is the set of currently selected objects, which are highlighted in both the project explorer and any view window where they appear. The active selection is under the control of the user, but it can also be changed programmatically within a script. A selection is represented in the SDK using the Selection class.

Important:  It is not advisable to rely on the order of objects within a selection as being significant. If the selection is user-generated (through the active selection), the order does not necessarily correspond to the sequence in which the user selected the objects.

Selection operations

The following section covers the basics of working with selections.

Getting and setting the active selection

To create a selection from the connected application’s active selection, use the Project.get_selected() or Selection.active_selection() functions.

Note:  The Selection object returned by these functions is a copy of the active selection; if the user subsequently changes the active selection, the set of objects in the Selection object will remain unchanged.

To set the active selection, use Project.set_selected().

Adding to a selection

Add an object to a selection using the Selection.append() method. Add multiple objects using the Selection.extend() methods.

Clearing a selection

Remove all objects from a selection using the Selection.clear() method.

Filtering a selection by object type

Selections can be filtered by object type using the Selection.where() and Selection.where_not() instance methods. These methods return a new selection with the applied filter, rather than modifying the original selection in place.

These methods serve as a shorthand for performing a list comprehension over a selection to check whether each object matches one of the specified types. This can be useful when a function expects objects of only a given type.

The following code snippet demonstrates how to obtain a selection that contains only Topology objects:

topologies = project.get_selected().where(Topology)

Partitioning the selection by type

You can use the Selection.partition() method to partition a selection by a given set of types into separate selections, one for each specified type.

The following code snippet demonstrates partitioning a selection of polygon and polyline objects into two new selections, one containing only the polygons and the other only the polylines:

cad_children = Selection(project.get_children('cad').ids()))
polygons, lines = selection.partition(Polygon, Polyline)

In this example, objects of any other type would be discarded from the result. To return other object types, you can supply the optional parameter with_remainder=True.

Querying the roots of a selection

The root objects of a selection are the objects whose parents are not part of that selection. You can obtain the root objects by accessing the Selection.roots property of a selection. This is useful when you only need the container objects themselves and not the individual objects within them.

See Working with Projects > Recycle bin for an example that uses Selection.roots.

Useful code snippets using selections

Creating a selection from the children of a container

The following snippet creates a selection containing all the child objects within the cad container:

cad_children = Selection(project.get_children('cad').ids()))

Creating a selection representing objects of a given type

The following snippet creates a selection containing all polyline objects located within the cad container:

cad_children = Selection(project.get_children('cad').ids()))
polylines = cad_children.where(Polyline)

Creating separate selections based on type

The following snippet creates two selections, one containing all polyline objects located within the cad container, and the other containing all polygon objects located within the cad container:

cad_children = Selection(project.get_children('cad').ids()))
polygons, lines = selection.partition(Polygon, Polyline)

Setting the active selection to a given type

The following snippet sets the active selection to only polygons located within the cad container:

cad_children = Selection(project.get_children('cad').ids()))
project.set_selected(cad_children.where(Polygon))