Patterns

def try_get_pattern(self) -> Tuple[bool, Optional[TPattern]]:
    """Try to get the wrapped pattern.

    :return: A tuple ``(supported, pattern_or_none)``.
    """
    pattern = self.pattern_or_default
    return pattern is not None, pattern

@handle_csharp_exceptions
def set_dock_position(self, dock_position: DockPosition) -> None:
    """Set the control's dock position.

    :param dock_position: The desired dock position.
    """
    self.raw_pattern.SetDockPosition(dock_position.value)

@handle_csharp_exceptions
def collapse(self) -> None:
    """Collapse the control."""
    self.raw_pattern.Collapse()

@handle_csharp_exceptions
def expand(self) -> None:
    """Expand the control."""
    self.raw_pattern.Expand()

@handle_csharp_exceptions
def get_item(self, row: int, column: int) -> AutomationElement:
    """Return the cell at the given zero-based row and column.

    :param row: Zero-based row index.
    :param column: Zero-based column index.
    :return: The :class:`AutomationElement` at the requested cell.
    """
    return AutomationElement(raw_element=self.raw_pattern.GetItem(row, column))

@handle_csharp_exceptions
def invoke(self) -> None:
    """Invoke the control (perform its primary action)."""
    self.raw_pattern.Invoke()

@handle_csharp_exceptions
def find_item_by_property(
    self, start_after: Optional["AutomationElement"], property_id: Any, value: Any
) -> Optional["AutomationElement"]:
    """Find an item by a property value, optionally starting after a given item.

    :param start_after: The item to start searching after, or ``None`` to start at the beginning.
    :param property_id: The C# ``PropertyId`` to match (or ``None`` to find any next item).
    :param value: The property value to match (or ``None``).
    :return: The matching :class:`~flaui.core.automation_elements.AutomationElement`, or ``None``.
    """
    from flaui.core.automation_elements import AutomationElement

    raw_start = None if start_after is None else start_after.raw_element
    result = self.raw_pattern.FindItemByProperty(raw_start, property_id, value)
    return None if result is None else AutomationElement(raw_element=result)

@handle_csharp_exceptions
def do_default_action(self) -> None:
    """Perform the element's default action."""
    self.raw_pattern.DoDefaultAction()

@handle_csharp_exceptions
def select(self, flags_select: int) -> None:
    """Modify the selection using MSAA ``SELFLAG`` flags.

    :param flags_select: The MSAA ``SELFLAG`` bitmask describing the selection change.
    """
    self.raw_pattern.Select(flags_select)

@handle_csharp_exceptions
def set_value(self, value: str) -> None:
    """Set the element's value.

    :param value: The value to set.
    """
    self.raw_pattern.SetValue(value)

@handle_csharp_exceptions
def get_view_name(self, view: int) -> str:
    """Return the localized name of a view.

    :param view: The view identifier.
    :return: The view's localized name.
    """
    return self.raw_pattern.GetViewName(view)

@handle_csharp_exceptions
def set_current_view(self, view: int) -> None:
    """Switch the control to the given view.

    :param view: The view identifier to switch to.
    """
    self.raw_pattern.SetCurrentView(view)

@handle_csharp_exceptions
def get_underlying_object_model(self) -> Any:
    """Return the control's underlying object model.

    :return: The native object model (a COM/.NET object specific to the control).
    """
    return self.raw_pattern.GetUnderlyingObjectModel()

@field_validator("raw_pattern")
def validate_pattern_exists(cls, v: Any, info: ValidationInfo) -> Any:
    """Validate the native pattern object exists.

    :param v: Raw C# pattern object.
    :param info: Pydantic validation info.
    :raises PatternNotSupportedException: If the pattern object is ``None``.
    :return: The validated raw pattern object.
    """
    if v is None:
        raise PatternNotSupportedException("Pattern is not supported by this element")
    return v

@handle_csharp_exceptions
def set_value(self, value: float) -> None:
    """Set the control's value.

    :param value: The numeric value to set.
    """
    self.raw_pattern.SetValue(value)

@handle_csharp_exceptions
def scroll_into_view(self) -> None:
    """Scroll the item into the visible region of its container."""
    self.raw_pattern.ScrollIntoView()

@handle_csharp_exceptions
def scroll(self, horizontal_amount: ScrollAmount, vertical_amount: ScrollAmount) -> None:
    """Scroll the content by the given horizontal and vertical amounts.

    :param horizontal_amount: The horizontal scroll amount.
    :param vertical_amount: The vertical scroll amount.
    """
    self.raw_pattern.Scroll(horizontal_amount.value, vertical_amount.value)

@handle_csharp_exceptions
def set_scroll_percent(self, horizontal_percent: float, vertical_percent: float) -> None:
    """Set the scroll position as horizontal and vertical percentages.

    :param horizontal_percent: The horizontal scroll position (0-100), or ``-1`` for no change.
    :param vertical_percent: The vertical scroll position (0-100), or ``-1`` for no change.
    """
    self.raw_pattern.SetScrollPercent(horizontal_percent, vertical_percent)

@handle_csharp_exceptions
def add_to_selection(self) -> None:
    """Add the item to the current selection."""
    self.raw_pattern.AddToSelection()

@handle_csharp_exceptions
def remove_from_selection(self) -> None:
    """Remove the item from the current selection."""
    self.raw_pattern.RemoveFromSelection()

@handle_csharp_exceptions
def select(self) -> None:
    """Select the item, deselecting any other selected items."""
    self.raw_pattern.Select()

@handle_csharp_exceptions
def get_item_by_name(self, name: str) -> Any:
    """Return the spreadsheet cell with the given name.

    :param name: The name of the cell (e.g. ``"A1"``).
    :return: The matching :class:`~flaui.core.automation_elements.AutomationElement`.
    """
    from flaui.core.automation_elements import AutomationElement

    return AutomationElement(raw_element=self.raw_pattern.GetItemByName(name))

@handle_csharp_exceptions
def cancel(self) -> None:
    """Cancel listening for synchronized input."""
    self.raw_pattern.Cancel()

@handle_csharp_exceptions
def start_listening(self, input_type: SynchronizedInputType) -> None:
    """Begin listening for the given type of synchronized input.

    :param input_type: The type of input event to listen for.
    """
    self.raw_pattern.StartListening(input_type.value)

@handle_csharp_exceptions
def get_caret_range(self) -> Tuple[TextRange, bool]:
    """Return the text range of the caret and whether the caret is active.

    :return: A tuple ``(caret_range, is_active)``.
    """
    raw_range, is_active = self.raw_pattern.GetCaretRange()
    return TextRange(raw_text_range=raw_range), is_active

@handle_csharp_exceptions
def range_from_annotation(self, annotation: "AutomationElement") -> TextRange:
    """Return the text range associated with an annotation element.

    :param annotation: The annotation element.
    :return: A :class:`~flaui.core.text_range.TextRange` for the annotation.
    """
    return TextRange(raw_text_range=self.raw_pattern.RangeFromAnnotation(annotation.raw_element))

@handle_csharp_exceptions
def get_active_composition(self) -> Optional[TextRange]:
    """Return the text range of the active text composition, if any.

    :return: The active composition :class:`~flaui.core.text_range.TextRange`, or ``None``.
    """
    result = self.raw_pattern.GetActiveComposition()
    return None if result is None else TextRange(raw_text_range=result)

@handle_csharp_exceptions
def get_conversion_target(self) -> Optional[TextRange]:
    """Return the text range of the current conversion target, if any.

    :return: The conversion target :class:`~flaui.core.text_range.TextRange`, or ``None``.
    """
    result = self.raw_pattern.GetConversionTarget()
    return None if result is None else TextRange(raw_text_range=result)

@handle_csharp_exceptions
def get_selection(self) -> List[TextRange]:
    """Return the currently selected text ranges.

    :return: A list of selected :class:`~flaui.core.text_range.TextRange` objects.
    """
    return [TextRange(raw_text_range=_) for _ in self.raw_pattern.GetSelection()]

@handle_csharp_exceptions
def get_visible_ranges(self) -> List[TextRange]:
    """Return the text ranges that are currently visible.

    :return: A list of visible :class:`~flaui.core.text_range.TextRange` objects.
    """
    return [TextRange(raw_text_range=_) for _ in self.raw_pattern.GetVisibleRanges()]

@handle_csharp_exceptions
def range_from_child(self, child: "AutomationElement") -> TextRange:
    """Return the text range that encloses a child element.

    :param child: The child element to locate.
    :return: A :class:`~flaui.core.text_range.TextRange` enclosing the child.
    """
    return TextRange(raw_text_range=self.raw_pattern.RangeFromChild(child.raw_element))

@handle_csharp_exceptions
def range_from_point(self, point: Point) -> TextRange:
    """Return the degenerate text range nearest to a screen point.

    :param point: The screen point to locate.
    :return: A :class:`~flaui.core.text_range.TextRange` at the point.
    """
    return TextRange(raw_text_range=self.raw_pattern.RangeFromPoint(point.cs_object))

@handle_csharp_exceptions
def toggle(self) -> None:
    """Cycle the control to its next toggle state."""
    self.raw_pattern.Toggle()

@handle_csharp_exceptions
def zoom(self, zoom: float) -> None:
    """Zoom the control to the given level.

    :param zoom: The target zoom level.
    """
    self.raw_pattern.Zoom(zoom)

@handle_csharp_exceptions
def zoom_by_unit(self, zoom_unit: ZoomUnit) -> None:
    """Zoom the control by a discrete unit.

    :param zoom_unit: The zoom unit (increment/decrement amount).
    """
    self.raw_pattern.ZoomByUnit(zoom_unit.value)

@handle_csharp_exceptions
def move(self, x: float, y: float) -> None:
    """Move the control to the given screen coordinates.

    :param x: The target x-coordinate.
    :param y: The target y-coordinate.
    """
    self.raw_pattern.Move(x, y)

@handle_csharp_exceptions
def resize(self, width: float, height: float) -> None:
    """Resize the control to the given dimensions.

    :param width: The target width.
    :param height: The target height.
    """
    self.raw_pattern.Resize(width, height)

@handle_csharp_exceptions
def rotate(self, degrees: float) -> None:
    """Rotate the control by the given number of degrees.

    :param degrees: The rotation in degrees.
    """
    self.raw_pattern.Rotate(degrees)

@handle_csharp_exceptions
def set_value(self, value: str) -> None:
    """Set the control's value.

    :param value: The value to set.
    """
    self.raw_pattern.SetValue(value)

@handle_csharp_exceptions
def realize(self) -> None:
    """Realize the virtualized item, making it a full member of the automation tree."""
    self.raw_pattern.Realize()

@handle_csharp_exceptions
def close(self) -> None:
    """Close the window."""
    self.raw_pattern.Close()

@handle_csharp_exceptions
def set_window_visual_state(self, state: WindowVisualState) -> None:
    """Set the window's visual state.

    :param state: The desired visual state (normal, maximized, or minimized).
    """
    self.raw_pattern.SetWindowVisualState(state.value)

@handle_csharp_exceptions
def wait_for_input_idle(self, milliseconds: int) -> bool:
    """Wait until the window is ready to accept input, or the timeout elapses.

    :param milliseconds: The maximum time to wait, in milliseconds.
    :return: ``True`` if the window became idle within the timeout, else ``False``.
    """
    return self.raw_pattern.WaitForInputIdle(milliseconds)

@handle_csharp_exceptions
def add_to_selection(self) -> None:
    """Add the text range to the current selection."""
    self.raw_text_range.AddToSelection()

@handle_csharp_exceptions
def clone(self) -> "TextRange":
    """Return a copy of the text range.

    :return: A new :class:`TextRange` with the same span.
    """
    return TextRange(raw_text_range=self.raw_text_range.Clone())