Various built-in functions have a WinTitle parameter, used to identify which window (or windows) to operate on. This parameter can be the title or partial title of the window, and/or any other criteria described on this page.
Specify any string for WinTitle to identify a window by its title. The title of a window is often visible as text in a title bar at the top of the window. If invisible or only partially visible, the full window title can be revealed via WinGetTitle or Window Spy.
The following example activates the calculator:
WinActivate "Calculator"
SetTitleMatchMode controls how a partial or complete title is compared against the title of each window. Depending on the setting, WinTitle can be an exact title, or it can contain a prefix, a substring which occurs anywhere in the title, or a RegEx pattern. This setting also controls whether the ahk_class and ahk_exe criteria are interpreted as RegEx patterns.
Window titles are case-sensitive, except when using the i) modifier in a RegEx pattern.
Hidden windows are only detected if DetectHiddenWindows is turned on, except with WinShow, which always detects hidden windows.
If multiple windows match WinTitle and any other criteria, the topmost matching window is used. If the active window matches the criteria, it usually takes precedence since it is usually above all other windows. However, if an always-on-top window also matches (and the active window is not always-on-top), it may be used instead.
In [v2.0.6+], it is no longer the case that only the first 1023 characters of the specified window title, ahk_class criterion value, and ahk_exe criterion value are considered for matching purposes. Exceeding the length no longer leads to unexpected results, which rarely occurs, but may be encountered more often if a very long RegEx pattern is used.
Use the letter A for WinTitle and omit the other three window parameters (WinText, ExcludeTitle and ExcludeText), to operate on the active window.
The following example retrieves and reports the unique ID (HWND) of the active window:
MsgBox WinExist("A")
The following example creates a hotkey which can be pressed to maximize the active window:
#Up::WinMaximize "A" ; Win+Up
Specify one or more of the following ahk_ criteria (optionally in addition to a window's title), each separated from the next with exactly one space or tab (any other spaces or tabs are treated as a literal part of the previous criterion). An ahk_ criterion always consists of an ahk_ keyword and its criterion value, separated by zero or more spaces or tabs. For example, ahk_class Notepad identifies a Notepad window.
The ahk_ keyword and its criterion value do not need to be separated by spaces or tabs. This is primarily useful when specifying ahk_ criteria in combination with variables. For example, you could specify "ahk_pid" PID instead of "ahk_pid " PID. In all other cases, however, it is recommended to use at least one space or tab as a separation to improve readability.
Use ahk_class ClassName in WinTitle to identify a window by its window class.
A window class is a set of attributes that the system uses as a template to create a window. In other words, the class name of the window identifies what type of window it is. A window class can be revealed via Window Spy or retrieved by WinGetClass. If the RegEx title matching mode is active, ClassName accepts a regular expression.
Window classes are case-sensitive, except when using the i) modifier in a RegEx pattern.
The following example activates a console window (e.g. cmd.exe):
WinActivate "ahk_class ConsoleWindowClass"
The following example does the same as above, but uses a regular expression (note that the RegEx title matching mode must be turned on beforehand to make it work):
WinActivate "ahk_class ^ConsoleWindowClass$"
Each window or control has a unique ID, also known as a HWND (short for handle to window). This ID can be used to identify the window or control even if its title or text changes.
Use ahk_id HWND or a pure HWND (as an Integer or an Object with a HWND property) in WinTitle to identify a window or control by its unique ID.
When using ahk_id HWND, DetectHiddenWindows affects whether hidden top-level windows are detected, but hidden controls are always detected. When using pure HWNDs, hidden windows are always detected regardless of DetectHiddenWindows. WinWait and WinWaitClose are an exception, where both ahk_id HWND and pure HWNDs are affected by DetectHiddenWindows.
ahk_id HWND can also be combined with other criteria that the given window must match. For example, WinExist("ahk_id " ahwnd " ahk_class " aclass) returns ahwnd if the window is "detected" (according to DetectHiddenWindows) and its window class matches the string contained by aclass.
The ID of a window is typically retrieved via WinExist or WinGetID. The ID of a control is typically retrieved via ControlGetHwnd, MouseGetPos, or DllCall. Gui and GuiControl objects have a Hwnd property and therefore can be used directly in WinTitle.
The following examples operate on a window by a unique ID stored in VarContainingID:
; Pass an Integer.
WinActivate Integer(VarContainingID)
WinShow A_ScriptHwnd
WinWaitNotActive WinExist("A")
; Pass an Object with a HWND property.
WinActivate {Hwnd: VarContainingID}
WinWaitClose myGuiObject
; Use the ahk_id prefix.
WinActivate "ahk_id " VarContainingID
If the object has no HWND property or the property's value is not an integer, a PropertyError or TypeError is thrown.
Use ahk_pid PID in WinTitle to identify a window belonging to a specific process. The process identifier (PID) is typically retrieved by WinGetPID, Run or Process functions. The ID of a window's process can be revealed via Window Spy.
The following example activates a window by a process ID stored in VarContainingPID:
WinActivate "ahk_pid " VarContainingPID
Use ahk_exe ProcessNameOrPath in WinTitle to identify a window belonging to any process with the given name or path.
While the ahk_pid criterion is limited to one specific process, the ahk_exe criterion considers all processes with name or full path matching a given string. If the RegEx title matching mode is active, ProcessNameOrPath accepts a regular expression which must match the full path of the process. Otherwise, it accepts a case-insensitive name or full path; for example, ahk_exe notepad.exe covers ahk_exe C:\Windows\Notepad.exe, ahk_exe C:\Windows\System32\Notepad.exe and other variations. The name of a window's process can be revealed via Window Spy.
The following example activates a Notepad window by its process name:
WinActivate "ahk_exe notepad.exe"
The following example does the same as above, but uses a regular expression (note that the RegEx title matching mode must be turned on beforehand to make it work):
WinActivate "ahk_exe i)\\notepad\.exe$" ; Match the name part of the full path.
Use ahk_group GroupName in WinTitle to identify a window or windows matching the rules contained by a previously defined window group.
WinMinimize, WinMaximize, WinRestore, WinHide, WinShow, WinClose, and WinKill will operate upon all the group's windows. By contrast, the other windowing functions such as WinActivate and WinExist will operate only upon the topmost window of the group.
The following example activates any window matching the criteria defined by a window group:
; Define the group: Windows Explorer windows GroupAdd "Explorer", "ahk_class ExploreWClass" ; Unused on Vista and later GroupAdd "Explorer", "ahk_class CabinetWClass" ; Activate any window matching the above criteria WinActivate "ahk_group Explorer"
By contrast with the ahk_group criterion (which broadens the search), the search may be narrowed by specifying more than one criterion within the WinTitle parameter. In the following example, the script waits for a window whose title contains My File.txt and whose class is Notepad:
WinWait "My File.txt ahk_class Notepad" WinActivate ; Activate the window it found.
When using this method, the text of the title (if any is desired) should be listed first, followed by one or more additional criteria. Criteria beyond the first should be separated from the previous with exactly one space or tab (any other spaces or tabs are treated as a literal part of the previous criterion).
The ahk_id criterion can be combined with other criteria to test a window's title, class or other attributes:
MouseGetPos ,, &id
if WinExist("ahk_class Notepad ahk_id " id)
MsgBox "The mouse is over Notepad."
This is the window most recently found by WinExist, WinActive, WinWait[Not]Active, WinWait, or WinWaitClose. It can make scripts easier to create and maintain since WinTitle and WinText of the target window do not need to be repeated for every windowing function. In addition, scripts perform better because they don't need to search for the target window again after it has been found the first time.
The last found window can be used by all of the windowing functions except WinWait, WinActivateBottom, GroupAdd, WinGetCount, and WinGetList. To use it, simply omit all four window parameters (WinTitle, WinText, ExcludeTitle, and ExcludeText).
Each thread retains its own value of the last found window, meaning that if the current thread is interrupted by another, when the original thread is resumed it will still have its original value of the last found window, not that of the interrupting thread.
If the last found window is a hidden Gui window, it can be used even when DetectHiddenWindows is turned off. This is often used in conjunction with the GUI's +LastFound option.
The following example opens Notepad, waits until it exists and activates it:
Run "Notepad" WinWait "Untitled - Notepad" WinActivate ; Use the window found by WinWait.
The following example activates and maximizes the Notepad window found by WinExist:
if WinExist("Untitled - Notepad")
{
WinActivate ; Use the window found by WinExist.
WinMaximize ; Same as above.
Send "Some text.{Enter}"
}
The following example activates the calculator found by WinExist and moves it to a new position:
if not WinExist("Calculator")
{
; ...
}
else
{
WinActivate ; Use the window found by WinExist.
WinMove 40, 40 ; Same as above.
}