CWnd::GetDCEx

Retrieves the handle of a device context for the CWnd window.

CDC* GetDCEx(
   CRgn* prgnClip,
   DWORD flags 
);

Parameters

  • prgnClip
    Identifies a clipping region that may be combined with the visible region of the client window.

  • flags
    Can have one of the following preset values:

    • DCX_CACHE   Returns a device context from the cache rather than the OWNDC or CLASSDC window. Overrides CS_OWNDC and CS_CLASSDC.

    • DCX_CLIPCHILDREN   Excludes the visible regions of all child windows below the CWnd window.

    • DCX_CLIPSIBLINGS   Excludes the visible regions of all sibling windows above the CWnd window.

    • DCX_EXCLUDERGN   Excludes the clipping region identified by prgnClip from the visible region of the returned device context.

    • DCX_INTERSECTRGN   Intersects the clipping region identified by prgnClip within the visible region of the returned device context.

    • DCX_LOCKWINDOWUPDATE   Allows drawing even if there is a LockWindowUpdate call in effect that would otherwise exclude this window. This value is used for drawing during tracking.

    • DCX_PARENTCLIP   Uses the visible region of the parent window and ignores the parent window's WS_CLIPCHILDREN and WS_PARENTDC style bits. This value sets the device context's origin to the upper-left corner of the CWnd window.

    • DCX_WINDOW   Returns a device context that corresponds to the window rectangle rather than the client rectangle.

Return Value

The device context for the specified window if the function is successful; otherwise NULL.

Remarks

The device context can be used in subsequent GDI functions to draw in the client area.

This function, which is an extension to the GetDC function, gives an application more control over how and whether a device context for a window is clipped.

Unless the device context belongs to a window class, the ReleaseDC function must be called to release the context after drawing. Since only five common device contexts are available at any given time, failure to release a device context can prevent other applications from gaining access to a device context.

To obtain a cached device context, an application must specify DCX_CACHE. If DCX_CACHE is not specified and the window is neither CS_OWNDC nor CS_CLASSDC, this function returns NULL.

A device context with special characteristics is returned by the GetDCEx function if the CS_CLASSDC, CS_OWNDC, or CS_PARENTDC style was specified in the WNDCLASS structure when the class was registered.

For more information about these characteristics, see the description of the WNDCLASS structure in the Windows SDK.

Requirements

Header: afxwin.h

See Also

Reference

CWnd Class

Hierarchy Chart

CWnd::BeginPaint

CWnd::GetDC

CWnd::GetWindowDC

CWnd::ReleaseDC

GetDCEx

Concepts

CWnd Members