WinGet

Functions for retrieving information about a window, or a list of windows. These functions all have the same syntax, as below; just replace WinGetX with the appropriate function name.

OutputVar := WinGetX(WinTitle, WinText, ExcludeTitle, ExcludeText)

Parameters

OutputVar

The name of the variable in which to store the result of the command. When calling the command as a function, OutputVar represents its return value.

WinTitle

A window title or other criteria identifying the target window. See WinTitle.

WinText

If present, this parameter must be a substring from a single text element of the target window (as revealed by the included Window Spy utility). Hidden text elements are detected if DetectHiddenText is ON.

ExcludeTitle

Windows whose titles include this value will not be considered.

ExcludeText

Windows whose text include this value will not be considered.

Functions

WinGetID: Equivalent to WinExist. Retrieves the unique ID number (HWND/handle) of a window. If there is no matching window, OutputVar is made blank. WinGetID("A") is a fast way to get the ID of the active window. To discover the HWND of a control (for use with Post/SendMessage or DllCall), use ControlGetHwnd or MouseGetPos.

WinGetIDLast: Same as above except it retrieves the ID of the last/bottommost window if there is more than one match. If there is only one match, it performs identically to ID. This concept is similar to that used by WinActivateBottom.

WinGetPID: Retrieves the Process ID (PID) of a window.

WinGetProcessName: Retrieves the name of the process (e.g. notepad.exe) that owns a window. If there are no matching windows, OutputVar is made blank.

WinGetProcessPath: Similar to ProcessName, but retrieves the full path and name of the process instead of just the name.

WinGetCount: Retrieves the number of existing windows that match the specified WinTitle, WinText, ExcludeTitle, and ExcludeText (0 if none). To count all windows on the system, omit all four title/text parameters. Hidden windows are included only if DetectHiddenWindows has been turned on.

WinGetList: Retrieves an array of the unique ID numbers of all existing windows that match the specified WinTitle, WinText, ExcludeTitle, and ExcludeText. To retrieve all windows on the entire system, omit all four title/text parameters.

WinGetMinMax: Retrieves the minimized/maximized state for a window. OutputVar is made blank if no matching window exists; otherwise, it is set to one of the following numbers:
-1: The window is minimized (WinRestore can unminimize it).
1: The window is maximized (WinRestore can unmaximize it).
0: The window is neither minimized nor maximized.

WinGetControls: Retrieves an array of control names for all controls in a window. If no matching window exists, OutputVar is made blank. If there are no controls in the window, the result is an empty array. Otherwise, each control name consists of its class name followed immediately by its sequence number (ClassNN), as shown by Window Spy.

Controls are sorted according to their Z-order, which is usually the same order as TAB key navigation if the window supports tabbing.

The control currently under the mouse cursor can be retrieved via MouseGetPos.

WinGetControlsHwnd: Same as above except it retrieves the window handle (HWND) of each control rather than its ClassNN.

WinGetTransparent: Retrieves the degree of transparency of a window (see WinSetTransparent for how to set transparency). OutputVar is made blank if: 1) the OS is older than Windows XP; 2) there are no matching windows; 3) the window has no transparency level; or 4) other conditions (caused by OS behavior) such as the window having been minimized, restored, and/or resized since it was made transparent. Otherwise, a number between 0 and 255 is stored, where 0 indicates an invisible window and 255 indicates an opaque window. For example:

MouseGetPos,,, MouseWin
WinGetTransparent, Transparent, ahk_id %MouseWin%  ; Transparency of window under the mouse cursor.

WinGetTransColor: Retrieves the color that is marked transparent in a window (see WinSetTransColor for how to set the TransColor). OutputVar is made blank if: 1) the OS is older than Windows XP; 2) there are no matching windows; 3) the window has no transparent color; or 4) other conditions (caused by OS behavior) such as the window having been minimized, restored, and/or resized since it was made transparent. Otherwise, a six-digit hexadecimal RGB color is stored, e.g. 0x00CC99. For example:

MouseGetPos,,, MouseWin
WinGetTransColor, TransColor, ahk_id %MouseWin%  ; TransColor of the window under the mouse cursor.

WinGetStyle or WinGetExStyle: Retrieves an integer representing the style or extended style (respectively) of a window. If there are no matching windows, OutputVar is made blank. The following example determines whether a window has the WS_DISABLED style:

WinGetStyle, Style, My Window Title
if (Style & 0x8000000)  ; 0x8000000 is WS_DISABLED.
  ... the window is disabled, so perform appropriate action.

The next example determines whether a window has the WS_EX_TOPMOST style (always-on-top):

WinGetExStyle, ExStyle, My Window Title
if (ExStyle & 0x8)  ; 0x8 is WS_EX_TOPMOST.
  ... the window is always-on-top, so perform appropriate action.

See the styles table for a partial listing of styles.

Remarks

A window's ID number is valid only during its lifetime. In other words, if an application restarts, all of its windows will get new ID numbers.

ID numbers retrieved by these commands are numeric (the prefix "ahk_id" is not included).

The ID of the window under the mouse cursor can be retrieved with MouseGetPos.

Window titles and text are case sensitive. Hidden windows are not detected unless DetectHiddenWindows has been turned on.

Related

WinGetClass, Process, WinGetTitle, MouseGetPos, Control functions, ControlFocus, GroupAdd

Examples

; Example #1: Maximize the active window and report its unique ID:
WinGetID, active_id, A
WinMaximize, ahk_id %active_id%
MsgBox, The active window's ID is "%active_id%".

; Example #2: This will visit all windows on the entire system and display info about each of them:
WinGetList, id,,, Program Manager
Loop % id.Length
{
    this_id := id[A_Index]
    WinActivate, ahk_id %this_id%
    WinGetClass, this_class, ahk_id %this_id%
    WinGetTitle, this_title, ahk_id %this_id%
    Result := MsgBox("Visiting All Windows`n%a_index% of %id.Length%`nahk_id %this_id%`nahk_class %this_class%`n%this_title%`n`nContinue?",, 4)
    if Result = "No", break
}

; Example #3: Display each of a window's control names:
for n, ctrl in WinGetControls("A")
{
    Result := MsgBox("Control #%n% is "%ctrl%". Continue?",, 4)
    if Result = "No"
        break
}

; Example #4: Display in real time the active window's control list:
SetTimer, WatchActiveWindow, 200

WatchActiveWindow() {
    ControlList := ""
    WinGetControls, Controls, A
    if !Controls {
        ToolTip, No visible window is active.
        return
    }
    if !Controls.Length() {
        ToolTip, The active window has no controls.
        return
    }
    Loop % Controls.Length()
        ControlList .= Controls[A_Index] . "`n"
    ToolTip, %ControlList%
}