Construct selection and grouping tasks

Three OPAL tasks act on the scene tree's selection and its grouping: construct.scene.set_selection, construct.scene.group_selection and construct.scene.ungroup. This page is their reference.

If you only do one thing with it: select the item you found before you tell the engineer which one it is. A name in a chat message can match several items; a selected row in the tree and a highlight in the viewport cannot be misread.

Why selection is writable

The selection could always be read, with construct.scene.get_selection, and for a long time it could not be written. An agent that found an item with construct.scene.search_items had no way to show it, and had to ask the engineer to click it.

Selection is part of the document, not of a widget: it is a tag on each item, and the tree and the viewport only show it. That is why a task can set it, and why setting it is undone by nothing — selecting is not an edit, so it does not enter the undo history.

The task still counts as a change to the scene (scope construct.scene.mutate), because the selection decides what the next Delete removes.

Why grouping is one task

You could build a group yourself: one construct.item.add for the group, then one construct.item.set_parent per item. That is one step per item, one approval prompt per step in Ask mode, and a tree that is half restructured if a step fails part way. construct.scene.group_selection does the whole change as one step, and one undo reverses it. construct.scene.ungroup is its opposite.

Grouping is not construct.component.nest. Nesting makes a reusable component definition, which is a heavier commitment than putting four items in a group.

Any item argument takes a name

Every item argument on this page takes an item's name as well as its UUID. A list takes a mix of both.

The three tasks

construct.scene.set_selection

Argument Required Default Meaning
itemIds no empty list The items, as a list of UUIDs or names
mode no replace replace, add or remove

replace selects exactly these items. add adds them to what is selected. remove takes them out of it. An empty list with replace clears the selection; there is no separate clear task.

Returns count and selectedIds, the selection after the change.

Fails, with the selection unchanged, when an item does not exist — the message names it — or when mode is none of the three.

{"task": "construct.scene.set_selection", "args": {"itemIds": ["Front wheel", "Back wheel"]}}

construct.scene.group_selection

Argument Required Default Meaning
name no Group The new group's name
itemIds no the selection The items to group, as a list of UUIDs or names

Puts the items into a new group and selects the group. The items keep their order. When every item has the same parent, the group takes the place of the first one; otherwise it goes at the end of the scene's top level.

A selected item whose parent is also selected moves with its parent rather than on its own, so nothing is grouped twice.

Returns groupId and count.

Fails, with the scene unchanged, when nothing is selected and no itemIds are given, or when an item does not exist. If a move is refused after the group was made, the message says so; one undo reverses what was done.

{"task": "construct.scene.group_selection", "args": {"name": "Wheels"}}

construct.scene.ungroup

Argument Required Default Meaning
itemId yes — The group to dissolve

Moves the group's children into the group's place in its parent, in their order, removes the group, and selects the children. One undo puts the group back with its children inside.

Returns count, the number of children moved.

Fails, with the scene unchanged, when the item does not exist or is not a group. The message names the item's type.

{"task": "construct.scene.ungroup", "args": {"itemId": "Wheels"}}

Hiding is not on this page

To hide an item, use construct.item.set_tags with the tag hidden: add it to hide the item, remove it to show it. It is the same undoable step as a click on the item's icon in the tree. There is no separate hide task.

See also

In this section