Although many scripts written for AutoHotkey 1.0 do not require changes to run on AutoHotkey 1.1, some may function incorrectly due to necessary differences between the two versions. As the most problematic differences only affect advanced functionality like DllCall(), most users do not need to be concerned.
AutoHotkey 1.1 is also known as "AutoHotkey_L", while AutoHotkey 1.0 was retrospectively labelled "AutoHotkey Basic". Some older versions of AutoHotkey_L used 1.0.* version numbers, so for clarity, this document refers to the two branches of AutoHotkey by name rather than version number.
Note: Some of the most common problems are caused by changes required to support Unicode text, and can be avoided by simply using the ANSI version of AutoHotkey_L.
High impact:
Medium impact:
x & y:: causes both x:: and x up:: to fire when x is releasedLow impact:
Certain syntax errors which were tolerated by AutoHotkey Basic are not tolerated by AutoHotkey_L. Most such errors can be easily corrected once they are identified. The following errors are detected immediately upon launching a script in AutoHotkey_L, and must be corrected for the script to run:
MsgBox< foo and If!foo are not tolerated.Hotkey, IfSomething, where Something is invalid, is not tolerated.Some other syntax errors are detected while the script is running. These cause an error message to be displayed prior to exiting the current thread:
Some other syntax errors are currently not detected, but cause problems with AutoHotkey_L:
( is more selective, so some invalid expressions like 12(34) no longer work.FileRead translates text between code pages in certain common cases and therefore might output corrupt binary data. To avoid this, add the *c option or use FileOpen() instead.
The characters [, ] and ? are reserved for use in expressions, so are no longer valid in variable names. Consequently, ? (used in ternary operations) no longer requires a space on either side. See also object syntax.
Errors may or may not be detected automatically:
Array%n% where n contains one of the above characters), an error message is displayed when the double-deref is evaluated, while the script is running.DPI scaling is enabled by default for script GUIs to ensure they scale according to the system DPI setting. If enabled and the system DPI setting is not 96 (100%), positions and sizes accepted by or returned from Gui commands are not compatible with other commands. To disable DPI scaling, use Gui -DPIScale.
Some Transform sub-commands are altered or unavailable in Unicode versions of AutoHotkey_L:
When AutoHotkey_L is launched without specifying a script, an .ahk file is loaded by default instead of an .ini file. The name of this file depends on the filename of the current executable. For more details, see Passing Command Line Parameters to a Script.
When an uppercase H is used, hexadecimal digits A-F will also be in uppercase. AutoHotkey Basic always uses lowercase digits. See SetFormat.
The following commands now set A_LastError to assist with debugging: FileAppend, FileRead, FileReadLine, FileDelete, FileCopy, FileMove, FileGetAttrib/Time/Size/Version, FileSetAttrib/Time, FileCreateDir, RegRead, RegWrite, RegDelete. Using any of these commands causes the previous value of A_LastError to be overwritten.
MsgBox's smart comma handling has been changed to improve flexibility and consistency with all other commands. In most cases, MsgBox will just work as intended. In some rare cases, scripts relying on the old quirky behaviour may observe a change in behaviour. For instance:
; This is now interpreted as an expression (Options) followed by text (Title) ; instead of as a single expression (Text) with multiple sub-expressions: MsgBox % x, y ; Parentheses can be added to force the old interpretation: MsgBox % (x, y) ; This now shows an empty dialog instead of the text "0, Title": MsgBox 0, Title ; These behave as expected in both AutoHotkey_L and AutoHotkey Basic: MsgBox 0, Title, % "" ; Shows an empty dialog MsgBox 0`, Title ; Shows the text "0, Title" ; This now shows an empty dialog instead of the text ", Title": MsgBox,, Title
Applying the +Owner option to a Gui also removes the WS_CHILD style and sets the WS_POPUP style. This may break scripts which used +Owner to set the parent window of a Gui after setting the styles.
SoundSet, SoundGet, SoundSetWaveVolume and SoundGetWaveVolume have improved support for Windows Vista and later. Typical changes in behaviour include:
As of [v1.1.14], the tilde prefix affects how a key works when used as a modifier key in a custom combination.
Except when the tilde prefix is used, if both a key-down and a key-up hotkey are defined for a custom modifier key, they will both fire when the key is released. For example, x & y:: causes both x:: and x up:: to fire when x is released, where previously x:: never fired.
If var is type ignores the system locale unless StringCaseSense, Locale has been used.
GroupActivate sets ErrorLevel to 1 if no window was found to activate or 0 otherwise. Previously, ErrorLevel was left unchanged.
GroupAdd's Label parameter applies to the window group as a whole instead of to one particular window specification within the group. A discussion of this change can be found on the forums. However, using this parameter is not recommended; check ErrorLevel after calling GroupActivate instead.
AutoHotkey_L includes some enhancements to the way the Run and RunWait commands interpret the Target parameter. This allows some things that didn't work previously, but in some very rare cases, may also affect scripts which were already working in AutoHotkey Basic. The new behaviour is as follows:
Loop Read and FileReadLine no longer interpret the character Ctrl+Z (0x1A) as an end-of-file marker. Any Ctrl+Z, even one appearing at the very end of the file, is loaded as-is. FileRead already ignored this character, so is not affected by this issue.
If Compatibility mode is set to Windows 95, 98/ME or NT4 in the properties of the EXE file used to run the script, the script may not behave correctly. This is because compatibility mode causes a specific version of Windows to be reported to the application, but AutoHotkey_L omits support for these versions. For example, setting compatibility mode to Windows 95 or 98/ME will cause MsgBox %A_OSVersion% to report WIN_NT4.
A_IsCompiled is defined as an empty string if the script has not been compiled. Previously it was left undefined, which meant that assignments such as A_IsCompiled := 1 were valid if the script hadn't been compiled. Now it is treated as a read-only built-in variable in all cases.
Escaped whitespace characters such as `t and ` are no longer trimmed from the beginning and end of each arg. For example, StringReplace s, s, `t is now valid and will remove all tab characters from s.
Note: This section builds on topics covered in other parts of the documentation: Strings, String Encoding.
Within a string (text value), the numeric character code and size (in bytes) of each character depends on the native encoding of the script or AutoHotkey executable; i.e. Unicode or ANSI. These details are typically important for scripts which do any of the following:
Scripts designed with one particular format in mind will often encounter problems when run on the wrong version of AutoHotkey. For instance, some scripts written for AutoHotkey Basic will function correctly on the ANSI version of AutoHotkey_L but fail on Unicode versions. If you aren't sure which version you are using, run the following script:
MsgBox % A_IsUnicode ? "Unicode" : "ANSI"
ANSI: Each character is one byte (8 bits). Character codes above 127 depend on your system's language settings.
Unicode: Each character is two bytes (16 bits). Character codes are as defined by the UTF-16 format.
Semantic note: Technically, some Unicode characters are represented by two 16-bit code units, collectively known as a "surrogate pair." Similarly, some ANSI code pages (commonly known as Double Byte Character Sets) contain some double-byte characters. However, for practical reasons these are almost always treated as two individual units (referred to as "characters" for simplicity).
VarSetCapacity sets the capacity of a var in bytes. To set a variable's capacity based on the number of characters, the size of a character must be taken into account. For example:
VarSetCapacity(ansi_var, capacity_in_chars) VarSetCapacity(unicode_var, capacity_in_chars * 2) VarSetCapacity(native_var, capacity_in_chars * (A_IsUnicode ? 2 : 1)) VarSetCapacity(native_var, t_size(capacity_in_chars)) ; see below
There are two main uses for VarSetCapacity:
VarSetCapacity(var, 1000) allows for 1000 bytes, which is only 500 characters on Unicode versions of AutoHotkey_L. This could affect performance, but the script should still function correctly.When the "Str" type is used, it means a string in the native format of the current build. Since some functions may require or return strings in a particular format, the following string types are available:
| Char Size | C / Win32 Types | Encoding | |
|---|---|---|---|
| WStr | 16-bit | wchar_t*, WCHAR*, LPWSTR, LPCWSTR | UTF-16 |
| AStr | 8-bit | char*, CHAR*, LPSTR, LPCSTR | ANSI (the system default ANSI code page) |
| Str | -- | TCHAR*, LPTSTR, LPCTSTR | Equivalent to WStr in Unicode builds and AStr in ANSI builds. |
If "Str" or the equivalent type for the current build is used as a parameter, the address of the string or var is passed to the function, otherwise a temporary copy of the string is created in the desired format and passed instead. As a general rule, "AStr" and "WStr" should not be used if the function writes a value into that parameter.
Note: "AStr" and "WStr" are equally valid for parameters and the function's return value.
In general, if a script calls a function via DllCall() which accepts a string as a parameter, one of the following approaches must be taken:
DllCall("DeleteFile", "Ptr", &filename)
DllCall("DeleteFile", "Str", filename)
In this example, &filename passes the address of the string exactly as-is, so the function must expect a string in the same format as the "Str" type. Note that "UInt" must be used in place of "Ptr" in AutoHotkey Basic, but the resulting code may not be 64-bit compatible.
Note: If the function cannot be found exactly as specified, AutoHotkey_L appends the "A" or "W" suffix regardless of which DLL is specified. However, AutoHotkey Basic appends the "A" suffix only for functions in User32.dll, Kernel32.dll, ComCtl32.dll, or Gdi32.dll.
DllCall("DeleteFileA", "AStr", filename)
DllCall("DeleteFileW", "WStr", filename)When NumPut() or NumGet() are used with strings, the offset and type must be correct for the given type of string. The following may be used as a guide:
; 8-bit/ANSI strings: size_of_char=1 type_of_char="Char" ; 16-bit/UTF-16 strings: size_of_char=2 type_of_char="UShort" nth_char := NumGet(var, (n-1)*size_of_char, type_of_char) NumPut(nth_char, var, (n-1)*size_of_char, type_of_char)
If var contains a string in the native format, the appropriate values may be determined based on the value of A_IsUnicode:
nth_char := NumGet(var, t_size(n-1), t_char())
NumPut(nth_char, var, t_size(n-1), t_char())
; Define functions for convenience and clarity:
t_char() {
return A_IsUnicode ? "UShort" : "Char"
}
t_size(char_count=1) {
return A_IsUnicode ? char_count*2 : char_count
}
Pointers are 4 bytes in 32-bit builds (including AutoHotkey Basic) and 8 bytes in 64-bit builds. Scripts using structures or DllCalls may need to account for this to run correctly on both platforms. Specific areas which are affected include:
For size and offset calculations, use A_PtrSize. For DllCall(), NumPut() and NumGet(), use the Ptr type where appropriate.
Remember that the offset of a field is usually the total size of all fields preceding it. Also note that handles (including types like HWND and HBITMAP) are essentially pointer-types.
/*
typedef struct _PROCESS_INFORMATION {
HANDLE hProcess; // Ptr
HANDLE hThread;
DWORD dwProcessId; // UInt (4 bytes)
DWORD dwThreadId;
} PROCESS_INFORMATION, *LPPROCESS_INFORMATION;
*/
VarSetCapacity(pi, A_PtrSize*2 + 8) ; Ptr + Ptr + UInt + UInt
DllCall("CreateProcess", <omitted for brevity>, "Ptr", &pi, <omitted>)
hProcess := NumGet(pi, 0) ; Defaults to "Ptr".
hThread := NumGet(pi, A_PtrSize) ;
dwProcessId := NumGet(pi, A_PtrSize*2, "UInt")
dwProcessId := NumGet(pi, A_PtrSize*2 + 4, "UInt")