User element

from ArtisanPlugin.Scripting import UserElementApi

A user element is your own part - a crown you modelled by hand, a gallery, a signature motif - promoted to a named component so the rest of Artisan treats it as one thing. The tool does not remodel anything: it groups the objects you selected, stamps the group with UserElement data carrying the name, and gives the solid metal parts the document’s metal material.

List

names = UserElementApi.List()          # -> ["Crown v2", "Gallery A", ...]

Returns the names of the user elements in the active document, read from the UserElement data on the document’s groups, in group order. Names are not unique - two elements created with the same name appear twice. List is read-only: it needs an active document but no licence, and it returns names only, with no way back to the objects or the element id.

Create

uid = UserElementApi.Create(objectIds, "Crown v2")     # -> id

Parameter	Default	Meaning
objectIds	required	The document objects to tag; ids that are not in the document are silently dropped, and an empty result throws
name	required	The element’s name, as the Outliner shows it - empty or whitespace throws

Create runs the tool’s whole flow. It makes a new Rhino group named UserElement <guid>, attaches the UserElement user data to that group with your name, and then walks the objects: non-gem solid geometry (breps, extrusions and meshes) is given the document’s metal material, while gems and everything else - curves, points, annotations - only join the group. Nothing is moved to another layer, and no geometry is rebuilt or replaced.

It returns a single Guid: the element’s own unique id, the one stored in the user data. This is not a document object id and not a group index, so doc.Objects.FindId will not find it; it identifies the element, not a piece of geometry. There is no handle interface on this facade, and no method that resolves an element id back to its objects.

Create is a licensed mutation and needs an active document. Since it touches the attributes of every object you pass as well as creating the group, wrap it in a Transaction so the whole tagging undoes in one step.