Search Objects
==============

Search objects are fundamental elements in Aiviro for identifying and automating interactions with screen elements.
They define **what** to look for on the screen, not **where** it is. When you use a search object, Aiviro will:

1. Analyze the current screen
2. Find all elements matching your criteria
3. Return the matching elements for interaction

**Basic Usage Example:**

.. code-block:: python

    import aiviro

    robot = aiviro.create_desktop_robot()

    # Find and click a button
    robot.click(aiviro.Button("OK"))

    # Find and type into an input field
    robot.type_text(aiviro.Input("Username"), "john.doe")

    # Find text on screen
    welcome_text = robot.get(aiviro.Text("Welcome"))

**Search Object Categories:**

- **Element Objects**: Find specific UI elements (buttons, inputs, text)
- **Positional Objects**: Find elements relative to other elements
- **Special Objects**: Advanced search capabilities (OR, AND, custom areas)

.. automodule:: aiviro.core.utils.search_objects

    Special Objects
    ---------------

    These objects provide advanced search capabilities and logical operations.

    .. code-block:: python

        # OR: Find any of several possible elements
        login_button = robot.get(
            aiviro.Or(
                aiviro.Button("Login"),
                aiviro.Button("Sign In"),
                aiviro.Button("Log In")
            )
        )

        # AND: Element must match all criteria
        specific_text = robot.get(
            aiviro.And(
                aiviro.Text("Total"),
                aiviro.Text("Summary")
            )
        )

        # CustomBox: Define custom search area around element
        input_near_label = robot.get(
            aiviro.CustomBox(
                aiviro.Text("Password:"),
                x_min_offset=100,  # Look 100px to the right
                x_max_offset=300,
                y_min_offset=-10,
                y_max_offset=30
            )
        )

    .. autoclass:: Or
    .. autoclass:: And
    .. autoclass:: Color
    .. autoclass:: CustomBox
    .. autoclass:: CustomSearchObject
    .. autoclass:: BoundaryArea
    .. autoclass:: LargestSize

    Positional Objects
    ------------------

    These objects find elements based on their position relative to other elements.

    .. code-block:: python

        # Find input field to the right of a label
        email_input = robot.get(
            aiviro.OnTheRight(
                aiviro.Input(),
                aiviro.Text("Email:")
            )
        )

        # Find button below a form
        submit_button = robot.get(
            aiviro.Below(
                aiviro.Button("Submit"),
                aiviro.Text("Registration Form")
            )
        )

        # Find label above an input
        field_label = robot.get(
            aiviro.Above(
                aiviro.Text(),
                aiviro.Input("username")
            )
        )

        # Find element to the left
        checkbox = robot.get(
            aiviro.OnTheLeft(
                aiviro.CheckBox(),
                aiviro.Text("I agree to terms")
            )
        )

    .. autoclass:: OnTheLeft
    .. autoclass:: OnTheRight
    .. autoclass:: Above
    .. autoclass:: Below
    .. autoclass:: ClosestElement

    Element Objects
    ---------------

    These objects find specific types of UI elements on the screen.

    .. code-block:: python

        # Find text elements
        title = robot.get(aiviro.Text("Welcome to Application"))

        # Find input fields
        username_field = robot.get(aiviro.Input("Username"))

        # Find buttons
        login_btn = robot.get(aiviro.Button("Login"))

        # Find checkboxes
        agree_checkbox = robot.get(aiviro.CheckBox("I agree"))

        # Find using regex patterns
        phone_number = robot.get(aiviro.RegexText(r"\(\d{3}\) \d{3}-\d{4}"))

        # Find any number
        price = robot.get(aiviro.Number())

        # Find icons
        settings_icon = robot.get(aiviro.Icon("Settings"))

        # Find with element index (when multiple matches)
        first_button = robot.get(aiviro.Button("OK", element_index=0))
        last_button = robot.get(aiviro.Button("OK", element_index=-1))

        # Find with different matching methods
        exact_match = robot.get(aiviro.Text("Submit", find_method=aiviro.find_method.EQUAL))
        contains_match = robot.get(aiviro.Text("Submit", find_method=aiviro.find_method.SUBSTRING))

    .. autoclass:: Text
    .. autoclass:: Input
    .. autoclass:: Button
    .. autoclass:: CheckBox
    .. autoclass:: RadioButton
    .. autoclass:: Toggle
    .. autoclass:: TextArea
    .. autoclass:: Icon
    .. autoclass:: Number
    .. autoclass:: Image
    .. autoclass:: RegexText