Function and Script wrappers

These are higher-level wrappers representing an AHK function and an AHK script. A Function object instance is transparently callable from either Python or AHK. A Script object handles initialization automatically, provides transparent variable access, and convenience wrappers around some AHK commands.

classes

Function

class ahk.Function(name, result, args, body)

Object wrapper around ahk functions

Called Functions are automatically transform to their result by calling the provided result function on the return value from the ahk function call.

Parameters:
  • name (str) – The name of the function to wrap.
  • result (callable type (default=str)) – Type of the expected result.
  • args (str (default='()')) – The argument definition of the function.
  • body (str (default='')) – The body of the function (excluding braces).

Script

class ahk.Script(script='', filename=None)

Wrapper around ahk script commands.

Initializes the ahk script engine just like calling the low-level function ahk.start followed by ahk.ready.

variable(name, kind=<type 'str'>, value='')

Create a new ahk variable wrapper.

Wrapped variables are tracked by the instance and can be accessed as object attributes. Variables are automatically transformed to their declared kind by calling their kind with their ahk string value as the first argument (just like normal python type conversions).

Variable wrappers are already provided for the special ahk Clipboard and ErrorLevel variables (Note the case).

Note

Variables are not allowed to start with ‘_’ the underscore char!

Parameters:
  • name (str) – Then name of the new variable.
  • kind (callable type (default=str)) – Type of the variable (cast on get).
  • value (match kind or str (default='')) – Initial value of the variable.
Raises:

AttributeError if the provided name already exists in the instance as either a variable or an attribute.
function(name, result=<type 'str'>, args='()', body='')

Create a new ahk function wrapper.

Wrapped functions are tracked by the instance and can be accessed as object attributes. Functions are automatically transform to their result by calling the provided result function on the return value from the ahk function call.

Note

Function names are not allowed to start with ‘_’ the underscore char!

Parameters:
  • name (str) – The name of the function to wrap.
  • result (callable type (default=str)) – Type of the expected result.
  • args (str (default='()')) – The argument definition of the function.
  • body (str (default='')) – The body of the function (excluding braces).
Raises:

AttributeError if the indicated name is already used.
Returns:

Function wrapper object.
send(keys, mode='SendInput')

Convenience wrapper to send input to the active window.

Sends a ahk formatted series of keystrokes to the active window. See AHK docs for more details.

Parameters:
  • keys (str) – The keys to be sent.
  • mode (str) –

    The ahk command used to send keys. Valid modes:

    • Send
    • SendRaw
    • SendInput
    • SendPlay
    • SendEvent
click(button='', count=1, x=None, y=None)

Convenience wrapper to the ahk click function.

Send a mouse click of any type to any coordinate with optional repeats. See AHK docs for more details. The button argument can actually take a number of options:

  • blank - Simple primary click.
  • right - Auxiliary button click.
  • wheelup - Send mouse wheel scroll event.
  • down - Press but don’t release the primary button.
  • rel[ative] - Interpret coordinates in relative mode.
  • etc.

Button options can be composed when not mutually exclusive (e.g. “right down relative”).

Use count=0 with x and y to move the mouse without clicking.

Parameters:
  • button (str (default="")) – The mouse button(s) to click.
  • count (int (default 1)) – Number of times to repeat the click.
  • x (int) – Mouse x-coord.
  • y (int) – Mouse y-coord.
winActivate(title='', text='', extitle='', extext='', bottom=False)

Convenience wrapper for ahk WinActivate commands.

Used to set a window with provided parameters as active. If all parameters are empty the last found window is activated. See AHK docs for more details.

Parameters:
  • title (str (default="")) – Partial window title text to match.
  • text (str (default="")) – Partial window text to match.
  • extitle (str (default="")) – Partial window title text to avoid.
  • extext (str (default="")) – Partial window text to avoid.
  • bottom (bool (default=False)) – Whether to act on the bottom-most window.
winActive(title='', text='', extitle='', extext='')

Convenience wrapper for ahk IfWinActive command.

Used to check if a window with provided parameters is active. If all parameters are empty the last found window is checked. See AHK docs for more details.

Parameters:
  • title (str (default="")) – Partial window title text to match.
  • text (str (default="")) – Partial window text to match.
  • extitle (str (default="")) – Partial window title text to avoid.
  • extext (str (default="")) – Partial window text to avoid.
Returns:

The found window’s HWND or None.
winExist(title='', text='', extitle='', extext='')

Convenience wrapper for ahk IfWinExist command.

Used to check if a window with provided parameters exists. If all parameters are empty the last found window is checked. See AHK docs for more details.

Parameters:
  • title (str (default="")) – Partial window title text to match.
  • text (str (default="")) – Partial window text to match.
  • extitle (str (default="")) – Partial window title text to avoid.
  • extext (str (default="")) – Partial window text to avoid.
Returns:

The found window’s HWND or None.
waitActive(title='', text='', timeout=5, extitle='', extext='', deactivate=False)

Convenience wrapper for ahk WinWaitActive command.

Used to wait until a window matching the given parameters is activated. See AHK docs for more details.

Parameters:
  • title (str (default="")) – Partial window title text to match.
  • text (str (default="")) – Partial window text to match.
  • timeout (int or None (default=5)) – How long in seconds to wait for the window to activate. Use None to wait indefinitely.
  • extitle (str (default="")) – Partial window title text to avoid.
  • extext (str (default="")) – Partial window text to avoid.
  • deactivate (bool (default=False)) – Toggle between WinWaitActive and WinWaitNotActive.
Returns:

The True if matching window is activated, else False.
waitWindow(title='', text='', timeout=5, extitle='', extext='', closed=False)

Convenience wrapper for ahk WinWait command.

Used to wait until a window matching the given parameters exists. See AHK docs, AHK docs for more details.

Parameters:
  • title (str (default="")) – Partial window title text to match.
  • text (str (default="")) – Partial window text to match.
  • timeout (int or None (default=5)) – How long in seconds to wait for the window to activate. Use None to wait indefinitely.
  • extitle (str (default="")) – Partial window title text to avoid.
  • extext (str (default="")) – Partial window text to avoid.
  • closed (bool (default=False)) – Toggle between WinWait and WinWaitClose.
Returns:

The True if matching window is activated, else False.
convert_color(color)

Convert ahk color returned as a hex string to tuple of ints.

getPixel(x=0, y=0, opt='RGB', screen=True)

Convenince wrapper around ahk PixelGetColor

Gets the pixel color at the indicated coordinates. See AHK docs for more details.

Parameters:
  • x (int) – The pixel x coordinate (relative to screen).
  • y (int) – The pixel y coordinate (relative to screen).
  • opt (str (default='RGB')) – Space separated color picking options.
  • screen (bool (default=True)) – Flag to use screen or relative coordinates.
waitPixel(x=0, y=0, color=None, threshold=0.01, interval=0.5, timeout=False)

Wait until the pixel at given coords changes color.

This function can wait until the indicated pixel is a color, or until it changes color. If a color is not provided the current color of the pixel when the function starts is stored and compared at a regular interval until it changes or until timeout.

Parameters:
  • x (int) – The pixel x coordinate (relative to screen).
  • y (int) – The pixel y coordinate (relative to screen).
  • color (tuple(int r, int g, int b) or None) – The color to wait for.
  • threshold (float) – Error factor allowed for determining color match.
  • interval (float) – How often the pixel color is checked.
  • timeout (float or None) – How long to wait for a color match.
Returns:

True if pixel changed, False if timeout.
message(text='Alert', title='Alert', options=0, timeout=None)

Convenience wrapper to the ahk msgbox function.

Displays a message box with buttons. See AHK docs for more details.

Parameters:
  • text (str (default='Alert')) – The body text of the msgbox.
  • title (str (default='Alert')) – The title text of the msgbox.
  • options (int (default=0)) – Button flags bit-field.
  • timeout (int or None (default=None)) – Optional timeout, dialog is closed after timeout.
msgResult(name='OK')

Convenience wrapper to the ahk ifMsgBox function.

Get the clicked status of a button on the last MsgBox. See AHK docs for more details.

Parameters:name (str (default='OK')) – The name of the button to check.
Returns:True if button was pressed, None if timeout, False otherwise.