|
| 1 | +"""Scroll a target into view, then act on it only once it is actionable. |
| 2 | +
|
| 3 | +Two reliability primitives the framework already had stayed separate: |
| 4 | +``scroll_find.scroll_until_visible`` brings an off-screen target on-screen, and |
| 5 | +``actionability.act_when_ready`` waits for a target to be visible / stable / |
| 6 | +enabled / unoccluded before acting. A real "click the row three pages down" step |
| 7 | +needs *both* — scroll to it, then gate before clicking. ``act_in_view`` composes |
| 8 | +them into one call. |
| 9 | +
|
| 10 | +* :class:`ScrollPlan` — bundles the scroll search (``kind`` / ``direction`` / |
| 11 | + ``max_scrolls`` / ``scroll_amount``) and its injectable ``locator`` / |
| 12 | + ``scroller`` seams, so the composed call stays within a sane argument count. |
| 13 | +* :func:`act_in_view` — scroll until the target is found, then run the |
| 14 | + actionability gate at its location and perform ``action`` on it. |
| 15 | +
|
| 16 | +All seams (locator / scroller / action / actionability probes / clock) are |
| 17 | +injectable, so the whole flow is testable without a screen. Reuses |
| 18 | +:func:`scroll_find.scroll_until_visible` and |
| 19 | +:func:`actionability.act_when_ready`. Imports no ``PySide6``. |
| 20 | +""" |
| 21 | +from dataclasses import dataclass |
| 22 | +from typing import Any, Callable, Dict, List, Optional |
| 23 | + |
| 24 | +from je_auto_control.utils.actionability import GateConfig, act_when_ready |
| 25 | +from je_auto_control.utils.exception.exceptions import AutoControlActionException |
| 26 | +from je_auto_control.utils.scroll_find import scroll_until_visible |
| 27 | +from je_auto_control.utils.scroll_find.scroll_find import Locator, Scroller |
| 28 | + |
| 29 | + |
| 30 | +@dataclass |
| 31 | +class ScrollPlan: |
| 32 | + """How to scroll while searching for the target (with injectable seams).""" |
| 33 | + |
| 34 | + kind: str = "image" |
| 35 | + direction: str = "down" |
| 36 | + max_scrolls: int = 10 |
| 37 | + scroll_amount: int = 3 |
| 38 | + locator: Optional[Locator] = None |
| 39 | + scroller: Optional[Scroller] = None |
| 40 | + |
| 41 | + |
| 42 | +def act_in_view(target: str, action: Callable[[List[int]], Any], *, |
| 43 | + scroll: Optional[ScrollPlan] = None, |
| 44 | + region_sampler: Optional[Callable[[Any], Any]] = None, |
| 45 | + enabled_probe: Optional[Callable[[], Optional[bool]]] = None, |
| 46 | + hit_tester: Optional[Callable[[List[int]], bool]] = None, |
| 47 | + config: Optional[GateConfig] = None) -> Dict[str, Any]: |
| 48 | + """Scroll ``target`` into view, gate on actionability, then ``action`` it. |
| 49 | +
|
| 50 | + Scrolls per ``scroll`` (a :class:`ScrollPlan`) until ``target`` is located, |
| 51 | + then runs :func:`actionability.act_when_ready` at the found point and calls |
| 52 | + ``action(center_point)``. Raises ``AutoControlActionException`` if the target |
| 53 | + never comes into view. The actionability probes / ``config`` are injectable |
| 54 | + and forwarded to the gate. Returns ``{acted, coords, scrolls, result}``. |
| 55 | + """ |
| 56 | + plan = scroll if scroll is not None else ScrollPlan() |
| 57 | + found = scroll_until_visible( |
| 58 | + target, kind=plan.kind, direction=plan.direction, |
| 59 | + max_scrolls=plan.max_scrolls, scroll_amount=plan.scroll_amount, |
| 60 | + locator=plan.locator, scroller=plan.scroller) |
| 61 | + if not found["found"]: |
| 62 | + raise AutoControlActionException( |
| 63 | + f"target {target!r} not in view after {found['scrolls']} scrolls") |
| 64 | + cx, cy = int(found["coords"][0]), int(found["coords"][1]) |
| 65 | + result = act_when_ready(action, lambda: (cx, cy, 1, 1), |
| 66 | + region_sampler=region_sampler, |
| 67 | + enabled_probe=enabled_probe, hit_tester=hit_tester, |
| 68 | + config=config) |
| 69 | + return {"acted": True, "coords": [cx, cy], "scrolls": found["scrolls"], |
| 70 | + "result": result} |
0 commit comments