How to View the Inner Workings and Hidden Mechanisms of Running AutoHotkey Scripts

AutoHotkey includes a tool called the Main Window which aids with the debugging process. It gives you a peek into various aspects of a running .ahk script:

1. Most recently executed lines of code (ListLines command).
2. Current variables and values (ListVars command).
3. Active Hotkeys (ListHotkeys command).
4. Keyboard activity (KeyHistory command).

Open the Main Window by right-clicking on Windows System Tray icon of an active .ahk script and selecting Open from the top of the menu. The window pops open at the “Lines most recently executed” view. You can select the other three views plus “Refresh” from the View menu.

You’ve probably encountered the Main Window while writing scripts—if only through curiosity. When you look up Main Window online, you won’t find a direct reference—but, you will find pages for the four related commands (ListLines, ListVars, ListHotkeys, KeyHistory) each of which opens a specific Main Window view for a running script.

The Open option only appears in the AutoHotkey icon right-click menu for .ahk files—not compiled .exe files. However, the individual commands work in a script for both .ahk and .exe files. The key difference between using the Main Window commands in .ahk files and .exe files affects the View menu where AutoHotkey disables all options (except Refresh) for .exe files.

If you have trouble figuring out the source of problems in a script, the Main Window might just give you the help you need. The tool offers four types of insights.

ListLines Main Window Command

Whether you select “Lines most recently executed” from the View menu or insert the ListLines command into a script, a window pops open displaying the most recently executed lines of code. This may give you the best look at the activity occurring inside running a script.

This peek at the code allows you to determine if the proper lines run at the right time. For example in the InstantHotkeyLoop.ahk script, the first time (IH_Count = 1) you set up a new Instant Hotkey, it makes adjustments to the System Tray menu (as shown by ListLines):

098: if IH_Count = 1
100: Menu,Tray,Add,Instant Hotkeys,:HotkeyMenu
101: Menu,Tray,Insert,Instant Hotkeys,Add Text,:InsertText
102: Menu,Tray,Icon,Add Text,InstantHotkey.ico,1
103: }
105: Gui,Show,,Instant Hotkey %IH_Count% (0.23)

After this first instance (if IH_Count = 1), the script skips the Menu commands:

098: if IH_Count = 1
105: Gui,Show,,Instant Hotkey %IH_Count% (0.20)

This glimpse at the running code acts as a quick check on whether or not the If conditional worked in the designed manner.

At times while debugging a script, I would place a MsgBox command inside a conditional, loop, or function to check its operation. Although I find occasions where I still need to add my own checks to a script, often the ListLines view of the Main Window saves the extra work.

ListVars Main Window Command

Whether you select “Variables and their contents” from the View menu or insert the ListVars command into a script, a window pops open displaying the script variables.

While in most script debugging, the ListVars window might give you all that you need, you’ll find a couple of situations where AutoHotkey requires adding a trap into your code.

First, Local function variables only show up in the Main Window if you catch script processing while inside the function. That means you need to add either the ListVars command or a script pausing command (such as MsgBox) inside the function to see the Local variables in the Main Window at processing time.

Second, associative arrays only display the last value called, while pseudo-arrays, such as those shown in the image above (e.g. InstantHotkey1 and InstantHotkey2), display all the variable values. For example, since I could not view all the associative array values through ListVars in the Main Window, I added a Hotkey which displays all array values (as shown at right) to the InstantHotkeyArray.ahk script.

In spite of the quick variable info offered by the Main Window, you’ll find times when you need to add your own debugging traps while developing new AutoHotkey scripts.

ListHotkeys  Main Window Command

Whether you select “Hotkeys and their methods” from the View menu or insert the ListHotkeys command into a script, a view pops open displaying the script Hotkeys.

I rarely examine Hotkeys, but when I explored the “Secret Hotstring Trick” a few weeks ago, I needed to know whether or not AutoHotkey had installed the Keyboard Hook for target Hotkeys. Fortunately, while the Main Window does not supply that type of information for Hotstrings, it does for Hotkeys:

Hotkeys:
k-hook           #z
k-hook           #z
reg              !,
m-hook           XButton1
reg              ^6

Hotstrings can’t launch Hotkeys with the keyboard hook installed (k-hook), whereas they can launch non-hook Hotkeys (reg).

KeyHistory Main Window Command

Whether you select “Key history and script info” from the menu or insert the KeyHistory command into a script, a view pops open displaying the script keyboard action.

I found this Main Window View particularly valuable when looking for Virtual Key and Scan Code values for the MousePrecise.ahk script. If you wonder what AutoHotkey actually does with each press of a key or click of a mouse, then start with KeyHistory.

You’ll note the other standard System Tray icon menu items (Reload Script, Edit Script, Window Spy, Pause Script, Suspend Hotkeys, and Exit (Terminate Script)) in the File menu of the Main Window.

You’ll find it easy to forget that the Main Window even exists, but if you encounter trouble with a particular script, right-click on the System Tray icon and select Open for a little insight.