GetRandomRgn function (wingdi.h)

Article
02/22/2024

The GetRandomRgn function copies the system clipping region of a specified device context to a specific region.

Syntax

int GetRandomRgn(
  [in] HDC  hdc,
  [in] HRGN hrgn,
  [in] INT  i
);

Parameters

[in] hdc

A handle to the device context.

[in] hrgn

A handle to a region. Before the function is called, this identifies an existing region. After the function returns, this identifies a copy of the current system region. The old region identified by hrgn is overwritten.

[in] i

This parameter must be SYSRGN.

Return value

If the function succeeds, the return value is 1. If the function fails, the return value is -1. If the region to be retrieved is NULL, the return value is 0. If the function fails or the region to be retrieved is NULL, hrgn is not initialized.

Remarks

When using the SYSRGN flag, note that the system clipping region might not be current because of window movements. Nonetheless, it is safe to retrieve and use the system clipping region within the BeginPaint-EndPaint block during WM_PAINT processing. In this case, the system region is the intersection of the update region and the current visible area of the window. Any window movement following the return of GetRandomRgn and before EndPaint will result in a new WM_PAINT message. Any other use of the SYSRGN flag may result in painting errors in your application.

The region returned is in screen coordinates.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	wingdi.h (include Windows.h)
Library	Gdi32.lib
DLL	Gdi32.dll