# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates.
# SPDX-License-Identifier: MIT
#
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

from ansys.mapdl.core._commands import CommandsBase


class Picking(CommandsBase):

    def fitem(
        self,
        nfield: str = "",
        item: str = "",
        itemy: str = "",
        itemz: str = "",
        **kwargs,
    ):
        r"""Identifies items chosen by a picking operation (GUI).

        Mechanical APDL Command: `FITEM <https://ansyshelp.ansys.com/Views/Secured/corp/v232/en//ans_cmd/Hlp_C_FITEM.html>`_

        Parameters
        ----------
        nfield : str
            Field number on the command which uses the picking data. (Count the command name as a field, so
            that a 2 indicates the first command argument, 3 the second command argument, etc.) The
            corresponding field on the command will have a P51X label.

        item : str
            Entity number of the entity picked. Negative entity numbers are used to indicate a range of
            entities. If the item picked is a coordinate location, then this field represents the
            X-coordinate. See also the :ref:`flst` command.

        itemy : str
            Y and Z coordinates of a picked coordinate location. ``ITEM`` represents the X coordinate. See
            also the :ref:`flst` command.

        itemz : str
            Y and Z coordinates of a picked coordinate location. ``ITEM`` represents the X coordinate. See
            also the :ref:`flst` command.

        Notes
        -----

        .. _FITEM_notes:

        This is a command generated by the GUI and will appear in the log file ( :file:`Jobname.LOG` ) if
        graphical picking is used. This command is not intended to be typed in directly in a session
        (although it can be included in an input file for batch input or for use with the :ref:`input`
        command).

        On the log file, a set of :ref:`fitem` commands is preceded by one :ref:`flst` command which defines
        the picking specifications for that pick operation. The data listed in the :ref:`fitem` commands are
        used by the first subsequent command containing a P51X label in one of its fields.

        .. warning::

            For a given entity type, a list containing an ITEMthat is larger than the maximum defined
            entity, could deplete the system memory and produce unpredictable results.

        This command is valid in any processor.
        """
        command = f"FITEM,{nfield},{item},{itemy},{itemz}"
        return self.run(command, **kwargs)

    def flst(
        self,
        nfield: str = "",
        narg: str = "",
        type_: int | str = "",
        otype: str = "",
        leng: str = "",
        **kwargs,
    ):
        r"""Specifies data required for a picking operation (GUI).

        Mechanical APDL Command: `FLST <https://ansyshelp.ansys.com/Views/Secured/corp/v232/en//ans_cmd/Hlp_C_FLST.html>`_

        Parameters
        ----------
        nfield : str
            Field number on the command which uses the picking data. (Count the command name as a field, so
            that a 2 indicates the first command argument, 3 for the second command argument, etc.) The
            corresponding field on the command will have a P51X label.

        narg : str
            Number of items in the picked list.

        type_ : int or str
            Type of items picked:

            * ``1`` - Node numbers

            * ``2`` - Element numbers

            * ``3`` - Keypoint numbers

            * ``4`` - Line numbers

            * ``5`` - Area numbers

            * ``6`` - Volume numbers

            * ``7`` - Trace points

            * ``8`` - Coordinate locations (in Global Cartesian coordinates)

            * ``9`` - Screen picks (in X, Y screen coordinates (-1 to 1))

        otype : str
            Data order:

            * ``NOOR`` - Data is not ordered (default).

            * ``ORDER`` - Data is in an ordered list (such as for the :ref:`e`,P51X and :ref:`a`,P51X commands,
              in which the order of the data items is significant for the picking operation).

        leng : str
            Length of number of items describing the list (should equal ``NARG`` if ``Otype`` = NOOR;
            default).

        Notes
        -----

        .. _FLST_notes:

        Specifies data required for the :ref:`fitem` command during a picking operation. This is a command
        generated by the GUI and will appear in the log file ( :file:`Jobname.LOG` ) if graphical picking is
        used. This command is not intended to be typed in directly in a session (although it can be included
        in an input file for batch input or for use with :ref:`input` ).

        On the log file, :ref:`flst` is always followed by one or more :ref:`fitem` commands which, in turn,
        are followed by the Mechanical APDL command containing a P51X label in one of its fields. Do not
        edit this
        set of commands.

        This command is valid in any processor.
        """
        command = f"FLST,{nfield},{narg},{type_},{otype},{leng}"
        return self.run(command, **kwargs)
