Sync API

The sync API is generated automatically from the async API using unasync.

The sync API is the default API described in most of the README.

FutureResult

class ahk._sync.transport.FutureResult(future)[source]

Parameters:: future (Future[TypeVar(T_SyncFuture)]) –

__init__(future)[source]

Parameters:: future (Future[TypeVar(T_SyncFuture)]) –

result(timeout=None)[source]

Parameters:: timeout (Optional[float]) –
Return type:: TypeVar(T_SyncFuture)

Window

class ahk._sync.window.Window(engine, ahk_id)[source]

Parameters:

engine (AHK[TypeVar(T_EngineVersion, bound= Optional[Literal['v1', 'v2']])]) –
ahk_id (str) –

__init__(engine, ahk_id)[source]

Parameters:

engine (AHK[TypeVar(T_EngineVersion, bound= Optional[Literal['v1', 'v2']])]) –
ahk_id (str) –

close()[source]

Return type:: None

kill()[source]

Return type:: None

exists()[source]

Return type:: bool

property id: str

property exist: bool

get_pid()[source]

Return type:: int

property pid: int

get_process_name()[source]

Return type:: str

property process_name: str

get_process_path()[source]

Return type:: str

property process_path: str

get_minmax()[source]

Return type:: int

get_title()[source]

Return type:: str

property title: str

set_title(new_title)[source]

Parameters:: new_title (str) –
Return type:: None

list_controls()[source]

Return type:: Sequence[Control]

minimize(blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

maximize(blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

restore(blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

get_class(blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Union[str, FutureResult[str]]

set_always_on_top(toggle, *, blocking=True)[source]

Parameters:

toggle (Literal['On', 'Off', 'Toggle', 1, -1, 0]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

is_always_on_top(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Union[bool, FutureResult[Optional[bool]]]

property always_on_top: bool

send(keys, control='', *, blocking=True)[source]

Parameters:

keys (str) –
control (str) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

click(x=0, y=0, *, button='L', click_count=1, options='', blocking=True)[source]

Parameters:

x (int) –
y (int) –
button (Literal['L', 'R', 'M', 'LEFT', 'RIGHT', 'MIDDLE']) –
click_count (int) –
options (str) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

get_text(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Union[str, FutureResult[str]]

property text: str

get_position(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Union[Position, FutureResult[Optional[Position]], FutureResult[Position]]

activate(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

to_bottom(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

to_top(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

show(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

hide(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

disable(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

enable(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

redraw(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Optional[FutureResult[None]]

set_style(style, *, blocking=True)[source]

Parameters:

style (str) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

set_ex_style(style, *, blocking=True)[source]

Parameters:

style (str) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

set_region(options, *, blocking=True)[source]

Parameters:

options (str) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

set_transparent(transparency, *, blocking=True)[source]

Parameters:

transparency (Union[int, Literal['Off']]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

set_trans_color(color, *, blocking=True)[source]

Parameters:

color (Union[int, str]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

property active: bool

is_active()[source]

Return type:: bool

move(x, y, *, width=None, height=None, blocking=True)[source]

Parameters:

x (int) –
y (int) –
width (Optional[int]) –
height (Optional[int]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

classmethod from_pid(engine, pid)[source]

Parameters:

engine (AHK[Any]) –
pid (int) –

Return type:

Optional[Window]

classmethod from_mouse_position(engine)[source]

Parameters:: engine (AHK[Any]) –
Return type:: Optional[Window]

AsyncControl

class ahk._sync.window.Control(window, hwnd, control_class)[source]

Parameters:

window (Window) –
hwnd (str) –
control_class (str) –

__init__(window, hwnd, control_class)[source]

Parameters:

window (Window) –
hwnd (str) –
control_class (str) –

click(*, button='L', click_count=1, options='', use_hwnd=None, blocking=True)[source]

Parameters:

button (Literal['L', 'R', 'M', 'LEFT', 'RIGHT', 'MIDDLE']) –
click_count (int) –
options (str) –
use_hwnd (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

send(keys, *, use_hwnd=None, blocking=True)[source]

Parameters:

keys (str) –
use_hwnd (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

get_text(*, use_hwnd=None, blocking=True)[source]

Parameters:

use_hwnd (Optional[bool]) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

get_position(*, use_hwnd=None, blocking=True)[source]

Parameters:

use_hwnd (Optional[bool]) –
blocking (bool) –

Return type:

Union[Position, FutureResult[Position]]

AHK

class ahk._sync.engine.AHK(*, TransportClass: Type[Transport] | None = None, directives: list[Union[ahk.directives.Directive, Type[ahk.directives.Directive]]] | None = None, executable_path: str = '', extensions: list[ahk.extensions.Extension] | None | Literal['auto'] = None)[source]

class ahk._sync.engine.AHK(*, TransportClass: Type[Transport] | None = None, directives: list[Union[ahk.directives.Directive, Type[ahk.directives.Directive]]] | None = None, executable_path: str = '', extensions: list[ahk.extensions.Extension] | None | Literal['auto'] = None, version: None)

class ahk._sync.engine.AHK(*, TransportClass: Type[Transport] | None = None, directives: list[Union[ahk.directives.Directive, Type[ahk.directives.Directive]]] | None = None, executable_path: str = '', extensions: list[ahk.extensions.Extension] | None | Literal['auto'] = None, version: Literal['v2'])

class ahk._sync.engine.AHK(*, TransportClass: Type[Transport] | None = None, directives: list[Union[ahk.directives.Directive, Type[ahk.directives.Directive]]] | None = None, executable_path: str = '', extensions: list[ahk.extensions.Extension] | None | Literal['auto'] = None, version: Literal['v1'])

Parameters:

self (AHK[Optional[Literal['v1', 'v2']]]) –
TransportClass (Optional[Type[Transport]]) –
directives (Optional[list[Union[Directive, Type[Directive]]]]) –
executable_path (str) –
extensions (Union[list[Extension], None, Literal['auto']]) –
version (Optional[Literal['v1', 'v2']]) –

__init__(*, TransportClass=None, directives=None, executable_path='', extensions=None, version=None)[source]

Parameters:

self (AHK[Optional[Literal['v1', 'v2']]]) –
TransportClass (Optional[Type[Transport]]) –
directives (Optional[list[Union[Directive, Type[Directive]]]]) –
executable_path (str) –
extensions (Union[list[Extension], None, Literal['auto']]) –
version (Optional[Literal['v1', 'v2']]) –

add_hotkey(keyname, callback, ex_handler=None)[source]

Register a function to be called when a hotkey is pressed.

Key notes:

You must call the start_hotkeys method for the hotkeys to be active
All hotkeys run in a single AHK process instance (but Python callbacks also get their own thread and can run simultaneously)
If you add a hotkey after the hotkey thread/instance is active, it will be restarted automatically
async functions are not directly supported as callbacks, however you may write a synchronous function that calls asyncio.run/loop.create_task etc.

Parameters:

keyname (str) – the key trigger for the hotkey, such as #n (win+n)
callback (Callable[[], Any]) – callback function to call when the hotkey is triggered
ex_handler (Optional[Callable[[str, Exception], Any]]) – a function which accepts two parameters: the keyname for the hotkey and the exception raised by the callback function.

Return type:

None

Returns:

function_call(function_name, args=None, blocking=True)[source]

Call an AHK function defined in the daemon script. This method is intended for use by extension authors.

Parameters:

function_name (str) –
args (Optional[list[str]]) –
blocking (bool) –

Return type:

Any

add_hotstring(trigger, replacement_or_callback, ex_handler=None, options='')[source]

Register a hotstring, e.g., ::btw::by the way

Key notes:

You must call the start_hotkeys method for registered hotstrings to be active
All hotstrings (and hotkeys) run in a single AHK process instance separate from other AHK processes.

Parameters:

trigger (str) – the trigger phrase for the hotstring, e.g., btw
replacement_or_callback (Union[str, Callable[[], Any]]) – the replacement phrase (e.g., by the way) or a Python callable to execute in response to the hotstring trigger
ex_handler (Optional[Callable[[str, Exception], Any]]) – a function which accepts two parameters: the hotstring and the exception raised by the callback function.
options (str) – the hotstring options – same meanings as in AutoHotkey.

Return type:

None

Returns:

remove_hotkey(keyname)[source]

Parameters:: keyname (str) –
Return type:: None

clear_hotkeys()[source]

Return type:: None

remove_hotstring(trigger)[source]

Parameters:: trigger (str) –
Return type:: None

clear_hotstrings()[source]

Return type:: None

set_title_match_mode(title_match_mode, /)[source]

Sets the default title match mode

Does not affect methods called with blocking=True (because these run in a separate AHK process)

Reference: https://www.autohotkey.com/docs/commands/SetTitleMatchMode.htm

Parameters:: title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) – the match mode (and/or match speed) to set as the default title match mode. Can be 1, 2, 3, ‘Regex’, ‘Fast’, ‘Slow’ or a tuple of these.
Return type:: None
Returns:: None

get_title_match_mode()[source]

Get the title match mode.

I.E. the current value of A_TitleMatchMode

Return type:: str

get_title_match_speed()[source]

Get the title match mode speed.

I.E. the current value of A_TitleMatchModeSpeed

Return type:: str

set_coord_mode(target, relative_to='Screen')[source]

Analog of CoordMode

Parameters:

target (Union[Literal['ToolTip'], Literal['Pixel'], Literal['Mouse'], Literal['Caret'], Literal['Menu']]) –
relative_to (Literal['Screen', 'Relative', 'Window', 'Client', '']) –

Return type:

None

get_coord_mode(target)[source]

Analog for A_CoordMode<target>

Parameters:: target (Union[Literal['ToolTip'], Literal['Pixel'], Literal['Mouse'], Literal['Caret'], Literal['Menu']]) –
Return type:: str

set_send_mode(mode)[source]

Analog for SendMode

Parameters:: mode (Literal['Event', 'Input', 'InputThenPlay', 'Play', '']) –
Return type:: None

get_send_mode()[source]

Return type:: str

control_click(button='L', click_count=1, options='', control='', title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for ControlClick

Parameters:

button (Literal['L', 'R', 'M', 'LEFT', 'RIGHT', 'MIDDLE']) –
click_count (int) –
options (str) –
control (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

control_get_text(*, control='', title='', text='', exclude_title='', exclude_text='', title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for ControlGetText

Parameters:

control (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

control_get_position(control='', title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog to ControlGetPos

Parameters:

control (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[Position, FutureResult[Position]]

control_send(keys, control='', title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for ControlSend

Parameters:

keys (str) –
control (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

start_hotkeys()[source]

Start the Autohotkey process for triggering hotkeys

Return type:: None

stop_hotkeys()[source]

Stop the Autohotkey process for triggering hotkeys/hotstrings

Return type:: None

set_detect_hidden_windows(value)[source]

Analog for DetectHiddenWindows

Parameters:: value (bool) – The setting value. True to turn on hidden window detection, False to turn it off.
Return type:: None

list_windows(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Enumerate all windows matching the criteria.

Analog for WinGet List subcommand <https://www.autohotkey.com/docs/v1/lib/WinGet.htm#List>_

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[List[Window], FutureResult[List[Window]]]

get_mouse_position(coord_mode=None, *, blocking=True)[source]

Analog for MouseGetPos

Parameters:

coord_mode (Optional[Literal['Screen', 'Relative', 'Window', 'Client', '']]) –
blocking (bool) –

Return type:

Union[Coordinates, FutureResult[Coordinates]]

property mouse_position: Coordinates

Convenience property for get_mouse_position()

Setter accepts a tuple of x,y coordinates passed to mouse_mouse()

mouse_move(x=None, y=None, *, speed=None, relative=False, send_mode=None, blocking=True)[source]

Analog for MouseMove

Parameters:

x (Union[str, int, None]) –
y (Union[str, int, None]) –
speed (Optional[int]) –
relative (bool) –
send_mode (Optional[Literal['Event', 'Input', 'InputThenPlay', 'Play', '']]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

a_run_script(*args, **kwargs)[source]

Deprecated. Use run_script() instead.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Union[str, FutureResult[str]]

get_active_window(blocking=True)[source]

Gets the currently active window.

Parameters:

self (AHK[Any]) –
blocking (bool) –

Return type:

Union[Window, None, FutureResult[Optional[Window]], FutureResult[Window]]

property active_window: Window | None: Gets the currently active window. Convenience property for get_active_window()

find_windows(func=None, *, title_match_mode=None, title='', text='', exclude_title='', exclude_text='', exact=None)[source]

Parameters:

func (Optional[Callable[[Window], bool]]) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
exact (Optional[bool]) –

Return type:

List[Window]

find_windows_by_class(class_name, *, exact=None, title_match_mode=None)[source]

Parameters:

class_name (str) –
exact (Optional[bool]) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –

Return type:

List[Window]

find_windows_by_text(text, exact=None, title_match_mode=None)[source]

Parameters:

text (str) –
exact (Optional[bool]) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –

Return type:

List[Window]

find_windows_by_title(title, exact=None, title_match_mode=None)[source]

Parameters:

title (str) –
exact (Optional[bool]) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –

Return type:

List[Window]

find_window(func=None, *, title_match_mode=None, title='', text='', exclude_title='', exclude_text='', exact=None)[source]

Parameters:

func (Optional[Callable[[Window], bool]]) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
exact (Optional[bool]) –

Return type:

Optional[Window]

find_window_by_class(class_name, exact=None, title_match_mode=None)[source]

Parameters:

class_name (str) –
exact (Optional[bool]) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –

Return type:

Optional[Window]

find_window_by_text(text, exact=None, title_match_mode=None)[source]

Parameters:

text (str) –
exact (Optional[bool]) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –

Return type:

Optional[Window]

find_window_by_title(title, exact=None, title_match_mode=None)[source]

Parameters:

title (str) –
exact (Optional[bool]) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –

Return type:

Optional[Window]

get_volume(device_number=1)[source]

Analog for SoundGetWaveVolume

Parameters:: device_number (int) –
Return type:: float

key_down(key, *, blocking=True)[source]

Shortcut for send_input() but transforms specified key to perform a key “DOWN” only (no release)

Parameters:

key (Union[str, Key]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

key_press(key, *, release=True, blocking=True)[source]

Press (and release) a key. Sends :py:meth:`key_down then, if release is True (the default), sends key_up() subsequently.

Parameters:

key (Union[str, Key]) –
release (bool) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

key_release(key, *, blocking=True)[source]

Alias for key_up()

Parameters:

key (Union[str, Key]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

key_state(key_name, *, mode=None, blocking=True)[source]

Analog for GetKeyState

Parameters:

key_name (str) –
mode (Optional[Literal['T', 'P']]) –
blocking (bool) –

Return type:

Union[int, float, str, None, FutureResult[str], FutureResult[int], FutureResult[float], FutureResult[None]]

key_up(key, blocking=True)[source]

Shortcut for send_input() but transforms specified key to perform a key “UP” only. Useful if the key was previously pressed down but not released.

Parameters:

key (Union[str, Key]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

key_wait(key_name, *, timeout=None, logical_state=False, released=False, blocking=True)[source]

Analog for KeyWait

Parameters:

key_name (str) –
timeout (Union[int, float, None]) –
logical_state (bool) –
released (bool) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

run_script(script_text_or_path, /, *, blocking=True, timeout=None)[source]

Run an AutoHotkey script. Can either be a path to a script (.ahk) file or a string containing script contents

Parameters:

script_text_or_path (str) –
blocking (bool) –
timeout (Optional[int]) –

Return type:

Union[str, FutureResult[str]]

set_send_level(level)[source]

Analog for SendLevel

Parameters:: level (int) –
Return type:: None

get_send_level()[source]

Get the current SendLevel (I.E. the value of A_SendLevel)

Return type:: int

send(s, *, raw=False, key_delay=None, key_press_duration=None, send_mode=None, blocking=True)[source]

Analog for Send

Parameters:

s (str) –
raw (bool) –
key_delay (Optional[int]) –
key_press_duration (Optional[int]) –
send_mode (Optional[Literal['Event', 'Input', 'InputThenPlay', 'Play', '']]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

send_raw(s, *, key_delay=None, key_press_duration=None, blocking=True)[source]

Analog for SendRaw

Parameters:

s (str) –
key_delay (Optional[int]) –
key_press_duration (Optional[int]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

send_input(s, *, blocking=True)[source]

Analog for SendInput

Parameters:

s (str) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

type(s, *, blocking=True)[source]

Like send_input() but performs necessary escapes for you.

Parameters:

s (str) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

send_play(s, *, key_delay=None, key_press_duration=None, blocking=True)[source]

Analog for SendPlay

Parameters:

s (str) –
key_delay (Optional[int]) –
key_press_duration (Optional[int]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

set_capslock_state(state=None, *, blocking=True)[source]

Analog for SetCapsLockState

Parameters:

state (Optional[Literal[True, False, 0, 1, 'On', 'Off', 'AlwaysOn', 'AlwaysOff']]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

set_numlock_state(state=None, *, blocking=True)[source]

Analog for SetCapsLockState

Parameters:

state (Optional[Literal[True, False, 0, 1, 'On', 'Off', 'AlwaysOn', 'AlwaysOff']]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

set_scroll_lock_state(state=None, *, blocking=True)[source]

Analog for SetCapsLockState

Parameters:

state (Optional[Literal[True, False, 0, 1, 'On', 'Off', 'AlwaysOn', 'AlwaysOff']]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

set_volume(value, device_number=1, *, blocking=True)[source]

Analog for SoundSetWaveVolume

Parameters:

value (int) –
device_number (int) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

show_traytip(title, text, second=None, type_id=1, *, silent=False, large_icon=False, blocking=True)[source]

Analog for TrayTip

Parameters:

title (str) –
text (str) –
second (Optional[float]) –
type_id (int) –
silent (bool) –
large_icon (bool) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

show_error_traytip(title, text, second=None, *, silent=False, large_icon=False, blocking=True)[source]

Convenience method for show_traytip() for error-style messages

Parameters:

self (AHK[Any]) –
title (str) –
text (str) –
second (Optional[float]) –
silent (bool) –
large_icon (bool) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

show_info_traytip(title, text, second=None, *, silent=False, large_icon=False, blocking=True)[source]

Convenience method for show_traytip() for info-style messages

Parameters:

self (AHK[Any]) –
title (str) –
text (str) –
second (Optional[float]) –
silent (bool) –
large_icon (bool) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

show_warning_traytip(title, text, second=None, *, silent=False, large_icon=False, blocking=True)[source]

Convenience method for show_traytip() for warning-style messages

Parameters:

self (AHK[Any]) –
title (str) –
text (str) –
second (Optional[float]) –
silent (bool) –
large_icon (bool) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

show_tooltip(text='', x=None, y=None, which=1)[source]

Analog for ToolTip

Parameters:

text (str) –
x (Optional[int]) –
y (Optional[int]) –
which (int) –

Return type:

None

hide_tooltip(which=1)[source]

Parameters:: which (int) –
Return type:: None

menu_tray_tooltip(value)[source]

Change the menu tray icon tooltip that appears when hovering the mouse over the tray icon. Does not affect tray icon for AHK processes started with run_script() or blocking=False

Uses the Tip subcommand

Parameters:: value (str) –
Return type:: None

menu_tray_icon(filename='*', icon_number=1, freeze=None)[source]

Change the tray icon menu. Does not affect tray icon for AHK processes started with run_script() or blocking=False

Uses the Icon subcommand

If called with no parameters, the tray icon will be reset to the original default.

Parameters:

filename (str) –
icon_number (int) –
freeze (Optional[bool]) –

Return type:

None

menu_tray_icon_show()[source]

Show (‘unhide’) the tray icon previously hidden by NoTrayIcon directive. Does not affect tray icon for AHK processes started with run_script() or blocking=False

Return type:: None

menu_tray_icon_hide()[source]

hides the tray icon. Does not affect tray icon for AHK processes started with run_script() or blocking=False

Return type:: None

sound_beep(frequency=523, duration=150, *, blocking=True)[source]

Analog for SoundBeep

Parameters:

frequency (int) –
duration (int) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

sound_get(device_number=1, component_type='MASTER', control_type='VOLUME', *, blocking=True)[source]

Analog for SoundGet

Parameters:

device_number (int) –
component_type (str) –
control_type (str) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

sound_play(filename, *, blocking=True)[source]

Analog for SoundPlay

Parameters:

filename (str) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

sound_set(value, device_number=1, component_type='MASTER', control_type='VOLUME', *, blocking=True)[source]

Analog for SoundSet

Parameters:

value (Union[str, int, float]) –
device_number (int) –
component_type (str) –
control_type (str) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_get(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinGet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[Window, None, FutureResult[Optional[Window]], FutureResult[Window]]

win_get_text(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

win_get_title(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

win_get_class(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinGetClass

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

win_get_position(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinGetPos

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[Position, None, FutureResult[Optional[Position]], FutureResult[Position]]

win_get_idlast(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Like the IDLast subcommand for WinGet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[Window, None, FutureResult[Optional[Window]]]

win_get_pid(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Get a window by process ID.

Like the pid subcommand for WinGet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[int, None, FutureResult[Optional[int]]]

win_get_process_name(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Get the process name of a window

Analog for ProcessName subcommand for WinGet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[None, str, FutureResult[Optional[str]]]

win_get_process_path(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Get the process path for a window.

Analog for the ProcessPath subcommand for WinGet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[str, None, FutureResult[Optional[str]]]

win_get_count(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for the Count subcommand for WinGet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[int, FutureResult[int]]

win_get_minmax(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for the MinMax subcommand for WinGet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[None, int, FutureResult[Optional[int]]]

win_get_control_list(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for the ControlList subcommand for WinGet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[List[Control], None, FutureResult[Optional[List[Control]]]]

win_get_from_mouse_position(*, blocking=True)[source]

Parameters:: blocking (bool) –
Return type:: Union[Window, None, FutureResult[Optional[Window]]]

win_exists(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

win_activate(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinActivate

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_title(new_title, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinSetTitle

Parameters:

new_title (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_always_on_top(toggle, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for AlwaysOnTop subcommand of WinSet

Parameters:

toggle (Literal['On', 'Off', 'Toggle', 1, -1, 0]) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_bottom(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for Bottom subcommand of WinSet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_top(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for Top subcommand of WinSet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_disable(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for Disable subcommand of WinSet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_enable(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for Enable subcommand of WinSet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_redraw(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for Redraw subcommand of WinSet

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_style(style, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for Style subcommand of WinSet

Parameters:

style (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

win_set_ex_style(style, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for ExStyle subcommand of WinSet

Parameters:

style (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

win_set_region(options, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for Region subcommand of WinSet

Parameters:

options (str) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

win_set_transparent(transparency, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for Transparent subcommand of WinSet

Parameters:

transparency (Union[int, Literal['Off']]) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_set_trans_color(color, title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for TransColor subcommand of WinSet

Parameters:

color (Union[int, str]) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

windows(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)

Enumerate all windows matching the criteria.

Analog for WinGet List subcommand <https://www.autohotkey.com/docs/v1/lib/WinGet.htm#List>_

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[List[Window], FutureResult[List[Window]]]

right_click(x=None, y=None, click_count=None, direction=None, *, relative=None, blocking=True, coord_mode=None, send_mode=None)[source]

Parameters:

x (Union[int, Tuple[int, int], None]) –
y (Optional[int]) –
click_count (Optional[int]) –
direction (Optional[Literal['U', 'D', 'Up', 'Down']]) –
relative (Optional[bool]) –
blocking (bool) –
coord_mode (Optional[Literal['Screen', 'Relative', 'Window', 'Client', '']]) –
send_mode (Optional[Literal['Event', 'Input', 'InputThenPlay', 'Play', '']]) –

Return type:

Optional[FutureResult[None]]

click(x=None, y=None, button=None, click_count=None, direction=None, *, relative=None, blocking=True, coord_mode=None, send_mode=None)[source]

Analog for Click

Parameters:

x (Union[int, Tuple[int, int], None]) –
y (Optional[int]) –
button (Union[int, Literal['L', 'R', 'M', 'left', 'right', 'middle', 'wheelup', 'WU', 'wheeldown', 'WD', 'wheelleft', 'WL', 'wheelright', 'WR'], str, None]) –
click_count (Optional[int]) –
direction (Optional[Literal['U', 'D', 'Up', 'Down']]) –
relative (Optional[bool]) –
blocking (bool) –
coord_mode (Optional[Literal['Screen', 'Relative', 'Window', 'Client', '']]) –
send_mode (Optional[Literal['Event', 'Input', 'InputThenPlay', 'Play', '']]) –

Return type:

Optional[FutureResult[None]]

image_search(image_path, upper_bound=(0, 0), lower_bound=None, *, color_variation=None, coord_mode=None, scale_height=None, scale_width=None, transparent=None, icon=None, blocking=True)[source]

Analog for ImageSearch

Parameters:

image_path (str) –
upper_bound (Tuple[Union[int, str], Union[int, str]]) –
lower_bound (Optional[Tuple[Union[int, str], Union[int, str]]]) –
color_variation (Optional[int]) –
coord_mode (Optional[Literal['Screen', 'Relative', 'Window', 'Client', '']]) –
scale_height (Optional[int]) –
scale_width (Optional[int]) –
transparent (Optional[str]) –
icon (Optional[int]) –
blocking (bool) –

Return type:

Union[Coordinates, None, FutureResult[Optional[Coordinates]]]

mouse_drag(x, y, *, from_position=None, speed=None, button=None, relative=None, blocking=True, coord_mode=None, send_mode=None)[source]

Analog for MouseClickDrag

Parameters:

x (int) –
y (int) –
from_position (Optional[Tuple[int, int]]) –
speed (Optional[int]) –
button (Union[int, Literal['L', 'R', 'M', 'left', 'right', 'middle', 'wheelup', 'WU', 'wheeldown', 'WD', 'wheelleft', 'WL', 'wheelright', 'WR'], str, None]) –
relative (Optional[bool]) –
blocking (bool) –
coord_mode (Optional[Literal['Screen', 'Relative', 'Window', 'Client', '']]) –
send_mode (Optional[Literal['Event', 'Input', 'InputThenPlay', 'Play', '']]) –

Return type:

Optional[FutureResult[None]]

pixel_get_color(x, y, *, coord_mode=None, alt=False, slow=False, rgb=True, blocking=True)[source]

Analog for PixelGetColor

Parameters:

x (int) –
y (int) –
coord_mode (Optional[Literal['Screen', 'Relative', 'Window', 'Client', '']]) –
alt (bool) –
slow (bool) –
rgb (bool) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

pixel_search(search_region_start, search_region_end, color, variation=0, *, coord_mode=None, fast=True, rgb=True, blocking=True)[source]

Analog for PixelSearch

Parameters:

search_region_start (Tuple[int, int]) –
search_region_end (Tuple[int, int]) –
color (Union[str, int]) –
variation (int) –
coord_mode (Optional[Literal['Screen', 'Relative', 'Window', 'Client', '']]) –
fast (bool) –
rgb (bool) –
blocking (bool) –

Return type:

Union[Coordinates, None, FutureResult[Optional[Coordinates]]]

win_close(title='', text='', seconds_to_wait=None, exclude_title='', exclude_text='', *, blocking=True, title_match_mode=None, detect_hidden_windows=None)[source]

Analog for WinClose

Parameters:

title (str) –
text (str) –
seconds_to_wait (Optional[int]) –
exclude_title (str) –
exclude_text (str) –
blocking (bool) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –

Return type:

Optional[FutureResult[None]]

win_kill(title='', text='', seconds_to_wait=None, exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinKill

Parameters:

title (str) –
text (str) –
seconds_to_wait (Optional[int]) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_minimize(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinMinimize

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_maximize(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinMaximize

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_restore(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinRestore

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_wait(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, timeout=None, blocking=True)[source]

Analog for WinWait

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
timeout (Optional[int]) –
blocking (bool) –

Return type:

Union[Window, FutureResult[Window]]

win_wait_active(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, timeout=None, blocking=True)[source]

Analog for WinWaitActive

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
timeout (Optional[int]) –
blocking (bool) –

Return type:

Union[Window, FutureResult[Window]]

win_wait_not_active(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, timeout=None, blocking=True)[source]

Analog for WinWaitNotActive

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
timeout (Optional[int]) –
blocking (bool) –

Return type:

Union[Window, FutureResult[Window]]

win_wait_close(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, timeout=None, blocking=True)[source]

Analog for WinWaitClose

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
timeout (Optional[int]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_show(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinShow

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_hide(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinHide

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

win_is_active(title='', text='', exclude_title='', exclude_text='', *, title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Check if a window is active.

Uses WinActive

Parameters:

title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Union[bool, FutureResult[bool]]

win_move(x, y, *, width=None, height=None, title='', text='', exclude_title='', exclude_text='', title_match_mode=None, detect_hidden_windows=None, blocking=True)[source]

Analog for WinMove

Parameters:

x (int) –
y (int) –
width (Optional[int]) –
height (Optional[int]) –
title (str) –
text (str) –
exclude_title (str) –
exclude_text (str) –
title_match_mode (Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', ''], Tuple[Union[Literal[1, 2, 3, 'RegEx', ''], Literal['Fast', 'Slow', '']], Union[Literal['Fast', 'Slow', ''], Literal[1, 2, 3, 'RegEx', '']]], None]) –
detect_hidden_windows (Optional[bool]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

get_clipboard(*, blocking=True)[source]

Get the string contents of the clipboard

Parameters:: blocking (bool) –
Return type:: Union[str, FutureResult[str]]

set_clipboard(s, *, blocking=True)[source]

Set the contents of the clipboard

Parameters:

s (str) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

get_clipboard_all(*, blocking=True)[source]

Get the full binary contents of the keyboard. The return value is intended to be used with set_clipboard_all()

Parameters:: blocking (bool) –
Return type:: Union[bytes, FutureResult[bytes]]

set_clipboard_all(contents, *, blocking=True)[source]

Set the full binary contents of the clipboard. Expects bytes object as returned by get_clipboard_all()

Parameters:

contents (bytes) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

on_clipboard_change(callback, ex_handler=None)[source]

call a function in response to clipboard change. Uses OnClipboardChange()

Parameters:

callback (Callable[[int], Any]) –
ex_handler (Optional[Callable[[int, Exception], Any]]) –

Return type:

None

clip_wait(timeout=None, wait_for_any_data=False, *, blocking=True)[source]

Wait until the clipboard contents change

Analog for ClipWait

Parameters:

timeout (Optional[float]) –
wait_for_any_data (bool) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

block_input(value, /)[source]

Analog for BlockInput

Parameters:: value (Literal['On', 'Off', 'Default', 'Send', 'Mouse', 'MouseMove', 'MouseMoveOff', 'SendAndMouse']) –
Return type:: None

reg_delete(key_name, value_name=None, *, blocking=True)[source]

Analog for RegDelete

Parameters:

key_name (str) –
value_name (Optional[str]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

reg_write(value_type, key_name, value_name=None, value=None, *, blocking=True)[source]

Analog for RegWrite

Parameters:

value_type (Literal['REG_SZ', 'REG_EXPAND_SZ', 'REG_MULTI_SZ', 'REG_DWORD', 'REG_BINARY']) –
key_name (str) –
value_name (Optional[str]) –
value (Optional[str]) –
blocking (bool) –

Return type:

Optional[FutureResult[None]]

reg_read(key_name, value_name=None, *, blocking=True)[source]

Analog for RegRead

Parameters:

key_name (str) –
value_name (Optional[str]) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

msg_box(text='', title='Message', buttons=MsgBoxButtons.OK, icon=None, default_button=None, modality=None, help_button=False, text_right_justified=False, right_to_left_reading=False, timeout=None, *, blocking=True)[source]

Parameters:

text (str) –
title (str) –
buttons (MsgBoxButtons) –
icon (Optional[MsgBoxIcon]) –
default_button (Optional[MsgBoxDefaultButton]) –
modality (Optional[MsgBoxModality]) –
help_button (bool) –
text_right_justified (bool) –
right_to_left_reading (bool) –
timeout (Optional[int]) –
blocking (bool) –

Return type:

Union[str, FutureResult[str]]

input_box(prompt='', title='Input', default='', hide=False, width=None, height=None, x=None, y=None, locale=True, timeout=None, *, blocking=True)[source]

Like AHK’s InputBox

If the user presses Cancel or closes the box, None is returned. Otherwise, the user’s input is returned. Raises a TimeoutError if a timeout is specified and expires.

Parameters:

prompt (str) –
title (str) –
default (str) –
hide (bool) –
width (Optional[int]) –
height (Optional[int]) –
x (Optional[int]) –
y (Optional[int]) –
locale (bool) –
timeout (Optional[int]) –
blocking (bool) –

Return type:

Union[None, str, FutureResult[str], FutureResult[None]]

file_select_box(title='Select File', multi=False, root='', filter='', save_button=False, file_must_exist=False, path_must_exist=False, prompt_create_new_file=False, prompt_override_file=False, follow_shortcuts=True, *, blocking=True)[source]

Parameters:

title (str) –
multi (bool) –
root (str) –
filter (str) –
save_button (bool) –
file_must_exist (bool) –
path_must_exist (bool) –
prompt_create_new_file (bool) –
prompt_override_file (bool) –
follow_shortcuts (bool) –
blocking (bool) –

Return type:

Union[str, None, FutureResult[str], FutureResult[None]]

folder_select_box(prompt='Select Folder', root='', chroot=False, enable_new_directories=True, edit_field=False, new_dialog_style=False, *, blocking=True)[source]

Parameters:

prompt (str) –
root (str) –
chroot (bool) –
enable_new_directories (bool) –
edit_field (bool) –
new_dialog_style (bool) –
blocking (bool) –

Return type:

Union[str, None, FutureResult[str], FutureResult[None]]

block_forever()[source]

Blocks (sleeps) forever. Utility method to prevent script from exiting.

Return type:: NoReturn

get_version()[source]

Return type:: str

get_major_version()[source]

Return type:: Literal['v1', 'v2']