The WinTitle Parameter & the Last Found Window

Many 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.

Quick Reference:
TitleMatching Behaviour
ObjectObject with HWND
AThe Active Window
ahk_classWindow Class
ahk_idUnique ID/HWND
ahk_pidProcess ID
ahk_exeProcess Name/Path
ahk_groupWindow Group
 Multiple Criteria
(All empty)Last Found Window

Matching Behaviour

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 ahk_class and ahk_exe 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 On, except with WinShow, which always detects hidden windows.

If multiple windows match the 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.

Active Window (A)

If WinTitle is the letter A and the other 3 window parameters (WinText, ExcludeTitle and ExcludeText) are blank or omitted, the active window will be used.

; Retrieve the ID/HWND of the active window
MsgBox WinExist("A")

; Press Win+↑ to maximize the active window
#Up::WinMaximize "A"

ahk_class 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. To use a window class, specify ahk_class ExactClassName as shown by Window Spy. ExactClassName can be retrieved by WinGetClass.

If the RegEx title matching mode is active, ahk_class accepts a regular expression.

; Activate a console window (e.g. cmd.exe)
WinActivate "ahk_class ConsoleWindowClass"

ahk_id Unique ID / HWND

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 changes. There are three ways to specify an ID in a WinTitle parameter, as shown in the examples below:

; 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

DetectHiddenWindows affects whether ahk_id detects hidden top-level windows, but hidden controls are always detected. Hidden windows are always detected if a valid Integer or Object is passed.

ahk_id 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 a WinTitle parameter.

ahk_pid Process ID

Use ahk_pid to identify a window belonging to a specific process. The process identifier (PID) is typically retrieved by WinGetPID, Run or Process functions.

WinActivate "ahk_pid " VarContainingPID

ahk_exe Process Name/Path

Use ahk_exe to identify a window belonging to any process with the given name or path.

While ahk_pid is limited to one specific process, ahk_exe considers all processes with name or full path matching a given string. If the RegEx title matching mode is active, ahk_exe accepts a regular expression which must match the full path of the process. Otherwise, ahk_exe 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.

; Activate an existing notepad.exe window, or open a new one
if WinExist("ahk_exe notepad.exe")
    WinActivate "ahk_exe notepad.exe"
    Run "notepad.exe"
SetTitleMatchMode "RegEx"
WinActivate "ahk_exe i)\\notepad\.exe$"  ; Match the name part of the full path.

ahk_group Window Group

Use ahk_group to identify a window or windows matching the rules contained by a previously defined window group.

The functions WinMinimize, WinMaximize, WinRestore, WinHide, WinShow, WinClose, and WinKill will act on all the group's windows. By contrast, the other window functions such as WinActivate and WinExist will operate only on the topmost window of the 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"

Multiple Criteria

By contrast with ahk_group (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).

ahk_id 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."

The "Last Found" Window

This is the window most recently found by IfWin[Not]Exist, WinExist, IfWin[Not]Active, WinActive, WinWait[Not]Active, or WinWait. It can make scripts easier to create and maintain since the 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 Off. This is often used in conjunction with the GUI's +LastFound option.

Run "notepad"
WinWait "Untitled - Notepad"
WinActivate  ; Uses the last found window.

if WinExist("Untitled - Notepad")
    WinActivate  ; Automatically uses the window found above.
    WinMaximize  ; same
    Send "Some text.{Enter}"

if not WinExist("Calculator")
    WinActivate  ; The above "WinExist" also set the "last found" window for us.
    WinMove 40, 40  ; Move it to a new position.