Gdi::EnumDisplayMonitors_I

  • Article

This method enumerates screens that intersect a region formed by the intersection of a specified clipping rectangle and the visible region of a specified device context.

static BOOL WINAPI EnumDisplayMonitors_I(
  HDC hdcPaint,
  LPCRECT lprcPaint,
  MONITORENUMPROC lpfnEnum,
  LPARAM lData
  HPROCESS hProcCallingContext
);

Parameters

  • hdcPaint
    [in] Handle to a display device context that specifies the visible region of interest. When this parameter is NULL, the hdcMonitor parameter that Gdi::EnumDisplayMonitors_I passes to the MonitorEnumProc callback function is NULL, and the visible region of interest is the virtual screen that encompasses all of the screens connected to the Windows CE–based device.
  • lprcPaint
    [in] Pointer to a RECT structure that specifies a clipping rectangle. The region of interest is the intersection of the clipping rectangle with the visible region specified by hdcPaint. If hdcPaint is not NULL, specify the coordinates of the clipping rectangle relative to the origin of the hdcPaint. If hdcPaint is NULL, specify virtual screen coordinates. Set lprcPaint equal to NULL if you do not want to clip the region specified by hdcPaint.
  • lpfnEnum
    [in] Pointer to an application-defined MonitorEnumProc callback function that you want Gdi::EnumDisplayMonitors_I to call for each screen it enumerates. This parameter cannot be NULL.
  • lData
    [in] LPARAM that specifies application-defined data that you want Gdi::EnumDisplayMonitors_I to pass directly to MonitorEnumProc.
  • hProcCallingContext
    [in] Handle of the process that owns the pointer for the callback function specified by lpfnEnum.

Return Values

TRUE indicates success. FALSE indicates failure or that lpfnEnum is NULL. To get extended error information, call GetLastError. When lpfnEnum is NULL, GetLastError returns ERROR_INVALID_PARAMETER.

Remarks

This method is an internal version of the EnumDisplayMonitors function.

You should call the Gdi::EnumDisplayMonitors_I function if you want to:

  • Draw optimally into a device context that spans several screens.
  • Obtain a handle and position rectangle for one or more screens.

Gdi::EnumDisplayMonitors_I calls an application-defined MonitorEnumProc callback function once for each screen that Gdi::EnumDisplayMonitors_I enumerates.

By setting the hdcPaint parameter to NULL, you can use Gdi::EnumDisplayMonitors_I to obtain a handle and position rectangle for one or more screens. The following table shows how the four combinations of NULL and non-NULL hdcPaint and lprcPaint values affect the behavior of Gdi::EnumDisplayMonitors_I.

Value of hdcPaint Value of lprcPaint Behavior of Gdi::EnumDisplayMonitors_I
NULL NULL Enumerates all screens and passes a NULL hdc to the callback function.
NULL non-NULL Enumerates all screens that intersect the clipping rectangle and passes a NULL hdc to the callback function. Use virtual screen coordinates for the clipping rectangle.
non-NULL NULL Enumerates all screens that intersect the visible region of the device context and passes an hdc for each specific screen to the callback function.
non-NULL non-NULL Enumerates all screens that intersect the visible region of the device context and the clipping rectangle and passes an hdc for each specific screen to the callback function. Use device context coordinates for the clipping rectangle.

Note   To make the following code examples easier to read, error checking is not included. These code examples should not be used in a release configuration unless they have been modified to include secure error handling.

The following code example shows how to paint in response to a WM_PAINT message using the capabilities of each screen.

case WM_PAINT:
  hdc = GweBypassCoredllThunk_t::BeginPaint_I(hwnd, &ps);
  Gdi::EnumDisplayMonitors_I(hdc, NULL, MyPaintEnumProc, 0);
  GweBypassCoredllThunk_t::EndPaint_I(hwnd, &ps);

The following code example shows how to paint the top half of a window using the capabilities of each screen.

GweBypassCoredllThunk_t::GetClientRect_I(hwnd, &rc);
rc.bottom = (rc.bottom - rc.top) / 2;
hdc = GweBypassCoredllThunk_t::GetDC_I(hwnd);
Gdi::EnumDisplayMonitors_I(hdc, &rc, MyPaintEnumProc, 0);
GweBypassCoredllThunk_t::ReleaseDC_I(hwnd, hdc);

The following code example shows how to paint the entire virtual screen optimally for each screen.

hdc = GweBypassCoredllThunk_t::GetDC_I(NULL);
Gdi::EnumDisplayMonitors_I(hdc, NULL, MyPaintScreenEnumProc, 0);
GweBypassCoredllThunk_t::ReleaseDC_I(NULL, hdc);

The following code example shows how to get information about all of the screens.

Gdi::EnumDisplayMonitors_I(NULL, NULL, MyInfoEnumProc, 0);

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Gdi.hpp.

See Also

EnumDisplayMonitors | MonitorEnumProc | RECT

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.