Window Acquisition
upscaler.acquisition
Public helpers for discovering and acquiring target windows.
find_window_by_class(instance=None, cls=None)
Find the first visible window whose WM_CLASS matches the given criteria.
At least one of instance or cls must be provided. Both are compared
case-insensitively as substrings.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instance
|
Optional[str]
|
Substring to match against the instance name. |
None
|
cls
|
Optional[str]
|
Substring to match against the class name. |
None
|
Returns:
| Type | Description |
|---|---|
WindowInfo
|
WindowInfo of the first matching window. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If neither |
WindowNotFound
|
If no matching window is found. |
find_window_by_pid(pid, pid_timeout=5.0, class_hint=None, class_timeout=5.0, total_timeout=60.0, starting_phase=1)
Wait for and return a window belonging to the given process ID.
This function uses a two-phase search (PID and optionally WM_CLASS) as
described in the internal _find_by_pid. It blocks until a matching
viewable window is found or the total timeout expires.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pid
|
int
|
Process ID of the launched program. |
required |
pid_timeout
|
float
|
Seconds to spend in the PID-based phase before switching. |
5.0
|
class_hint
|
Optional[str]
|
Optional substring to match against WM_CLASS (instance/class). |
None
|
class_timeout
|
float
|
Seconds to spend in the pure-class phase. |
5.0
|
total_timeout
|
Optional[float]
|
Maximum total search time. |
60.0
|
starting_phase
|
int
|
1 for PID+class first, 2 for pure class first. |
1
|
Returns:
| Type | Description |
|---|---|
WindowInfo
|
WindowInfo of the first matching window. |
Raises:
| Type | Description |
|---|---|
WindowNotFound
|
If no matching window appears within the total timeout. |
find_window_by_title(contains=None, regex=None)
Find the first visible window whose title matches the given criteria.
Priority: regex is used if provided, otherwise contains (case-insensitive).
At least one of contains or regex must be given.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
contains
|
Optional[str]
|
Substring to search for in the window title. |
None
|
regex
|
Optional[str]
|
Regular expression to search for in the window title. |
None
|
Returns:
| Type | Description |
|---|---|
WindowInfo
|
WindowInfo of the first matching window. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If neither |
WindowNotFound
|
If no matching window is found. |
get_active_window()
Return the currently active (focused) window, or None if none.
launch_window(program, pid_timeout=5.0, class_hint=None, class_timeout=5.0, total_timeout=60.0, starting_phase=1)
Launch a program and wait for its main window to appear.
If the window cannot be found within the timeout, the launched process is terminated.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
program
|
List[str]
|
List of command and arguments (e.g., |
required |
pid_timeout
|
float
|
Seconds to spend in the PID phase. |
5.0
|
class_hint
|
Optional[str]
|
Optional substring for class phase. |
None
|
class_timeout
|
float
|
Seconds to spend in the class phase. |
5.0
|
total_timeout
|
Optional[float]
|
Maximum total wait time. |
60.0
|
starting_phase
|
int
|
1 for PID first, 2 for class first. |
1
|
Returns:
| Type | Description |
|---|---|
Tuple[WindowInfo, Popen]
|
A tuple |
Raises:
| Type | Description |
|---|---|
WindowNotFound
|
If no window appears within the timeout or the program fails to start. |
list_windows()
Return a list of all currently visible application windows.