Capturing & Video

@staticmethod
@handle_csharp_exceptions
def element(element: "AutomationElement", settings: Optional[CaptureSettings] = None) -> CaptureImage:
    """Capture a single automation element.

    :param element: The element to capture.
    :param settings: Optional output sizing settings.
    :return: The captured image.
    """
    from FlaUI.Core.Capturing import Capture as CSCapture  # pyright: ignore

    return CaptureImage(raw_image=CSCapture.Element(element.raw_element, _cs_settings(settings)))

@staticmethod
@handle_csharp_exceptions
def element_rectangle(
    element: "AutomationElement", rectangle: Rectangle, settings: Optional[CaptureSettings] = None
) -> CaptureImage:
    """Capture a rectangle (relative to the element) inside an element.

    :param element: The element whose region to capture.
    :param rectangle: The rectangle relative to the element's top-left corner.
    :param settings: Optional output sizing settings.
    :return: The captured image.
    """
    from FlaUI.Core.Capturing import Capture as CSCapture  # pyright: ignore

    return CaptureImage(
        raw_image=CSCapture.ElementRectangle(element.raw_element, rectangle.raw_value, _cs_settings(settings))
    )

@staticmethod
@handle_csharp_exceptions
def main_screen(settings: Optional[CaptureSettings] = None) -> CaptureImage:
    """Capture the primary screen.

    :param settings: Optional output sizing settings.
    :return: The captured image.
    """
    from FlaUI.Core.Capturing import Capture as CSCapture  # pyright: ignore

    return CaptureImage(raw_image=CSCapture.MainScreen(_cs_settings(settings)))

@staticmethod
@handle_csharp_exceptions
def rectangle(bounds: Rectangle, settings: Optional[CaptureSettings] = None) -> CaptureImage:
    """Capture a desktop-relative rectangle.

    :param bounds: The screen region to capture.
    :param settings: Optional output sizing settings.
    :return: The captured image.
    """
    from FlaUI.Core.Capturing import Capture as CSCapture  # pyright: ignore

    return CaptureImage(raw_image=CSCapture.Rectangle(bounds.raw_value, _cs_settings(settings)))

@staticmethod
@handle_csharp_exceptions
def screen(screen_index: int = -1, settings: Optional[CaptureSettings] = None) -> CaptureImage:
    """Capture a screen (or the whole virtual desktop when ``screen_index`` is out of range).

    :param screen_index: Zero-based monitor index; ``-1`` captures all monitors.
    :param settings: Optional output sizing settings.
    :return: The captured image.
    """
    from FlaUI.Core.Capturing import Capture as CSCapture  # pyright: ignore

    return CaptureImage(raw_image=CSCapture.Screen(screen_index, _cs_settings(settings)))

@staticmethod
@handle_csharp_exceptions
def screens_with_element(element: "AutomationElement", settings: Optional[CaptureSettings] = None) -> CaptureImage:
    """Capture every screen the given element overlaps.

    :param element: The element to locate across screens.
    :param settings: Optional output sizing settings.
    :return: The captured image.
    """
    from FlaUI.Core.Capturing import Capture as CSCapture  # pyright: ignore

    return CaptureImage(raw_image=CSCapture.ScreensWithElement(element.raw_element, _cs_settings(settings)))

def __enter__(self) -> "CaptureImage":
    """Enter the context manager.

    :return: This :class:`CaptureImage`.
    """
    return self

def __exit__(self, *exc_info: Any) -> None:
    """Dispose the image on context-manager exit.

    :param exc_info: Standard ``(exc_type, exc, tb)`` tuple (unused).
    """
    self.dispose()

@handle_csharp_exceptions
def apply_overlays(self, *overlays: Any) -> "CaptureImage":
    """Draw the given C# ``ICaptureOverlay`` objects onto the image.

    :param overlays: Raw C# overlay instances (e.g. ``MouseOverlay``, ``InfoOverlay``).
    :return: This :class:`CaptureImage` (for chaining).
    """
    self.raw_image.ApplyOverlays(*overlays)
    return self

@handle_csharp_exceptions
def dispose(self) -> None:
    """Dispose the underlying bitmap and release its memory."""
    self.raw_image.Dispose()

@handle_csharp_exceptions
def to_file(self, file_path: str) -> None:
    """Save the image to a file; the extension selects the format (defaults to PNG).

    :param file_path: Destination path (``.png``, ``.jpg``, ``.gif``, ``.tif``, ``.bmp``).
    """
    self.raw_image.ToFile(file_path)

def __enter__(self) -> "VideoRecorder":
    """Enter the context manager.

    :return: This :class:`VideoRecorder`.
    """
    return self

def __exit__(self, *exc_info: Any) -> None:
    """Stop and dispose the recorder on context-manager exit.

    :param exc_info: Standard ``(exc_type, exc, tb)`` tuple (unused).
    """
    self.dispose()

@handle_csharp_exceptions
def dispose(self) -> None:
    """Dispose the recorder (stops it if still running)."""
    self.raw_recorder.Dispose()

@staticmethod
@handle_csharp_exceptions
def download_ffmpeg(target_folder: str) -> str:
    """Download a static ffmpeg build into ``target_folder`` (blocking).

    :param target_folder: Folder to download ffmpeg into.
    :return: The path to the downloaded ffmpeg executable.
    """
    from FlaUI.Core.Capturing import VideoRecorder as CSVideoRecorder  # pyright: ignore

    return CSVideoRecorder.DownloadFFMpeg(target_folder).Result

@classmethod
@handle_csharp_exceptions
def start(
    cls,
    settings: VideoRecorderSettings,
    capture_method: Optional[Callable[["VideoRecorder"], CaptureImage]] = None,
) -> "VideoRecorder":
    """Start recording.

    :param settings: Recorder settings (must include ``target_video_path``).
    :param capture_method: Optional callback ``(recorder) -> CaptureImage`` producing each frame.
        Defaults to capturing the whole virtual desktop.
    :return: The running :class:`VideoRecorder`.
    """
    from System import Func  # pyright: ignore
    from FlaUI.Core.Capturing import (  # pyright: ignore
        Capture as CSCapture,
        CaptureImage as CSCaptureImage,
        VideoRecorder as CSVideoRecorder,
    )

    if capture_method is None:

        def _frame(_recorder: Any) -> Any:
            """Default frame source: capture the whole desktop."""
            return CSCapture.Screen()
    else:

        def _frame(recorder: Any) -> Any:
            """Bridge the C# frame request to the user's Python capture callback."""
            result = capture_method(cls(raw_recorder=recorder))
            return result.raw_image if isinstance(result, CaptureImage) else result

    delegate = Func[CSVideoRecorder, CSCaptureImage](_frame)
    raw = CSVideoRecorder(settings.cs_object, delegate)
    return cls(raw_recorder=raw, keep_alive=(_frame, delegate))

@handle_csharp_exceptions
def stop(self) -> None:
    """Stop recording and finish encoding the output file."""
    self.raw_recorder.Stop()