FEAT: Add new class for named selections

doc/changelog.d/7832.added.md

@@ -0,0 +1 @@
+Add new class for named selections

src/ansys/aedt/core/modeler/cad/modeler.py

@@ -31,6 +31,8 @@
 
 from __future__ import annotations
 
+import warnings
+
 from ansys.aedt.core.base import PyAedtBase
 from ansys.aedt.core.generic.data_handlers import _dict2arg
 from ansys.aedt.core.generic.file_utils import generate_unique_name
@@ -39,6 +41,7 @@
 from ansys.aedt.core.generic.general_methods import settings
 from ansys.aedt.core.generic.numbers_utils import _units_assignment
 from ansys.aedt.core.generic.quaternion import Quaternion
+from ansys.aedt.core.internal.errors import AEDTRuntimeError
 from ansys.aedt.core.modeler.cad.elements_3d import EdgePrimitive
 from ansys.aedt.core.modeler.cad.elements_3d import FacePrimitive
 from ansys.aedt.core.modeler.cad.elements_3d import VertexPrimitive
@@ -1890,6 +1893,12 @@ class Lists(PropsManager, PyAedtBase):
     """
 
     def __init__(self, modeler, props=None, name: str | None = None) -> None:
+        # Deprecated: Lists will be replaced by NamedSelections in future releases.
+        warnings.warn(
+            "`Lists` is deprecated and will be removed in future releases. Use `NamedSelections` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.auto_update = True
         self._modeler = modeler
         self.name = name
@@ -2072,6 +2081,249 @@ def _list_verification(self, object_list, list_type):
         return object_list_new
 
 
+class NamedSelections(PropsManager, PyAedtBase):
+    """Manages Named Selections (replacement for `Lists`).
+
+    Keeps create and delete behavior and provides an ``update`` method that wraps
+    the native ``oEditor.EditNamedSelection`` call.
+    """
+
+    def __init__(self, modeler, props=None, name: str | None = None) -> None:
+        self.auto_update = True
+        self._modeler = modeler
+        self.name = name
+        # Reuse ListsProps for the simple properties structure
+        self.props = ListsProps(self, props)
+
+    @pyaedt_function_handler()
+    def create(
+        self, assignment: list | str | None = None, name: str | None = None, entity_type: str = "Object"
+    ) -> bool:
+        """Create a named selection.
+
+        Parameters
+        ----------
+        assignment : list or str, optional
+            List of object names or face ids or a comma-separated string.
+        name : str, optional
+            Name of the named selection. If not provided a unique name is generated.
+        entity_type : str optional
+            Type of the selection: ``"Object"`` or ``"Face"``. Default is ``"Object"``.
+
+        Examples
+        --------
+        >>> from ansys.aedt.core.modeler.cad.modeler import NamedSelections
+        >>> m3d = Maxwell3d(version="2026.1")
+        >>> box1 = m3d.modeler.create_box([1, 1, 1], [5, 2, 5], name="box1")
+        Create a new instance of NamedSelections
+        >>> lst1 = NamedSelections(m3d.modeler)
+        Create a named selection by specifying assignment and entity type
+        >>> lst1.create(assignment=["box1"], name="my_list", entity_type="Object")
+        >>> m3d.release_desktop(False, False)
+
+        References
+        ----------
+        >>> oEditor.CreateNamedSelection
+        """
+        if not name:
+            name = generate_unique_name(entity_type + "NamedSelection")
+
+        user_list_names = [sel for sel in self._modeler.user_lists if sel.name == name]
+        if name in user_list_names:
+            raise ValueError(f"Named selection with name '{name}' already exists.")
+
+        # Normalize selection
+        if isinstance(assignment, (list, tuple)):
+            if all(isinstance(x, int) for x in assignment):
+                selection = assignment
+                sel_type = "Face"
+            else:
+                selection = ", ".join([str(x) for x in assignment])
+                sel_type = entity_type
+        elif isinstance(assignment, str):
+            selection = assignment
+            sel_type = entity_type
+        else:
+            selection = ""
+            sel_type = entity_type
+
+        params = ["NAME:NamedSelectionParameters", "Type:=", sel_type, "Selection:=", selection]
+        attr = ["NAME:Attributes", "Name:=", name, "UDM ID:=", -1]
+        try:
+            self._modeler.oeditor.CreateNamedSelection(params, attr)
+        except Exception:
+            raise AEDTRuntimeError("Failed to create named selection")
+
+        props = {}
+        props["Selection"] = selection
+        props["Type"] = sel_type
+        self.props = ListsProps(self, props)
+        # Keep compatibility with existing storage
+        try:
+            self._modeler.user_lists.append(self)
+        except Exception:
+            pass
+        self.name = name
+        return True
+
+    @pyaedt_function_handler()
+    def delete(self) -> bool:
+        """Delete the named selection.
+
+        Examples
+        --------
+        >>> from ansys.aedt.core import Maxwell3d
+        >>> m3d = Maxwell3d(version="2026.1")
+        >>> box1 = m3d.modeler.create_box([1, 1, 1], [5, 2, 5], name="box1")
+        Create Objects list and delete it afterward
+        >>> lst = m3d.modeler.create_object_list(assignment=["box1"], name="my_list")
+        >>> lst.delete()
+        >>> m3d.release_desktop(False, False)
+
+        References
+        ----------
+        >>> oEditor.Delete
+        """
+        self._modeler.oeditor.Delete(["NAME:Selections", "Selections:=", self.name])
+        try:
+            self._modeler.user_lists.remove(self)
+        except Exception:
+            pass
+        return True
+
+    @pyaedt_function_handler()
+    def rename(self, name: str) -> bool:
+        """Rename the named selection.
+
+        Parameters
+        ----------
+        name : str
+            New name for the named selection.
+
+        Examples
+        --------
+        >>> from ansys.aedt.core import Maxwell3d
+        >>> m3d = Maxwell3d(version="2026.1")
+        >>> box1 = m3d.modeler.create_box([1, 1, 1], [5, 2, 5], name="box1")
+        Create Objects list and rename it afterward
+        >>> lst = m3d.modeler.create_object_list(assignment=["box1"], name="my_list")
+        >>> lst.rename(name="new_list")
+        >>> m3d.release_desktop(False, False)
+
+        Returns
+        -------
+        bool
+            ``True`` when successful, ``False`` when failed.
+
+        References
+        ----------
+        >>> oEditor.ChangeProperty
+        """
+        argument = [
+            "NAME:AllTabs",
+            [
+                "NAME:Geometry3DListTab",
+                ["NAME:PropServers", self.name],
+                ["NAME:ChangedProps", ["NAME:Name", "Value:=", name]],
+            ],
+        ]
+        self._modeler.oeditor.ChangeProperty(argument)
+        self.name = name
+        return True
+
+    @pyaedt_function_handler()
+    def update(self, selection: list | str | None = None, entity_type: str = "Object", mode: str = "Reassign") -> bool:
+        """Update an existing named selection.
+
+        This method mirrors the signature and semantics of :class:`Lists.update` for
+        backward compatibility. If ``selection`` is ``None``, the stored properties
+        in ``self.props`` are used.
+
+        Parameters
+        ----------
+        selection : str or list, optional
+            Comma-separated string of object names or a list of names/ids. If
+            ``None``, uses the selection stored in ``self.props["Selection"]``.
+        entity_type : str, optional
+            Type of selection, e.g. ``"Object"`` or ``"Face"``. Default ``"Object"``.
+        mode : str, optional
+            Edit mode for the named selection.
+            Options are: ``"Reassign"``, ``"Add"`,``"Remove"``.
+            The default value is ``"Reassign"``.
+
+        Examples
+        --------
+        >>> from ansys.aedt.core import Maxwell3d
+        >>> m3d = Maxwell3d(version="2026.1")
+        >>> box1 = m3d.modeler.create_box([1, 1, 1], [5, 2, 5], name="box1")
+        >>> box2 = m3d.modeler.create_box([2, 2, 2], [5, 2, 5], name="box2")
+        >>> box3 = m3d.modeler.create_box([3, 3, 3], [5, 2, 5], name="box3")
+        Create objects list
+        >>> lst = m3d.modeler.create_object_list(assignment=["box1"], name="my_list")
+        Add box2 in the NamedSelection "my_list"
+        >>> lst.update(selection=[m3d.modeler["box2"]], entity_type="Object", mode="Add")
+        Remove box2 in the NamedSelection "my_list"
+        >>> lst.update(selection=[m3d.modeler["box2"]], entity_type="Object", mode="Remove")
+        Reassign box2 in the NamedSelection "my_list"
+        >>> lst.update(selection=[m3d.modeler["box2"]], entity_type="Object", mode="Reassign")
+        >>> m3d.release_desktop(False, False)
+
+        References
+        ----------
+        >>> oEditor.EditNamedSelection
+        """
+        # If no selection provided, use stored properties
+        if selection is None:
+            selection = self.props.get("Selection", "")
+            entity_type = self.props.get("Type", entity_type)
+
+        # If caller provided a list, normalize using Lists._list_verification to keep
+        # behavior consistent with Lists.update
+        if isinstance(selection, (list, tuple)):
+            try:
+                object_list_new = Lists._list_verification(self, selection, entity_type)
+            except Exception:
+                # Fallback to simple string conversion if verification fails
+                selection = ", ".join([str(s) for s in selection])
+            else:
+                if entity_type == "Object":
+                    selection = ", ".join(object_list_new)
+                else:
+                    # For faces, keep a list of ints as EditNamedSelection accepts it
+                    selection = object_list_new
+
+        # If selection is a string, leave it as-is
+
+        argument1 = ["NAME:Selections", "Selections:=", self.name]
+        argument2 = [
+            "NAME:NamedSelectionParameters",
+            "Type:=",
+            entity_type,
+            "Selection:=",
+            selection,
+            "Mode:=",
+            mode,
+        ]
+        try:
+            self._modeler.oeditor.EditNamedSelection(argument1, argument2)
+        except Exception:
+            raise ValueError("Failed to update named selection")
+
+        # Update stored props to reflect the new selection/type when provided
+        try:
+            # self.props calls __setitem__ and internally calls update()
+            # auto_update needs to be disabled
+            previous_auto_update = self.auto_update
+            self.auto_update = False
+            self.props["Selection"] = selection
+            self.props["Type"] = entity_type
+            self.auto_update = previous_auto_update
+        except Exception:
+            pass
+
+        return True
+
+
 class Modeler(PyAedtBase):
     """Provides the `Modeler` application class that other `Modeler` classes inherit.