AutoHotkey_L New Features

This document describes features added in the AutoHotkey_L branch of AutoHotkey development, now simply known as "AutoHotkey 1.1".

Caution: This document has been neglected in recent years and may be missing some of the more recent changes.

Control Flow

Feature Description
Break LoopLabelBreak out of a loop or any number of nested loops.
Continue LoopLabelContinue a loop, even from within any number of nested loops.
For x,y in zLoop through the contents of an object.
Loop UntilLoop until a condition is true. Applicable to any type of loop.
Try...Catch...FinallyProvides structured exception handling.
ThrowThrows an exception.

Commands

Feature Description
FileEncodingSets the default encoding for FileRead, FileReadLine, Loop Read, FileAppend, and FileOpen().
See also: Text Encodings
GuiSee GUI Enhancements below.
IniRead/Write/DeleteRead, write or delete entire sections, or retrieve a list of all section names.
Menu, IconSets or removes a menu item's icon.
RunImprovements were made to the way parameters are parsed.
SendInput {U+nnnn}Sends a Unicode character. Unicode characters may be used directly in Unicode builds.
SendLevelControls which artificial keyboard and mouse events are ignored by hotkeys and hotstrings.
SetFormat, IntegerFast, h|HSet lower-case or upper-case hexadecimal format.
SetRegView, RegViewAllows registry commands in a 32-bit script to access the 64-bit registry view and vice versa.
Transform, HTMLPerform code page or HTML transformations.
WinGet, ..., ProcessPathRetrieves the full path and name of the process that owns a given window.

Directives

Feature Description
#If expressionSimilar to #IfWinActive, but for arbitrary expressions.
#IfTimeoutSets the maximum time that may be spent evaluating a single #If expression.
#MenuMaskKeyChanges which key is used to mask Win or Alt keyup events.
#Include <Lib>Includes a script file from a function library folder.
#InputLevelControls which artificial keyboard and mouse events are ignored by hotkeys and hotstrings.
#WarnEnables or disables warnings for selected conditions that may be indicative of developer errors.

Functions

Feature Description
ComObjActiveRetrieves a registered COM object.
ComObjArrayCreates a SAFEARRAY for use with COM.
ComObjConnectConnects a COM object's event sources to functions with a given prefix.
ComObjCreateCreates a COM object.
ComObjectWraps a value and type to pass as a parameter or return value.
ComObjEnwrap/UnwrapWraps/unwraps a COM object.
ComObjErrorEnables or disables notification of COM errors.
ComObjFlagsRetrieves or changes flags which control a COM wrapper object's behaviour.
ComObjGetReturns a reference to an object provided by a COM component.
ComObjMissingCreates a "missing parameter" object to pass to a COM method.
ComObjParameterWraps a value and type to pass as a parameter.
ComObjQueryQueries a COM object for an interface or service.
ComObjTypeRetrieves type information from a COM object.
ComObjValueRetrieves the value or pointer stored in a COM wrapper object.
ExceptionCreates an exception object for Throw (also provides limited access to the call stack).
FileOpenProvides object-oriented file I/O.
FuncRetrieves a reference to a function.
GetKeyName/VK/SCRetrieves the name/text, virtual key code or scan code of a key.
InStrSearches for a given occurrence of a string, from the left or the right.
IsByRefDetermines whether a ByRef parameter was supplied with a variable.
IsObjectDetermines whether a value is an object.
StrPut / StrGetCopies a string to or from a memory address, optionally converting it to or from a given code page.
TrimTrims certain characters from the beginning and/or end of a string.
RegEx (?CNum:Func)Calls a function during evaluation of a regex pattern.
Function LibrariesNew "local library" and #Include <LibName>.
Variadic FunctionsFunctions may accept a variable number of parameters via an array.
Static InitializersStatic variables can now be initialized using any expression.

Objects

Feature Description
GeneralBehaviour and usage of objects in general.
ObjectAssociative arrays which can be extended with other functionality.
EnumeratorAllows items in a collection to be enumerated.
FileProvides an interface to access a file. FileOpen() returns an object of this type.
FuncRepresents a user-defined or built-in function which can be called by the script.
ComObjectSee ComObj functions above.

Variables

Feature Description
A_Is64bitOSContains 1 (true) if the OS is 64-bit or 0 (false) if it is 32-bit.
A_IsUnicodeIn Unicode builds, this variable contains 1 (true). In ANSI builds it is not defined, so is effectively false.
A_FileEncodingContains the default encoding for various commands; see FileEncoding.
A_OSVersionSupports Windows 7 and Windows 8; see A_OSVersion.
A_PriorKeyThe name of the last key which was pressed prior to the most recent key-press or key-release ... (More)
A_PtrSizeContains the size of a pointer, in bytes. This is either 4 (32-bit) or 8 (64-bit).
A_RegViewThe current registry view as set by SetRegView.
A_ScriptHwndThe unique ID (HWND/handle) of the script's hidden main window.

Datatypes

Feature Description
PtrEquivalent to Int in 32-bit builds and Int64 in 64-bit builds. Supported by DllCall(), NumPut() and NumGet().
AStr, WStrSupported only by DllCall(); see Script Compatibility.

Unicode

Feature Description
CompatibilityHow to deal with Unicode in DllCall(), etc.
Script FilesUsing Unicode in script files.
SendInputUsing Unicode with SendInput.

Other

Feature Description
ahk_exeWindows can be identified by the name or path of the process (EXE file) which owns them.
DebuggingInteractive debugging features (line by line execution etc.).
Error HandlingTry/catch/throw and increased usefulness for A_LastError.
GUI EnhancementsVarious enhancements to the Gui command and related.
Icon SupportResource identifiers and improved support for various icon sizes.
Other ChangesChanges affecting script compatibility.
Version HistoryHistory of AutoHotkey_L revisions.

Error Handling

Many commands support using try/catch instead of ErrorLevel for error handling. For example:

try
{
    FileCopy, file1.txt, C:\folder
    FileDelete, C:\folder\old.txt
}
catch
    MsgBox An error occured!

Additionally, 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.

Function Libraries

In addition to the user library in %A_MyDocuments%\AutoHotkey\Lib and standard library in the AutoHotkey directory, functions may be auto-included from the "local library" which resides in %A_ScriptDir%\Lib. For more information, see Libraries of Functions.

#Include <LibName> explicitly includes a library file which may be located in any one of the function libraries.

GUI Enhancements

A number of enhancements have been made to the Gui command and related:

Static Variables

Static variables can now be initialized using any expression. For example:

Sleep 500
MsgBox % Time() "ms since the script started."
Time() {
    static Tick := A_TickCount
    return A_TickCount - Tick
}

Text Encodings

FileRead, FileReadLine, Loop Read and FileAppend support the majority of Windows-supported text encodings, not just the system default ANSI code page. FileEncoding can be used to set the default encoding, which can be overridden for FileRead and FileAppend as follows:

FileRead, OutputVar, *Pnnn Filename
FileAppend , Text, Filename, Encoding

While nnn must be a numeric code page identifier, Encoding follows the same format as FileEncoding.

See also: Script Compatibility

Variadic Functions and Function-Calls

Variadic functions can receive a variable number of parameters via an array, while variadic function-calls can be used to pass a variable number of parameters to a function.

Improvements to Icon Support

Unusual Sizes

Icon resources of any size supported by the operating system may be extracted from executable files. When multiple sized icon resources exist within an icon group, the most appropriate size is used. Prior to revision 17, an arbitrary icon resource was selected by the system, scaled to the system large icon size, then scaled back to the requested size.

Resource Identifiers

Negative icon numbers may be used to identify a group icon resource within an executable file. For example, the following sets the tray icon to the default icon used by ahk files:

Menu, Tray, Icon, %A_AhkPath%, -160