WinSetRegion

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

WinSetRegion Options, WinTitle, WinText, ExcludeTitle, ExcludeText

Parameters

Options

Type: String

If blank or omitted, 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: h200.

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.

WinTitle

Type: String, Integer or Object

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

WinText

Type: String

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

Type: String

Windows whose titles include this value will not be considered.

ExcludeText

Type: String

Windows whose text include this value will not be considered.

Error Handling

An exception is thrown on failure. 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.

Remarks

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

Win functions, Control functions

Examples

#1

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

#2: Here is a region with a more complex area. It creates a see-through rectangular hole inside Notepad (or any other 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", "ahk_class Notepad"