WinSet

Functions for making a variety of changes to a window, such as "always on top" and transparency.

WinSetAlwaysOnTop

Makes a window stay on top of all other windows (except other always-on-top windows).

WinSetAlwaysOnTop Value, WinTitle, WinText, ExcludeTitle, ExcludeText

Value

One of the following case-insensitive text values or numbers:

ON or 1 (true) turns on the setting.
OFF or 0 (false) turns off the setting.
TOGGLE or -1 sets it to the opposite of its current state.

If omitted, it defaults to TOGGLE.

WinGetExStyle can be used to determine whether a window is always-on-top.

Related: Window Parameters, Return Value

WinMoveBottom

Sends a window to the bottom of stack; that is, beneath all other windows. The effect is similar to pressing Alt-Escape.

WinMoveBottom WinTitle, WinText, ExcludeTitle, ExcludeText

Related: Window Parameters, Return Value

WinMoveTop

Brings a window to the top of the stack without explicitly activating it.

WinMoveTop WinTitle, WinText, ExcludeTitle, ExcludeText

The system default settings will probably cause it to activate in most cases. In addition, this command may have no effect due to the operating system's protection against applications that try to steal focus from the user (it may depend on factors such as what type of window is currently active and what the user is currently doing). One possible work-around is to make the window briefly AlwaysOnTop, then turn off AlwaysOnTop.

Related: Window Parameters, Return Value

WinSetEnabled

Enables or disables a window.

WinSetEnabled Value , WinTitle, WinText, ExcludeTitle, ExcludeText

Value

One of the following case-insensitive text values or numbers:

ON or 1 (true) turns on the setting.
OFF or 0 (false) turns off the setting.
TOGGLE or -1 sets it to the opposite of its current state.

If omitted, it defaults to TOGGLE.

When a window is disabled, the user cannot move it or interact with its controls. In addition, disabled windows are omitted from the alt-tab list.

WinGetStyle can be used to determine whether a window is disabled.

Related: Window Parameters, Return Value

WinRedraw

Attempts to update the appearance/contents of a window by informing the OS that the window's rectangle needs to be redrawn.

WinRedraw WinTitle, WinText, ExcludeTitle, ExcludeText

If this method does not work for a particular window, try WinMove. If that does not work, try the following:

WinHide, WinTitle
WinShow, WinTitle

Related: Window Parameters, Return Value

WinSetStyle / WinSetExStyle

Changes the style or extended style of a window.

WinSetStyle Value , WinTitle, WinText, ExcludeTitle, ExcludeText
WinSetExStyle Value , WinTitle, WinText, ExcludeTitle, ExcludeText

Value

Pass a positive integer to completely overwrite the window's style; that is, to set it to Value.

To easily add, remove or toggle styles, pass a numeric string prefixed with a plus sign (+), minus sign (-) or caret (^), respectively. The new style value is calculated as shown below (where CurrentStyle could be retrieved with WinGetStyle/WinGetExStyle):

Operation	Prefix	Example String	Formula
Add	+	+0x80	NewStyle := CurrentStyle | Value
Remove	-	-0x80	NewStyle := CurrentStyle & ~Value
Toggle	^	^0x80	NewStyle := CurrentStyle ^ Value

If Value is a negative integer, it is treated the same as the corresponding numeric string.

To use the + or ^ prefix literally in an expression, the prefix or value must be enclosed in quote marks. For example: WinSetStyle("+0x80") or WinSetStyle("^" StylesToToggle). This is because the expression +123 produces 123 (without a prefix) and ^123 is a syntax error.

After applying certain style changes to a visible window, it might be necessary to redraw the window using WinRedraw. Finally, the styles table lists some of the common style numbers. Examples:

WinSetStyle, -0xC00000, A  ; Remove the active window's title bar (WS_CAPTION).
WinSetExStyle, ^0x80, WinTitle  ; Toggle the WS_EX_TOOLWINDOW attribute, which removes/adds the window from the alt-tab list.

Related: Window Parameters, Return Value, WinGetStyle/WinGetExStyle

WinSetRegion

Changes the shape of a window to be the specified rectangle, ellipse, or polygon.

WinSetRegion Options, WinTitle, WinText, ExcludeTitle, ExcludeText

If the Options parameter is blank, the window is restored to its original/default display area. Otherwise, one or more of the following options can be specified, each separated from the others with space(s):

Wn: Width of rectangle or ellipse. For example: w200.
Hn: Height of rectangle or ellipse. For example: h300.
X-Y: Each of these is a pair of X/Y coordinates. For example, 200-0 would use 200 for the X coordinate and 0 for the Y.
E: Makes the region an ellipse rather than a rectangle. This option is valid only when W and H are present.
R[w-h]: Makes the region a rectangle with rounded corners. For example, R30-30 would use a 30x30 ellipse for each corner. If w-h is omitted, 30-30 is used. R is valid only when W and H are present.

Rectangle or ellipse: If the W and H options are present, the new display area will be a rectangle whose upper left corner is specified by the first (and only) pair of X-Y coordinates. However, if the E option is also present, the new display area will be an ellipse rather than a rectangle. For example: WinSetRegion, 50-0 W200 H250 E, WinTitle.

Polygon: When the W and H options are absent, the new display area will be a polygon determined by multiple pairs of X-Y coordinates (each pair of coordinates is a point inside the window relative to its upper left corner). For example, if three pairs of coordinates are specified, the new display area will be a triangle in most cases. The order of the coordinate pairs with respect to each other is sometimes important. In addition, the word Wind maybe be present in Options to use the winding method instead of the alternating method to determine the polygon's region.

ErrorLevel and the function's return value are set based on whether the function succeeds or fails. Failure occurs when: 1) the target window does not exist; 2) one or more Options are invalid; 3) more than 2000 pairs of coordinates were specified; or 4) the specified region is invalid or could not be applied to the target window.

See the bottom of this page for examples of how to use this command.

Related: Window Parameters, Return Value

WinSetTransparent

Makes a window semi-transparent.

WinSetTransparent N, WinTitle, WinText, ExcludeTitle, ExcludeText

N

To enable transparency, specify a number between 0 and 255 indicating the degree of transparency: 0 makes the window invisible while 255 makes it opaque.

To turn off transparency completely, specify the word OFF (case-insensitive).

Turning off transparency is different than specifying 255 because it may improve performance and reduce usage of system resources (but probably only on Windows XP, or when desktop composition is disabled).

Known Limitations for Transparent and TransColor:

• Setting "Transparent" to 255 prior to turning it off might avoid window redrawing problems such as a black background. If the window still fails to be redrawn correctly, see Redraw for a possible workaround.
• To change a window's existing TransColor, it may be necessary to turn off transparency before making the change.

Tip: To make the task bar transparent, use WinSetTransparent, 150, ahk_class Shell_TrayWnd. Similarly, to make the Start Menu transparent, follow this example:

DetectHiddenWindows, on
WinSetTransparent, 150, ahk_class BaseBar  ; To make the Start Menu's submenus transparent, also include the script below.

To make all or selected menus on the entire system transparent, keep a script such as the following always running. Note that although such a script cannot make its own menus transparent, it can make those of other scripts transparent:

SetTimer, WatchForMenu, 5
return  ; End of auto-execute section.

WatchForMenu:
DetectHiddenWindows, on  ; Might allow detection of menu sooner.
If WinExist("ahk_class #32768")
    WinSetTransparent, 150  ; Uses the window found by the above line.
return

Related: Window Parameters, Return Value, WinGetTransparent

WinSetTransColor

WinSetTransColor Color N , Options, WinTitle, WinText, ExcludeTitle, ExcludeText

Makes all pixels of the chosen color invisible inside the target window, which allows the contents of the window behind it to show through. If the user clicks on an invisible pixel, the click will "fall through" to the window behind it. Specify for Color a color name or RGB value (see the color chart for guidance, or use PixelGetColor in its RGB mode). To additionally make the visible part of the window partially transparent, append a space (not a comma) followed by the transparency level (0-255). For example: WinSetTransColor, EEAA99 150, WinTitle.

TransColor is often used to create on-screen displays and other visual effects. There is an example of an on-screen display at the bottom of the Gui page.

The word OFF may be specified to completely turn off transparency for a window. Both of the following are identical in function:

WinSetTransparent, Off, WinTitle
WinSetTransColor, Off, WinTitle

Known Limitations: See the list above.

Related: Window Parameters, Return Value, WinGetTransColor

Window Parameters

All of the functions on this page utilize the following parameters to identify the target window:

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.

Return Value

All of the functions on this page return 1 (true) on success and 0 (false) on failure. The return value is only accessible when using the function syntax.

Conversely, ErrorLevel is set to 0 (false) on success and 1 (true) on failure. ErrorLevel is always set.

Failure occurs if the target window is not found or the change could not be applied.

Remarks

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

Related

WinGet, WinHide, WinSetTitle, WinMove, WinActivate, Control functions

Examples

WinSetTransparent, 200, Untitled - Notepad ; Make the window a little bit transparent.
WinSetTransColor, White, Untitled - Notepad ; Make all white pixels invisible.
WinSetAlwaysOnTop, toggle, Calculator ; Toggle the always-on-top status of Calculator.

; Longer Example:
; Here are some hotkeys that demonstrate the effects of "Transparent" and
; "TransColor".  NOTE: If you press one of the hotkeys while the mouse cursor
; is hovering over a pixel that is invisible as a result of TransColor, the window
; visible beneath that pixel will be acted upon instead!

#t::  ; Press Win+T to make the color under the mouse cursor invisible.
MouseGetPos, MouseX, MouseY, MouseWin
PixelGetColor, MouseRGB, %MouseX%, %MouseY%, RGB
; In seems necessary to turn off any existing transparency first:
WinSetTransColor, Off, ahk_id %MouseWin%
WinSetTransColor, %MouseRGB% 220, ahk_id %MouseWin%
return

#o::  ; Press Win+O to turn off transparency for the window under the mouse.
MouseGetPos,,, MouseWin
WinSetTransColor, Off, ahk_id %MouseWin%
return

#g::  ; Press Win+G to show the current settings of the window under the mouse.
MouseGetPos,,, MouseWin
WinGetTransparent, Transparent, ahk_id %MouseWin%
WinGetTransColor, TransColor, ahk_id %MouseWin%
ToolTip Translucency:`t%Transparent%`nTransColor:`t%TransColor%
return

; Examples of "WinSet Region":
WinSetRegion, 50-0 W200 H250, WinTitle  ; Make all parts of the window outside this rectangle invisible.
WinSetRegion, 50-0 W200 H250 R40-40, WinTitle  ; Same as above but with corners rounded to 40x40.
WinSetRegion, 50-0 W200 H250 E, WinTitle  ; An ellipse instead of a rectangle.
WinSetRegion, 50-0 250-0 150-250, WinTitle  ; A triangle with apex pointing down.
WinSetRegion,, WinTitle ; Restore the window to its original/default display area.

; Here is a region with a more complex area. It creates a see-through rectangular hole inside a window.
; There are two rectangles specified below: an outer and an inner.  Each rectangle consists of 5 pairs
; of X/Y coordinates because the first pair is repeated at the end to "close off" each rectangle.
WinSetRegion, 0-0 300-0 300-300 0-300 0-0   100-100 200-100 200-200 100-200 100-100, WinTitle