SetWindowRgn Function

Declare Function SetWindowRgn Lib "user32.dll" (ByVal hWnd As Long, ByVal hRgn As Long, ByVal bRedraw As Boolean) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.51 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

SetWindowRgn changes the visible region of a window. Using this function, you can make a window appear non-rectangular. Any portion of the window lying outside of the region is not drawn, and so is invisible.

Return Value

If successful, the function returns a non-zero value. If an error occured, the function returns zero (Windows NT/2000: use GetLastError to get the error code).

Visual Basic-Specific Issues

None.

Parameters

hWnd: A handle to the window to set the region of.
hRgn: A handle to a region that defines what to make the visible area of the window. If this is zero, the entire window is displayed (effectively removing any special region set previously).
bRedraw: Specifies whether to immediately redraw the window using its new region or not. If this is True, the window is redrawn. If this is False, it is not.

Example

Use an elliptic region to make window Form1 appear elliptical. Notice how, as this example is written, a portion of the title bar is still visible after applying the region. This allows us to move the window without adding any special code providing a different way for the user to move the window. Normally, in a real program, you would not want the title bar to be displayed, but after all, this is just an example. At least it shows you that the region only changes what part of the window you can see -- it doesn't change anything else about the window.

To run this example, make two windows Form1 and Form2. The latter will be used to illustrate GetWindowRgn. Place the following three buttons on Form1: a button labeled "Apply Region" and named cmdApplyRegion, a button labeled "Remove Region" and named cmdRemoveRegion, and a button labeled "Show Region" and named cmdShowRegion. Place these buttons near the center of Form1 to make sure parts of them won't be hidden when the region is applied.

' This code is licensed according to the terms and conditions listed here.

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Declare Function GetWindowRgn Lib "user32.dll" (ByVal hWnd As Long, ByVal hRgn As Long) As Long
Public Declare Function SetWindowRgn Lib "user32.dll" (ByVal hWnd As Long, ByVal hRgn As Long, _
	ByVal bRedraw As Boolean) As Long
Public Declare Function CreateEllipticRgn Lib "gdi32.dll" (ByVal nLeftRect As Long, ByVal nTopRect _
	As Long, ByVal nRightRect As Long, ByVal nBottomRect As Long) As Long
Public Declare Function DeleteObject Lib "gdi32.dll" (ByVal hObject As Long) As Long
Public Declare Function InvertRgn Lib "gdi32.dll" (ByVal hdc As Long, ByVal hrgn As Long) As Long

' *** Place the following code inside Form1. ***

' Stores a handle to the special window region, if it exists.
Private hRgnWindow As Long

Private Sub Form_Load()
	' Open Form2 when this loads.  Form2 is used to display a sort of
	' "shadow" of the region used by Form1, although it really isn't a shadow effect.
	Form2.Show
	
	' Initially disable the "Remove Region" button, sice one hasn't
	' yet been applied.
	cmdRemoveRegion.Enabled = False
End Sub

Private Sub cmdApplyRegion_Click()
	' Create an elliptic region slightly smaller than the current size of
	' Form1, and make that the window region.  This makes the previously
	' rectangular Form1 appear to be an ellipse.
	
	Dim retval As Long  ' return value
	
	' First, make the elliptical region, slightly smaller than Form1.
	hRgnWindow = CreateEllipticRgn(5, 5, (Form1.Width / Screen.TwipsPerPixelX) - 5, _
		(Form1.Height / Screen.TwipsPerPixelY) - 5)
	' Apply this region to Form1 and show the change immediately.
	retval = SetWindowRgn(Form1.hWnd, hRgnWindow, True)
	
	' To make sure that multiple regions aren't created, disable
	' this button and enable the "Remove Region" button.
	cmdApplyRegion.Enabled = False
	cmdRemoveRegion.Enabled = True
End Sub

Private Sub cmdRemoveRegion_Click()
	' Remove the window region from Form1, returning it to its
	' normal rectangular shape.
	
	Dim retval As Long  ' return value
	
	' Set a null window region, which removes the current one entirely.
	retval = SetWindowRgn(Form1.hWnd, 0, True)
	' Delete the region object because it is no longer needed.
	retval = DeleteObject(hRgnWindow)
	
	' Since the region no longer exists, enable "Apply Region" and
	' disable this button.
	cmdApplyRegion.Enabled = True
	cmdRemoveRegion.Enabled = False
End Sub

Private Sub cmdShowRegion_Click()
	' Show the region currently applied to Form1 by inverting that region on
	' Form2.  Note that if no region is applied, nothing appears to happen because
	' the actual window region is empty.
	
	Dim hRgnCopy As Long  ' region that receives copy of Form1's region
	Dim retval As Long    ' return value
	
	' Create a region.  It doesn't matter what, since it will be overwritten
	' when GetWindowRgn is called.  We just need to have some region.
	hRgnCopy = CreateEllipticRgn(0, 0, 0, 0)
	' Copy Form1's region to hRgnCopy.  The actual value of the handle
	' does not change, but the information it "points" to does.
	retval = GetWindowRgn(Form1.hWnd, hRgnCopy)
	' Invert the colors on Form2 that lie within this region.
	retval = InvertRgn(Form2.hDC, hRgnCopy)
	' Delete the copied region, since we no longer need it.
	retval = DeleteObject(hRgnCopy)
End Sub