WinSetRegion

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

WinSetRegion Options, WinTitle, WinText,  ExcludeTitle, ExcludeText

Command  Example: WinSetRegion "AlwaysOnTop", "On", "A"
Function Example: WinSetRegion("AlwaysOnTop", "On", "A")

Parameters

Options (optional)

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: WinSet, Region, 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

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.

Remarks

ErrorLevel is set to 1 upon failure and 0 upon success. 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.

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

Related

WinHide, WinSetTitle, WinMove, WinActivate, Control

Examples

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