AHK

https://github.com/spyoungtech/ahk
Admin
This project likely contains AutoHotkey scripts or utilities designed to automate tasks and enhance...
Tokens:12,432
Snippets:139
Trust Score:8.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Extension output example

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Expected console output from the extension usage example.

```default
2 + 4 = 6
2 * 4 = 8
An exception was raised. Exception message was: Invalid operator: %
```

--------------------------------

### Initialize development environment

Source: https://github.com/spyoungtech/ahk/blob/main/CONTRIBUTING.md

Commands to set up the virtual environment and install development dependencies.

```bash
py -m venv venv
venv\Scripts\activate
```

```bash
pip install -r requirements-dev.txt
```

```bash
pre-commit install
```

--------------------------------

### Install AHK with binary

Source: https://github.com/spyoungtech/ahk/blob/main/docs/quickstart.md

Install the AHK package including the AutoHotkey binary via pip.

```default
py -m pip install "ahk[binary]"
```

--------------------------------

### Install AHK Python package

Source: https://github.com/spyoungtech/ahk/blob/main/docs/quickstart.md

Use pip to install the core AHK library.

```default
py -m pip install ahk
```

--------------------------------

### Execute extension methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Usage examples for the registered extension method, including error handling.

```default
# ... above code omitted for brevity
ahk = AHK(extensions='auto')

result = ahk.simple_math(2, 4, operator='+')
print('2 + 4 =', result)
assert result == 6

result = ahk.simple_math(2, 4, operator='*')
print('2 * 4 =', result)
assert result == 8

# this will raise our custom exception from our AHK code
try:
    ahk.simple_math(0, 0, operator='invalid')
except Exception as e:
    print('An exception was raised. Exception message was:', e)
```

--------------------------------

### Create a new feature branch

Source: https://github.com/spyoungtech/ahk/blob/main/CONTRIBUTING.md

Use this command to start a new branch for your contribution, following the issue number format.

```bash
git checkout -b gh-12345
```

--------------------------------

### Clipboard Management Methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods for getting, setting, and monitoring clipboard contents.

```APIDOC
## get_clipboard()

### Description
Retrieves the current text contents of the clipboard.

## set_clipboard(text)

### Description
Sets the clipboard to the provided text content.

### Parameters
- **text** (str) - Required - The text to set.

## clip_wait(timeout=None, wait_for_any_data=False)

### Description
Waits for the clipboard contents to change.

### Parameters
- **timeout** (int) - Optional - Seconds to wait.
- **wait_for_any_data** (bool) - Optional - If True, waits for any data type instead of just text.

## get_clipboard_all()

### Description
Retrieves all clipboard contents including non-text formats.

## set_clipboard_all(data)

### Description
Restores clipboard contents from data previously retrieved via get_clipboard_all.

## on_clipboard_change(callback)

### Description
Registers a callback function to execute when clipboard contents change. Requires start_hotkeys() to be called.
```

--------------------------------

### Manage Clipboard Text

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Set, get, and wait for clipboard text content changes.

```python
from ahk import AHK
ahk = AHK()

ahk.set_clipboard('hello \N{EARTH GLOBE AMERICAS}')  # set clipboard text contents
ahk.get_clipboard() # get clipboard text contents
# 'hello 🌎'
ahk.set_clipboard("")  # Clear the clipboard

ahk.clip_wait(timeout=3)  # Wait for clipboard contents to change (with text or file(s))
ahk.clip_wait(timeout=3, wait_for_any_data=True)  # wait for _any_ clipboard contents
```

--------------------------------

### Run first AHK script

Source: https://github.com/spyoungtech/ahk/blob/main/docs/quickstart.md

Initialize AHK, run a script to open Notepad, and send text to the window.

```default
from ahk import AHK
ahk = AHK()
ahk.run_script('Run Notepad')
notepad_window = ahk.win_get(title='Untitled - Notepad')
notepad_window.send('Hello World')
```

--------------------------------

### Initialize and use AsyncAHK

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Demonstrates basic usage of the AsyncAHK class with async/await syntax for mouse operations.

```python
from ahk import AsyncAHK
import asyncio
ahk = AsyncAHK()

async def main():
    await ahk.mouse_move(100, 100)
    x, y = await ahk.get_mouse_position()
    print(x, y)

asyncio.run(main())
```

--------------------------------

### Initialize AHK with extensions

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Demonstrates how to instantiate the AHK class with automatic extension loading.

```default
ahk = AHK(extensions='auto')
print(ahk.simple_math(2, 2, '+')) # 4
```

--------------------------------

### Using an AHK extension

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Demonstrates how to import and enable extensions when instantiating the AHK class.

```python
from my_great_extension import the_extension
from ahk import AHK
ahk = AHK(extensions='auto')  # use all available/imported extensions
ahk.my_great_method('foo', 'bar', 'baz')  # new methods are available from the extension!
```

--------------------------------

### Keyboard Input and State Control with AHK

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Demonstrates typing, sending raw input, checking key states, and managing key events. Requires the AHK library initialized as an object.

```python
from ahk import AHK

ahk = AHK()

ahk.type('hello, world!')  # Send keys, as if typed (performs string escapes for you)
ahk.send_input('Hello, {U+1F30E}{!}')  # Like AHK SendInput
                                   # Unlike `type`, control sequences must be escaped manually.
                                   # For example the characters `!^+#=` and braces (`{` `}`) must be escaped manually.
ahk.key_state('Control')  # Return True or False based on whether Control key is pressed down
ahk.key_state('CapsLock', mode='T')  # Check toggle state of a key (like for NumLock, CapsLock, etc)
ahk.key_press('a')  # Press and release a key
ahk.key_down('Control')  # Press down (but do not release) Control key
ahk.key_up('Control')  # Release the key
ahk.set_capslock_state("On")  # Turn CapsLock on
if ahk.key_wait('x', timeout=3):  # wait for a key to be pressed; returns a boolean
    print('X was pressed within 3 seconds')
else:
    print('X was not pressed within 3 seconds')
```

--------------------------------

### Load extension via includes

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Configuring an extension to load AutoHotkey code from an external file.

```default
from ahk.extensions import Extension
my_extension = Extension(includes=['myscript.ahk']) # equivalent to "#Include myscript.ahk"
```

--------------------------------

### Initializing AHK with extensions

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

When an extension is provided to the AHK constructor, its dependencies are automatically included.

```default
from ahk import AHK
from my_extension import MY_EXTENSION

ahk = AHK(extensions=[MY_EXTENSION], version='v1')  # same effect as extensions=[JXON, MY_EXTENSION]
```

--------------------------------

### GUI and Dialog Methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods for displaying tooltips, tray notifications, and various system dialog boxes.

```APIDOC
## show_tooltip(text, x, y)
Displays a tooltip at the specified coordinates.

## hide_tooltip()
Hides the currently displayed tooltip.

## show_info_traytip(title, text, silent, blocking)
Displays an information tray notification.

## show_warning_traytip(title, text)
Displays a warning tray notification.

## show_error_traytip(title, text)
Displays an error tray notification.

## msg_box(text, title, buttons)
Displays a message box with optional buttons.

## input_box(prompt, title, hide)
Displays an input dialog box, optionally masking the input.

## file_select_box(title, multi, filter, file_must_exist)
Opens a file selection dialog.

## folder_select_box(prompt)
Opens a folder selection dialog.
```

--------------------------------

### Initialize AHK for version 2

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Configure the AHK instance to use AutoHotkey v2 by providing the explicit path or the version keyword argument.

```python
from ahk import AHK


ahk = AHK(executable_path=r'C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe')
# OR
ahk = AHK(version='v2')
```

--------------------------------

### Retrieve Windows with AHK

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Demonstrates various ways to obtain window references, including by title, PID, mouse position, or listing all windows. Includes a timeout-based wait mechanism for specific windows.

```python
from ahk import AHK

ahk = AHK()

win = ahk.active_window                        # Get the active window
win = ahk.win_get(title='Untitled - Notepad')  # by title
all_windows = ahk.list_windows()               # list of all windows
win = ahk.win_get_from_mouse_position()        # the window under the mouse cursor
win = ahk.win_get(title='ahk_pid 20366')       # get window from pid

# Wait for a window
try:
    # wait up to 5 seconds for notepad
    win = ahk.win_wait(title='Untitled - Notepad', timeout=5)
    # see also: win_wait_active, win_wait_not_active
except TimeoutError:
    print('Notepad was not found!')
```

--------------------------------

### Run pre-commit hooks

Source: https://github.com/spyoungtech/ahk/blob/main/CONTRIBUTING.md

Executes all configured pre-commit hooks across the entire repository.

```bash
pre-commit run --all-files
```

--------------------------------

### Registering a Hotkey Callback

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Uses the AHK library to bind a keyboard shortcut to a Python function. Requires calling start_hotkeys() to initialize the background thread.

```python
from ahk import AHK

def my_callback():
    print('Hello callback!')

ahk = AHK()
# when WIN + n is pressed, fire `my_callback`
ahk.add_hotkey('#n', callback=my_callback)
ahk.start_hotkeys()  # start the hotkey process thread
ahk.block_forever()  # not strictly needed in all scripts -- stops the script from exiting; sleep forever
```

--------------------------------

### Control Audio and Sound Devices with AHK

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Use these methods to play audio files, generate beeps, and manage system volume or device properties.

```python
from ahk import AHK

ahk = AHK()

ahk.sound_play('C:\\path\\to\\sound.wav')  # Play an audio file
ahk.sound_beep(frequency=440, duration=1000)  # Play a beep for 1 second (duration in microseconds)
ahk.get_volume(device_number=1)  # Get volume of a device
ahk.set_volume(50, device_number=1)  # Set volume of a device
ahk.sound_get(device_number=1, component_type='MASTER', control_type='VOLUME') # Get sound device property
ahk.sound_set(50, device_number=1, component_type='MASTER', control_type='VOLUME') # Set sound device property
```

--------------------------------

### Defining an extension with dependencies

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Declare dependencies by passing a list of Extension objects to the dependencies keyword argument.

```default
from ahk_json import JXON  # pip install ahk-json
my_extension_script = '''\
MyAHKFunction(one, two) {
   val := Array(one, two)
   ret := Jxon_Dump(val) ; `Jxon_Dump` is provided by the dependent extension!
   return FormatResponse("ahk_json.message.JsonResponseMessage", ret) ; this message type is also part of the extension
}
'''
MY_EXTENSION = Extension(script_text=my_extension_script, dependencies=[JXON], requires_autohotkey='v1')

@MY_EXTENSION.register
def my_function(ahk: AHK, one: str, two: str) -> list[str]:
    args = [one, two]
    return ahk.function_call('MyAHKFunction', args)
```

--------------------------------

### Initialize AHK with executable path

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Manually specify the location of the AutoHotkey executable during AHK class initialization.

```python
from ahk import AHK

ahk = AHK(executable_path='C:\\path\\to\\AutoHotkey.exe')
```

--------------------------------

### Manage Tray Icon

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Customize the tray icon, tooltip, and visibility using the AHK instance methods.

```python
from ahk import AHK
ahk = AHK()

# change the tray icon (in this case, using a builtin system icon)
ahk.menu_tray_icon('Shell32.dll', 174)
# revert it back to the original:
ahk.menu_tray_icon()

# change the tooltip that shows up when hovering the mouse over the tray icon
ahk.menu_tray_tooltip('My Program Name')

# Hide the tray icon
ahk.menu_tray_icon_hide()

# Show the tray icon that was previously hidden by ``NoTrayIcon`` or ``menu_tray_icon_hide``
ahk.menu_tray_icon_show()
```

--------------------------------

### Control mouse with AHK

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Initialize the AHK client to perform mouse movements and retrieve the current mouse position.

```python
from ahk import AHK

ahk = AHK()

ahk.mouse_move(x=100, y=100, blocking=True)  # Blocks until mouse finishes moving (the default)
ahk.mouse_move(x=150, y=150, speed=10, blocking=True) # Moves the mouse to x, y taking 'speed' seconds to move
print(ahk.mouse_position)  #  (150, 150)
```

--------------------------------

### Display Tooltips and Traytips

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Manage desktop notifications and tooltips. Note that blocking traytips will pause execution until dismissed.

```python
import time
from ahk import AHK

ahk = AHK()
ahk.show_tooltip("hello4", x=10, y=10)
time.sleep(2)
ahk.hide_tooltip() # hide the tooltip
ahk.show_info_traytip("Info", "It's also info", silent=False, blocking=True)  # Default info traytip
ahk.show_warning_traytip("Warning", "It's a warning")                           # Warning traytip
ahk.show_error_traytip("Error", "It's an error")                                 # Error trytip
```

--------------------------------

### Handle ClipboardAll Data

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Save and restore all clipboard formats. Only restore data exactly as returned by get_clipboard_all.

```python
from ahk import AHK
ahk = AHK()

# save all clipboard contents in all formats
saved_clipboard = ahk.get_clipboard_all()
ahk.set_clipboard('something else')
...
ahk.set_clipboard_all(saved_clipboard)  # restore saved content from earlier
```

--------------------------------

### Register sync and async extension methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Providing both synchronous and asynchronous implementations for an extension function.

```default
@my_extension.register
def my_function(ahk: AHK, foo, bar):
    ...

@my_extension.register
async def my_function(ahk: AsyncAHK, foo, bar):
    ...
```

--------------------------------

### Monitor Clipboard Changes

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Register a callback function to execute when clipboard contents change. Requires calling start_hotkeys().

```python
from ahk import AHK
ahk = AHK()
def my_clipboard_callback(change_type: int):
    if change_type == 0:
        print('Clipboard is now empty')
    elif change_type == 1:
        print('Clipboard has text contents')
    elif change_type == 2:
        print('Clipboard has non-text contents')

ahk.on_clipboard_change(my_clipboard_callback)
ahk.start_hotkeys()  # like with hotkeys, must be called at least once for listening to start
# ...
ahk.set_clipboard("hello") # will cause the message "Clipboard has text contents" to be printed by the callback
ahk.set_clipboard("") # Clears the clipboard, causing the message "Clipboard is now empty" to be printed by the callback
```

--------------------------------

### Window Retrieval Methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods available on the AHK instance to retrieve window objects.

```APIDOC
### AHK.active_window
Returns the currently active window.

### AHK.win_get(title=None)
Retrieves a window by its title or ahk_pid.

### AHK.list_windows()
Returns a list of all windows.

### AHK.win_get_from_mouse_position()
Retrieves the window currently under the mouse cursor.

### AHK.win_wait(title=None, timeout=None)
Waits for a window to exist, optionally with a timeout.
```

--------------------------------

### Create Dialog Boxes

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Interact with users through message boxes, input prompts, and file or folder selection dialogs.

```python
from ahk import AHK, MsgBoxButtons
ahk = AHK()

ahk.msg_box(text='Do you like message boxes?', title='My Title', buttons=MsgBoxButtons.YES_NO)
ahk.input_box(prompt='Password', title='Enter your password', hide=True)
ahk.file_select_box(title='Select one or more mp3 files', multi=True, filter='*.mp3', file_must_exist=True)
ahk.folder_select_box(prompt='Select a folder')
```

--------------------------------

### Keyboard Interaction Methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods for typing text, sending raw input, managing key states, and waiting for key events.

```APIDOC
## Keyboard Methods

### type(text)
- **Description**: Sends keys as if typed, performing string escapes automatically.

### send_input(keys)
- **Description**: Sends raw input like AHK SendInput. Control sequences must be escaped manually.

### key_state(key, mode=None)
- **Description**: Returns True or False based on whether a key is pressed down or its toggle state.

### key_press(key)
- **Description**: Presses and releases a key.

### key_down(key)
- **Description**: Presses down a key without releasing it.

### key_up(key)
- **Description**: Releases a key.

### set_capslock_state(state)
- **Description**: Sets the state of the CapsLock key (e.g., "On").

### key_wait(key, timeout=None)
- **Description**: Waits for a key to be pressed. Returns a boolean indicating if the key was pressed within the timeout.
```

--------------------------------

### Specify AHK executable path

Source: https://github.com/spyoungtech/ahk/blob/main/docs/quickstart.md

Manually define the path to the AutoHotkey executable if it is not found automatically.

```default
ahk = AHK(executable_path='C:\\Path\\To\\AutoHotkey.exe')
```

--------------------------------

### Register Python extension method

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Creates an Extension instance and registers a Python function to call the underlying AHK logic.

```default
from ahk import AHK
from ahk.extensions import Extension
from typing import Literal

script_text = r'''
; a string of your AHK script
; Omitted here for brevity -- copy/paste from the previous code block
'''
simple_math_extension = Extension(script_text=script_text)

@simple_math_extension.register  # register the method for the extension
def simple_math(ahk: AHK, lhs: int, rhs: int, operator: Literal['+', '*']) -> int:
    assert isinstance(lhs, int)
    assert isinstance(rhs, int)
    # assert operator in ('+', '*')  # we'll leave this out so we can demo raising exceptions from AHK
    args = [str(lhs), str(rhs), operator]  # all args must be strings
    result = ahk.function_call('SimpleMath', args, blocking=True)
    return result
```

--------------------------------

### Sound Control Methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods for playing audio, generating beeps, and managing system sound device volumes and properties.

```APIDOC
## sound_play(path)
Plays an audio file from the specified path.

## sound_beep(frequency, duration)
Plays a beep sound at a specific frequency for a given duration in milliseconds.

## get_volume(device_number)
Retrieves the current volume level of the specified device.

## set_volume(level, device_number)
Sets the volume level for the specified device.

## sound_get(device_number, component_type, control_type)
Retrieves a specific property from a sound device.

## sound_set(value, device_number, component_type, control_type)
Sets a specific property for a sound device.
```

--------------------------------

### Global State Configuration

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods to configure global AutoHotkey settings that affect subsequent operations.

```APIDOC
## set_coord_mode(target, mode)
Sets the coordinate mode for mouse or other operations.

## set_detect_hidden_windows(enabled)
Configures whether hidden windows are detected.

## set_send_level(level)
Sets the send level for keyboard/mouse events.

## set_title_match_mode(mode)
Sets the mode for window title matching.

## set_send_mode(mode)
Sets the default send mode for input events.
```

--------------------------------

### Perform Registry Operations

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Read, write, and delete registry keys. Exceptions are raised if the key does not exist or an error occurs.

```python
from ahk import AHK
ahk = AHK()

ahk.reg_write('REG_SZ', r'HKEY_CURRENT_USER\SOFTWARE\my-software', value='test')
ahk.reg_write('REG_SZ', r'HKEY_CURRENT_USER\SOFTWARE\my-software', value_name='foo', value='bar')
ahk.reg_read(r'HKEY_CURRENT_USER\SOFTWARE\my-software')  # 'test'
ahk.reg_delete(r'HKEY_CURRENT_USER\SOFTWARE\my-software')
```

--------------------------------

### Execute non-blocking mouse movement

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Demonstrates moving the mouse slowly while simultaneously reporting its position in a loop.

```python
import time

from ahk import AHK

ahk = AHK()

ahk.mouse_position = (200, 200)  # Moves the mouse instantly to the start position
start = time.time()

# move the mouse very slowly
ahk.mouse_move(x=100, y=100, speed=30, blocking=False)

# This code begins executing right away, even though the mouse is still moving
while True:
    t = round(time.time() - start, 4)
    position = ahk.mouse_position
    print(t, position) #  report mouse position while it moves
    if position == (100, 100):
        break
```

--------------------------------

### Manipulate Windows and Controls

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Covers window object methods for state management, style adjustments, and control interaction. Note that many methods have direct equivalents on the AHK class instance.

```python
from ahk import AHK

ahk = AHK()

ahk.run_script('Run Notepad') # Open notepad
win = ahk.find_window(title='Untitled - Notepad') # Find the opened window; returns a `Window` object

# Window object methods
win.send('hello', control='Edit1')  # Send keys directly to the window (does not need focus!)
# OR ahk.control_send(title='Untitled - Notepad', control='Edit1')
win.move(x=200, y=300, width=500, height=800)

win.activate()                  # Give the window focus
win.close()                     # Close the window
win.hide()                      # Hide the window
win.kill()                      # Kill the window
win.maximize()                  # Maximize the window
win.minimize()                  # Minimize the window
win.restore()                   # Restore the window
win.show()                      # Show the window
win.disable()                   # Make the window non-interactable
win.enable()                    # Enable it again
win.to_top()                    # Move the window on top of other windows
win.to_bottom()                 # Move the window to the bottom of the other windows
win.get_class()                 # Get the class name of the window
win.get_minmax()                # Get the min/max status
win.get_process_name()          # Get the process name (e.g., "notepad.exe")
win.process_name                # Property; same as `.get_process_name()` above
win.is_always_on_top()          # Whether the window has the 'always on top' style applied
win.list_controls()             # Get a list of controls (list of `Control` objects)
win.redraw()                    # Redraw the window
win.set_style("-0xC00000")      # Set a style on the window (in this case, removing the title bar)
win.set_ex_style("^0x80")       # Set an ExStyle on the window (in this case, removes the window from alt-tab list)
win.set_region("")              # See: https://www.autohotkey.com/docs/v2/lib/WinSetRegion.htm
win.set_trans_color("White")    # Makes all pixels of the chosen color invisible inside the specified window.
win.set_transparent(155)        # Makes the specified window semi-transparent (or "Off" to turn off transparency)


win.always_on_top = 'On' # Make the window always on top
# or
win.set_always_on_top('On')

for window in ahk.list_windows():  # list all (non-hidden) windows -- ``detect_hidden_windows=True`` to include hidden
    print(window.title)

    # Some more attributes
    print(window.text)           # window text -- or .get_text()
    print(window.get_position()) # (x, y, width, height)
    print(window.id)             # the ahk_id of the window
    print(window.pid)            # process ID -- or .get_pid()
    print(window.process_path)   # or .get_process_path()


if win.active:        # or win.is_active()
    ...

if win.exist:         # or win.exists()
    ...

# Controls

edit_control = win.list_controls()[0]  # get the first control for the window, in this case "Edit1" for Notepad
edit_control.get_text()      # get the text in Notepad
edit_control.get_position()  # returns a `Postion` namedtuple: e.g. Position(x=6, y=49, width=2381, height=1013)
```

--------------------------------

### Execute AutoHotkey scripts

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Use run_script to execute either a string of AHK code or a path to an existing .ahk file.

```python
from ahk import AHK
ahk = AHK()
my_script = '''\
MouseMove, 100, 100
; etc...
'''

ahk.run_script(my_script)
```

```python
from ahk import AHK
ahk = AHK()
script_path = r'C:\Path\To\myscript.ahk'
ahk.run_script(script_path)
```

--------------------------------

### Implement AutoHotkey function

Source: https://github.com/spyoungtech/ahk/blob/main/CONTRIBUTING.md

Define the AHK function in the daemon template, ensuring it returns a formatted response.

```AutoHotkey
AHKSimpleMath(lhs, rhs, operator) {
    if (operator = "+") {
        result := (lhs + rhs)
    } else if (operator = "*") {
        result := (lhs * rhs)
    } else { ; invalid operator argument
        return FormatResponse("ahk.message.ExceptionResponseMessage", Format("Invalid operator: {}", operator))
    }
    return FormatResponse("ahk.message.IntegerResponseMessage", result)
}
```

--------------------------------

### Window Object Methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods available on a Window object to perform actions on a specific window.

```APIDOC
### Window.activate()
Gives the window focus.

### Window.close()
Closes the window.

### Window.move(x, y, width, height)
Moves and resizes the window.

### Window.send(keys, control=None)
Sends keystrokes to the window or a specific control.

### Window.hide() / Window.show()
Hides or shows the window.

### Window.minimize() / Window.maximize() / Window.restore()
Changes the window state.

### Window.kill()
Forcefully terminates the window process.
```

--------------------------------

### Screen Interaction Methods

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods for interacting with the screen, including image searching and pixel color retrieval.

```APIDOC
## image_search(image_path, upper_bound=None, lower_bound=None)

### Description
Searches for an image on the screen within optional boundaries.

### Parameters
- **image_path** (str) - Required - Path to the image file.
- **upper_bound** (tuple) - Optional - Coordinates (x, y) for the upper-left corner of the search area.
- **lower_bound** (tuple) - Optional - Coordinates (x, y) for the lower-right corner of the search area.

## pixel_get_color(x, y)

### Description
Retrieves the color of a pixel at the specified coordinates.

### Parameters
- **x** (int) - Required - X coordinate.
- **y** (int) - Required - Y coordinate.

## pixel_search(color, search_region_start, search_region_end)

### Description
Searches for the first pixel matching a specified color within a defined region.

### Parameters
- **color** (str) - Required - Hex color code.
- **search_region_start** (tuple) - Required - Starting coordinates (x, y).
- **search_region_end** (tuple) - Required - Ending coordinates (x, y).
```

--------------------------------

### Apply NoTrayIcon Directive in Python

Source: https://github.com/spyoungtech/ahk/blob/main/docs/api/methods.md

Pass directives as a list during AHK class initialization to configure script behavior.

```python
from ahk import AHK
from ahk.directives import NoTrayIcon
ahk = AHK(directives=[NoTrayIcon])
```

--------------------------------

### AHK Hotkey API

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods for registering, managing, and controlling hotkey processes.

```APIDOC
## add_hotkey(hotkey, callback, ex_handler=None)

### Description
Registers a hotkey to trigger a Python function callback. An optional exception handler can be provided to manage errors within the callback.

### Parameters
- **hotkey** (str) - Required - The key combination string (e.g., '#n').
- **callback** (callable) - Required - The function to execute when the hotkey is pressed.
- **ex_handler** (callable) - Optional - A function to handle exceptions raised by the callback.

## remove_hotkey(hotkey)

### Description
Removes a specific hotkey registration by its keyname.

### Parameters
- **hotkey** (str) - Required - The key combination string to remove.

## clear_hotkeys()

### Description
Removes all registered hotkeys.

## start_hotkeys()

### Description
Starts the background process thread required to listen for hotkey events.

## stop_hotkeys()

### Description
Stops the background process thread for hotkeys.
```

--------------------------------

### Configure AHK Directives

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Add directives to all generated scripts, such as hiding the tray icon, by passing them to the AHK constructor.

```python
from ahk import AHK
from ahk.directives import NoTrayIcon

ahk = AHK(directives=[NoTrayIcon])
```

```python
from ahk import AHK
from ahk.directives import NoTrayIcon

directives = [
    NoTrayIcon(apply_to_hotkeys_process=True)
]

ahk = AHK(directives=directives)
```

--------------------------------

### Run tests with tox

Source: https://github.com/spyoungtech/ahk/blob/main/CONTRIBUTING.md

Executes the test suite within an isolated environment using tox.

```bash
tox -e py
```

--------------------------------

### Implement Python async method

Source: https://github.com/spyoungtech/ahk/blob/main/CONTRIBUTING.md

Add the method to the AsyncAHK class, ensuring arguments are strings and the function call is awaited.

```python
async def simple_math(self, lhs: int, rhs: int, operator: Literal['+', '*']) -> int:
    """
    Exposes arithmetic functions in AutoHotkey for plus and times operators
    """
    assert isinstance(lhs, int)
    assert isinstance(rhs, int)

    # Normally, you probably want to validate all inputs, but we'll comment this out to demo bubbling up AHK exceptions
    # assert operator in ('+', '*')

    args = [str(lhs), str(rhs), operator]  # all args must be strings
    result = await self._transport.function_call('AHKSimpleMath', args, blocking=True)
    return result
```

--------------------------------

### Perform Screen Operations

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Use image search and pixel color retrieval to interact with screen elements.

```python
from ahk import AHK

ahk = AHK()

ahk.image_search('C:\\path\\to\\image.jpg')  # Find an image on screen

# Find an image within a boundary on screen
ahk.image_search('C:\\path\\to\\image.jpg', upper_bound=(100, 100),  # upper-left corner of search area
                                            lower_bound=(400, 400))  # lower-right corner of search area
ahk.pixel_get_color(100, 100)  # Get color of pixel located at coords (100, 100)
ahk.pixel_search(color='0x9d6346', search_region_start=(0, 0), search_region_end=(500, 500))  # Get coords of the first pixel with specified color
```

--------------------------------

### Manage Hotstrings with AHK

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Register hotstrings for simple string replacement or to trigger Python callbacks. Use the provided methods to remove specific hotstrings or clear all registered ones.

```python
from ahk import AHK
ahk = AHK()

def my_callback():
    print('hello callback!')

ahk.add_hotstring('btw', 'by the way')  # string replacements
ahk.add_hotstring('btw', my_callback) # call python function in response to the hotstring
```

```python
ahk.remove_hotstring('btw')  # remove a hotstring by its trigger sequence
ahk.clear_hotstrings()  # remove all registered hotstrings
```

--------------------------------

### Configure Global AHK State

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Modify global settings like coordinate modes, window detection, and send modes to affect subsequent library calls.

```python
from ahk import AHK

ahk = AHK()

ahk.set_coord_mode('Mouse', 'Screen')  # set default Mouse CoordMode to be relative to Screen
ahk.set_detect_hidden_windows(True) # Turn on detect hidden windows by default
ahk.set_send_level(5)  # Change send https://www.autohotkey.com/docs/v1/lib/SendLevel.htm

ahk.set_title_match_mode('Slow') # change title match speed and/or mode
ahk.set_title_match_mode('RegEx')
ahk.set_title_match_mode(('RegEx', 'Slow'))  # or both at the same time
ahk.set_send_mode('Event')  # change the default SendMode
```

--------------------------------

### Configure AHK path via environment variable

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Set the AHK_PATH environment variable to define the executable location before running the Python script.

```console
set AHK_PATH=C:\Path\To\AutoHotkey.exe
python myscript.py
```

--------------------------------

### Run tests with pytest

Source: https://github.com/spyoungtech/ahk/blob/main/CONTRIBUTING.md

Executes tests directly using pytest. Ensure code generation is performed before running.

```bash
pytest tests
```

--------------------------------

### Mouse Control

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods for retrieving mouse coordinates, moving the mouse, and performing click actions.

```APIDOC
## mouse_position

### Description
Property to get or set the mouse coordinates. Getting returns a tuple (x, y) relative to the active window. Setting moves the mouse to absolute screen coordinates.

## get_mouse_position(coord_mode='Screen')

### Description
Retrieves mouse coordinates with a specified coordinate mode.

## mouse_move(x, y, speed=None, relative=False)

### Description
Moves the mouse to the specified coordinates.

## click(x=None, y=None, coord_mode='Window', button='L', click_count=1)

### Description
Performs a mouse click at the specified location or current position.

## right_click()

### Description
Performs a right-click action.

## mouse_drag(x, y, relative=False)

### Description
Holds down the primary mouse button and moves the mouse to the target coordinates.
```

--------------------------------

### Registering an extension for multiple AutoHotkey versions

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Use the requires_autohotkey keyword to specify compatibility and register the same Python function to multiple extension objects.

```default
my_extension_v1 = Extension(..., requires_autohotkey='v1')
my_extension_v2 = Extension(..., requires_autohotkey='v1')

@my_extension_v1.register
@my_extension_v2.register
def my_extension_function(ahk: AHK, foo, bar, baz) -> Any:
   ...
```

--------------------------------

### Test asynchronous implementation

Source: https://github.com/spyoungtech/ahk/blob/main/CONTRIBUTING.md

Create test cases using pytest and IsolatedAsyncioTestCase to verify the new functionality.

```python
import unittest

import pytest

from ahk import AsyncAHK

class MathTestCases(unittest.IsolatedAsyncioTestCase):
    async def test_simple_math_plus_operator(self):
        ahk = AsyncAHK()
        result = await ahk.simple_math(1, 2, '+')
        expected = 3
        assert result == expected

    async def test_simple_math_times_operator(self):
        ahk = AsyncAHK()
        result = await ahk.simple_math(2, 3, '*')
        expected = 6
        assert result == expected

    async def test_simple_math_bad_operator(self):
        with pytest.raises(Exception) as exc_info:
            await ahk.simple_math(1, 2, '>>>')
        assert "Invalid operator:" in str(exc_info.value)
```

--------------------------------

### Hotstring Management

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Methods for adding, removing, and clearing hotstrings, including support for string replacements and Python callbacks.

```APIDOC
## add_hotstring(trigger, replacement)

### Description
Registers a hotstring trigger. If the replacement is a string, it performs a text replacement. If it is a callable, it executes the Python function when triggered.

### Parameters
- **trigger** (str) - Required - The sequence that triggers the hotstring.
- **replacement** (str|callable) - Required - The string to type or the function to execute.

## remove_hotstring(trigger)

### Description
Removes a previously registered hotstring by its trigger sequence.

### Parameters
- **trigger** (str) - Required - The trigger sequence to remove.

## clear_hotstrings()

### Description
Removes all registered hotstrings.
```

--------------------------------

### Implement a custom ResponseMessage

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

Subclass ResponseMessage and implement the unpack method to return custom types like datetime objects.

```python
import datetime
from ahk.message import IntegerResponseMessage
class DatetimeResponseMessage(IntegerResponseMessage):
    def unpack(self) -> datetime.datetime:
        val = super().unpack()  # get the integer timestamp
        return datetime.datetime.fromtimestamp(val)
```

--------------------------------

### Handling Exceptions in Hotkey Callbacks

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Defines an exception handler to catch and process errors occurring within a hotkey callback function.

```python
from ahk import AHK
ahk = AHK()

def go_boom():
    raise Exception('boom!')

def my_ex_handler(hotkey: str, exception: Exception):
    print('exception with callback for hotkey', hotkey, 'Here was the error:', exception)

ahk.add_hotkey('#n', callback=go_boom, ex_handler=my_ex_handler)
```

--------------------------------

### Define AHK extension function

Source: https://github.com/spyoungtech/ahk/blob/main/docs/extending.md

An AutoHotkey function that processes arguments and returns a formatted response using FormatResponse.

```default
SimpleMath(lhs, rhs, operator) {
    if (operator = "+") {
        result := (lhs + rhs)
    } else if (operator = "*") {
        result := (lhs * rhs)
    } else { ; invalid operator argument
        return FormatResponse("ahk.message.ExceptionResponseMessage", Format("Invalid operator: {}", operator))
    }
    return FormatResponse("ahk.message.IntegerResponseMessage", result)
}
```

--------------------------------

### Retrieve results from non-blocking calls

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Shows how to use the FutureResult object returned by non-blocking calls to wait for completion.

```python
from ahk import AHK
ahk = AHK()
future_result = ahk.mouse_move(100, 100, speed=40, blocking=False)
...
# wait on the mouse_move to finish
future_result.result(timeout=10) # timeout keyword is optional
```

--------------------------------

### Control Mouse Operations

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Perform mouse movements, clicks, and drags using absolute or relative coordinates. Supports different coordinate modes and button configurations.

```python
from ahk import AHK

ahk = AHK()

ahk.mouse_position  # Returns a tuple of mouse coordinates (x, y) (relative to active window)
ahk.get_mouse_position(coord_mode='Screen') # get coordinates relative to the screen
ahk.mouse_move(100, 100, speed=10, relative=True)  # Moves the mouse reletave to the current position
ahk.mouse_position = (100, 100)  # Moves the mouse instantly to absolute screen position
ahk.click()  # Click the primary mouse button
ahk.click(200, 200)  # Moves the mouse to a particular position and clicks (relative to active window)
ahk.click(100, 200, coord_mode='Screen') # click relative to the screen instead of active window
ahk.click(button='R', click_count=2) # Clicks the right mouse button twice
ahk.right_click() # Clicks the secondary mouse button
ahk.mouse_drag(100, 100, relative=True) # Holds down primary button and moves the mouse
```

--------------------------------

### Removing Hotkeys

Source: https://github.com/spyoungtech/ahk/blob/main/docs/README.md

Provides methods to remove specific hotkeys by name or clear all registered hotkeys.

```python
# ...
ahk.remove_hotkey('#n') # remove a hotkey by its keyname
ahk.clear_hotkeys()  # remove all hotkeys
```
Tokens:
Raw