1. What is AHK scripting language
2. Proxy32 components to support integration with AHK
    2.1 LAUNCH launcher and VIEWER launcher
    2.2 E-SCRIPT Launcher
    2.3 Window handles passed by Proxy32 as parameters
    2.4 User-pointed coordinates passed by Proxy32 as parameters
3. Examples and use cases

1. What is AHK scripting language

AutoHotKey (AHK) is scripting language to automate GUI manipulation in Windows GUI environment.

Proxy32 includes its own basic and simple GUI automation capabilities which do not include loops, conditional execution, files input/output etc. For serious automation tasks one will need to use AHK. There was also older similar language called "MortScript" (it is still included with Proxy32) but it is no longer supported by its developer. Proxy32 comes with pre-installed AHK Unicode 32 bit version 1.1.14.03 (Proxy32 user can replace it by newer versions if needed).

For example, AHK can find certain application window in the Windows GUI environment and then manipulate that window, for example, change size and position of such window and send keystrokes and mouse clicks into such window. To be able to do such things and more, user will have to learn AHK syntax first. After learning syntax user should be able to write AHK scripts and pass them for execution to AHK interpreter. Any scripting language that can access Win32 API calls will potentially be able to do the same job, but AHK seems better alternative for small tasks (once AHK syntax is learned) as it has convenient built-in primitives to manipulate windows and simulate user input.

2. Proxy32 components to support integration with AHK

Proxy32 can help user to work with AHK. For example, to simplify managing collection of AHK scripts and to simplify passing selected scripts for execution by AHK interpreter. It is also possible to pass to AHK script certain parameters, such as target window handles and target user mouse coordinates. Those parameters can be preset by user via Proxy32 Window manager.

2.1 LAUNCH launcher and VIEWER launcher

After Proxy32 installtion AHK interpreter is located at ./gui/ahk/AutoHotkeyU32.exe.
For all processes that are started by Proxy32 process PATH environment variable has ./gui/ahk/ added, so that AHK interpreter can be called as AutoHotkeyU32.exe without specifying path to executable.
where . directory is referring to Proxy32 installation directory.

Therefore, one can use LAUNCH launcher in proxy32 to start AHK interpreter and pass AHK script file to interpreter via command line. And also pass command line (positional) parameters to AHK script.

Fig.1 LAUNCH launcher to execute AHK interpreter with the script file and script parameter

Fig.2 The same LAUNCH launcher shown in the Launcher Editor Dialog

There are certain Proxy32 parameters that can be passed to the AHK script to ensure better integration. In above example, handle of the active (target) Proxy32 window is passed to the AHK script to act upon it.

Fig.3 5 AHK-integration parameters (starting from highlighted) that can be inserted via "Insert New Proxy Parameter/Password" dialog that can be invoked via button from the launcher editor

VIEWER launcher helps to quickly edit AHK script file and attach it to the Proxy32 configuration tree for the purposes of export and import. Executing (double-click) VIEWER launcher will show .ahk file in the Notepad.

Fig.4 Executing VIEWER launcher shows AHK script code in the Notepad

One can see that first positional parameter of the AHK script is referred to in AHK code as %1%. This first positional parameter contains handle of the active window which will be activated by AHK script before typing pwd command into that window. The actual AHK script contains first line with the comment (starting from ;), second line to activate (by mouse click) target window (represented as decimal integer handle number passed via %1%) and third line that actually types pwd to active window.

In general, VIEWER launcher should be explicitely configured by user to define what to do with attached .ahk file on execution.

Fig.5 Configuring VIEWER launcher definitions to work with AHK scripts

VIEWER launcher definitions dialog can be used to set what VIEWER launcher will do with AHK script file on launcher execution. In Example above highlighted VIEWER definition row will open VIEWER file with extension .ahk in the Notepad. If VIEWER launcher is executed with Ctrl key pressed, only definitions with Viewer2=Y are searched. Therefore, the upper definition row will be used for .ahk file when VIEWER launcher is executed with Ctrl key pressed. And upper VIEWER definition row will pass .ahk file to AHK interpreter and append <PROXYHANDLEOFACTIVEWINDOW> as first positional parameter of the AHK script. Middle row definition (to open .ahk file in the JEdit text editor) is not used as list of definition rows is searched from the top to the bottom - till first row with url_match_regex and Viewer2 matching values is found. url_match_regex should match url configured in the executed VIEWER launcher (in our case .ahk at the end of the file path). Viewer2=Y if VIEWER launcher is executed with Ctrl key pressed, otherwise Viewer2=N.

2.2 E-SCRIPT Launcher

Instead of creating AHK script file on disk, then explicitely calling AHK interpreter and passing that AHK script file and positional parameters to AHK interpreter, E-SCRIPT launcher allows to store AHK script code directly in the E-SCRIPT launcher configuration text field. To create AHK script, user inserts AHK code into Command text field of the E-SCRIPT launcher. On execution (double-clicking) E-SCRIPT launcher stores its code in the temporary .ahk file and then passes this file to AHK interpreter. When interpreter finishes its execution, proxy32 deletes temporary .ahk file.

Fig.6 E-SCRIPT launcher on the proxy32 configuration tree

Fig.7 The same E-SCRIPT launcher shown in the Launcher Editor Dialog

In example above Proxy32 passes to the AHK script list of handles of all non-minimized windows in current proxy32 workspace. Handles are decimal integers and they are separated by spaces. This list is inserted directly into the stored AHK code in place of <PROXYHANDLESOFNONMINIMIZEDWINDOWS> placeholder. Proxy32 parameters are substituted directly into the AHK code that is stored in E-SCRIPT launcher.

Above AHK script loops through the received space-separted list of window handles and for each window in the list it activates window by mouse click and then sends keystrokes pwd to activated window.

2.3 Window handles passed by Proxy32 as parameters

First three parameters on the picture below (starting from highlighted) are Proxy32 window handles.

<PROXYHANDLEOFACTIVESTICKERWINDOW> - replaced by decimal integer equal to window handle number of active proxy32 window if such window is created by 'external' process (window that is not part of proxy32.exe process - in other words, not "proxy32 own terminal window" or 'proxy32 own ScriptEditor window"). Active 'external' window is labeled in Proxy32 by red sticker with word "ACTIVE" on it.
<PROXYHANDLEOFACTIVEWINDOW> - replaced by decimal integer equal to window handle number of active proxy32 window. Active 'external' window is labeled in Proxy32 by red sticker with word "ACTIVE" on it. Active 'internal' window ("proxy32 own terminal window" or 'proxy32 own ScriptEditor window") is highlighted by thick red window frame.
<PROXYHANDLESOFNONMINIMIZEDWINDOWS> - replaced by list of handles of all non-minimized windows in current Proxy32 workspace. Handles are decimal integers and they are separated by spaces.

Fig.8 5 AHK-integration parameters (starting from highlighted) that can be inserted via "Insert New Proxy Parameter/Password" dialog that can be invoked via button from the launcher editor

2.4 User-pointed coordinates passed by Proxy32 as parameters

Sometimes there is a need to automate mouse click at some particular point inside of the "active" proxy32 window. That is especially important when "active" proxy32 window is remote desktop or console of virtual machine: * mouse click should trigger focus switch to particular window inside of virtual machine window. * target point will indicate origin (upper left corner) of some configuration window shown inside of virtual machine screen. Origin will serve to tell to AHK script where to click inside of active window to move focus between different text fields in the configuration window that is by itself located inside of the window of virtual machine.

For such use cases the 'target point' should be easily specified by proxy32 user.
There is an action called SET_COMMAND_LAUNCHER_MOUSEMOVECLICK_MOUSEPOSITION. This action is not shown as menu item or button inside of Proxy32 GUI. But it can be assigned to the hotkey of user's choice via "proxy32 workspace hotkey configuration dialog" as shown in Fig.9. In the example below on Fig.9 this action is assigned to F1 hotkey.

Fig.9 Configuring hotkey (F1) to store user mouse position inside of active window rectangle

To save mouse coordinates user have to position mouse over some point inside of the rectangle of the active 'external' window. Once the mouse pointer is over the right point, user will press designated hotkey to save x and y coordinates relatively to upper corner of active window. Saved coordinates will stay in Proxy32 memory until replaced by another pair x and y or till Proxy32 exit.

Stored x and y coordinates can be used by AHK script or by execution of COMMAND launcher when COMMAND execution is performed to 'external' window.

COMMAND launcher accesses stored x and y coordinates directly to perform mouse move or mouse click to active window before text of the command is sent to the active window. For thsi to work one of the MOUSEMOVECLICK modes should be enabled in proxy32. For deatils, pls, refer to the COMMAND launcher description.

AHK script can access stored x and y coordinates as proxy32 parameters <PROXYMOUSEXWITHINACTIVESTICKERWINDOW> and <PROXYMOUSEYWITHINACTIVESTICKERWINDOW>. Those two parameters can be insterted into AHK code stored in the E-SCRIPT launcher or those two parameters can be passed as positional to AHK script started via LAUNCH/VIEWER launcher as described above. Those two paremeters are shown on Fig.10 below (4th and 5th after highlighted).

Fig.10 5 AHK-integration parameters (starting from highlighted) that can be inserted via "Insert New Proxy Parameter/Password" dialog that can be invoked via button from the launcher editor

3. Examples and use cases

First example shows how to connect all non-minimized CYGWIN bash terminal windows in the current workspace to the set of different SSH-servers (cluster of virtual machines) by taking list of hostnames/IPs of the SSH servers from the text file. Text file should contain list of hostnames/IPs of the SSH servers - one hostname/IP per line. Path to file with list of SSH servers is passed into AHK code as <PROXYPARM=path to file that has hostnames one per line>. List of CYGWIN bash terminal window handles is passed to AHK code as <PROXYHANDLESOFNONMINIMIZEDWINDOWS>. Username and password for each server is the same for all servers and passed to AHK code as <PROXYPARM=SSH server user name> and <PROXYPASSWORD=SSH server user password>. AHK script also sets window title to the hostname of the server to which it is connected.

Fig.11 AHK script example to connect all non-minimized CYGWIN bash terminal windows in the current workspace to the set of different SSH-servers by taking list of hostnames/IPs of the SSH servers from the text file

My_handles = <PROXYHANDLESOFNONMINIMIZEDWINDOWS>
Loop,parse,My_handles,%A_Space%
{
    ;MsgBox, handle number %A_Index% is %A_LoopField%.
    ;read next line from hosts file
    FileReadLine, line, <PROXYPARM=path to file that has hostnames one per line>, %A_Index%
    if ErrorLevel
        break
    ;MsgBox, line number %A_Index% is %line%.

    Sleep, 1000  ;1 second
    ControlClick,,ahk_id %A_LoopField% ;click on window to make it active.
    Send,ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null <PROXYPARM=SSH server user name>@%line%{Enter} ;send keypresses to active window
    Sleep, 1000  ;1 second
    SendRaw,<PROXYPASSWORD=SSH server user password>
    Send,{Enter}
    WinSetTitle,ahk_id %A_LoopField%,,%line%
}

Second example shows AHK script to configure PuTTY via its "PuTTY Configuration Dialog" located inside of the remote desktop window of XP machine. Owner of remote desktop does not allow desktop user to save PuTTY configuration settings into registry, so we have to use AHK script to configure PuTTY terminal for every single SSH connection we make from remote desktop. User have to start PuTTY terminal inside of remote desktop window. PuTTY will show its "PuTTY Configuration Dialog" box. Then user will have use proxy32 functionality to store coordinates of top left corner of WINXP "PuTTY Configuration Dialog" (leftmost grey point immediately under "PuTTY Configuration Dialog" titlebar). Coordinates are saved relatively left top corner of remote desktop window (which is Proxy32 'active' window).

To save mouse coordinates Proxy32 user have to position mouse over target point (leftmost grey point immediately under "PuTTY Configuration Dialog" titlebar) inside of the rectangle of the active 'external' window (which is remote desktop window). Once the mouse pointer is over the correct point, user will press designated hotkey to make Proxy32 save x and y coordinates of mouse pointer relatively to top left corner of active window. For this to work designated hotkey is previously assigned SET_COMMAND_LAUNCHER_MOUSEMOVECLICK_MOUSEPOSITION action in Proxy32 workspace hotkeys configuration dialog. Saved coordinates will stay in Proxy32 memory until replaced by another pair x and y or till Proxy32 exit.

Those coordinates are passed to AHK script that is residing inside of E-SCRIPT launcher shown below (as proxy32 parameters <PROXYMOUSEXWITHINACTIVESTICKERWINDOW> and <PROXYMOUSEYWITHINACTIVESTICKERWINDOW>). AHK script navigates WINXP "PuTTY Configuration Dialog" with sequences of mouse clicks and keystrokes. Mouse clicks positions in AHK script are pre-configured (hard-coded for WINXP and certain version of PuTTY) relatively to coordinates of top left corner of WINXP "PuTTY Configuration Dialog". Handle of active remote desktop window is passed to AHK script as <PROXYHANDLEOFACTIVESTICKERWINDOW>. Hostname of the ssh server to which PuTTY terminal has to connect is passed to AHK script as <PROXYPARM=hostname>.

Fig.12 AHK script example to configure PuTTY via its "PuTTY Configuration Dialog" located inside of the remote desktop window of XP machine

;WINXP PuTTY Configuration Dialog (set point at the left top corner of gray area)


SetKeyDelay, 100
SetControlDelay, 200
x:=<PROXYMOUSEXWITHINACTIVESTICKERWINDOW>
y:=<PROXYMOUSEYWITHINACTIVESTICKERWINDOW>

;set xterm mouse mode
pos1:=% "x" . (x+73) . " y" . (y+192)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+190) . " y" . (y+116)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>

;set log file
pos1:=% "x" . (x+71) . " y" . (y+49)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+190) . " y" . (y+148)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}E:\PuttyLogs\my_terminal_&Y_&M_&D_&T_&H_<PROXYPARM=hostname>.log

pos1:=% "x" . (x+190) . " y" . (y+92)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+190) . " y" . (y+230)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>

;set scrollback
pos1:=% "x" . (x+52) . " y" . (y+129)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+320) . " y" . (y+220)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}1410065407

;set colors
pos1:=% "x" . (x+70) . " y" . (y+209)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+210) . " y" . (y+238)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+410) . " y" . (y+242)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}0
pos1:=% "x" . (x+410) . " y" . (y+266)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}0
pos1:=% "x" . (x+410) . " y" . (y+291)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}0

pos1:=% "x" . (x+210) . " y" . (y+251)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+410) . " y" . (y+242)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}85
pos1:=% "x" . (x+410) . " y" . (y+266)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}85
pos1:=% "x" . (x+410) . " y" . (y+291)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}85

pos1:=% "x" . (x+210) . " y" . (y+264)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+410) . " y" . (y+242)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}255
pos1:=% "x" . (x+410) . " y" . (y+266)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}255
pos1:=% "x" . (x+410) . " y" . (y+291)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}255

pos1:=% "x" . (x+210) . " y" . (y+277)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+410) . " y" . (y+242)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}255
pos1:=% "x" . (x+410) . " y" . (y+266)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}0
pos1:=% "x" . (x+410) . " y" . (y+291)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}128


;set clean user name
pos1:=% "x" . (x+64) . " y" . (y+240)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+322) . " y" . (y+76)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}


;set title info
pos1:=% "x" . (x+75) . " y" . (y+160)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+185) . " y" . (y+90)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}<PROXYPARM=hostname>




;set host info and connect
pos1:=% "x" . (x+51) . " y" . (y+32)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
pos1:=% "x" . (x+189) . " y" . (y+91)
ControlClick,%pos1%,ahk_id <PROXYHANDLEOFACTIVESTICKERWINDOW>
Send ^{A}{Del}{Shift up}<PROXYPARM=hostname>{Enter}

AHK language help file is installed in the same directory where AHK interpreter is installed.

Index