3 out of 4 rated this helpful - Rate this topic

RedrawWindow function

Applies to: desktop apps only

The RedrawWindow function updates the specified rectangle or region in a window's client area.

Syntax

Copy

BOOL RedrawWindow(
  __in  HWND hWnd,
  __in  const RECT *lprcUpdate,
  __in  HRGN hrgnUpdate,
  __in  UINT flags
);

Parameters

hWnd [in]

A handle to the window to be redrawn. If this parameter is NULL, the desktop window is updated.

lprcUpdate [in]

A pointer to a RECT structure containing the coordinates, in device units, of the update rectangle. This parameter is ignored if the hrgnUpdate parameter identifies a region.

hrgnUpdate [in]

A handle to the update region. If both the hrgnUpdate and lprcUpdate parameters are NULL, the entire client area is added to the update region.

flags [in]

One or more redraw flags. This parameter can be used to invalidate or validate a window, control repainting, and control which windows are affected by RedrawWindow.

The following flags are used to invalidate the window.

Flag (invalidation)	Description
RDW_ERASE	Causes the window to receive a WM_ERASEBKGND message when the window is repainted. The RDW_INVALIDATE flag must also be specified; otherwise, RDW_ERASE has no effect.
RDW_FRAME	Causes any part of the nonclient area of the window that intersects the update region to receive a WM_NCPAINT message. The RDW_INVALIDATE flag must also be specified; otherwise, RDW_FRAME has no effect. The WM_NCPAINT message is typically not sent during the execution of RedrawWindow unless either RDW_UPDATENOW or RDW_ERASENOW is specified.
RDW_INTERNALPAINT	Causes a WM_PAINT message to be posted to the window regardless of whether any portion of the window is invalid.
RDW_INVALIDATE	Invalidates lprcUpdate or hrgnUpdate (only one may be non-NULL). If both are NULL, the entire window is invalidated.

The following flags are used to validate the window.

Flag (validation)	Description
RDW_NOERASE	Suppresses any pending WM_ERASEBKGND messages.
RDW_NOFRAME	Suppresses any pending WM_NCPAINT messages. This flag must be used with RDW_VALIDATE and is typically used with RDW_NOCHILDREN. RDW_NOFRAME should be used with care, as it could cause parts of a window to be painted improperly.
RDW_NOINTERNALPAINT	Suppresses any pending internal WM_PAINT messages. This flag does not affect WM_PAINT messages resulting from a non-NULL update area.
RDW_VALIDATE	Validates lprcUpdate or hrgnUpdate (only one may be non-NULL). If both are NULL, the entire window is validated. This flag does not affect internal WM_PAINT messages.

The following flags control when repainting occurs. RedrawWindow will not repaint unless one of these flags is specified.

Flag	Description
RDW_ERASENOW	Causes the affected windows (as specified by the RDW_ALLCHILDREN and RDW_NOCHILDREN flags) to receive WM_NCPAINT and WM_ERASEBKGND messages, if necessary, before the function returns. WM_PAINT messages are received at the ordinary time.
RDW_UPDATENOW	Causes the affected windows (as specified by the RDW_ALLCHILDREN and RDW_NOCHILDREN flags) to receive WM_NCPAINT, WM_ERASEBKGND, and WM_PAINT messages, if necessary, before the function returns.

By default, the windows affected by RedrawWindow depend on whether the specified window has the WS_CLIPCHILDREN style. Child windows that are not the WS_CLIPCHILDREN style are unaffected; non-WS_CLIPCHILDREN windows are recursively validated or invalidated until a WS_CLIPCHILDREN window is encountered. The following flags control which windows are affected by the RedrawWindow function.

Flag	Description
RDW_ALLCHILDREN	Includes child windows, if any, in the repainting operation.
RDW_NOCHILDREN	Excludes child windows, if any, from the repainting operation.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

When RedrawWindow is used to invalidate part of the desktop window, the desktop window does not receive a WM_PAINT message. To repaint the desktop, an application uses the RDW_ERASE flag to generate a WM_ERASEBKGND message.

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll

The RECT uses client coordinates for the window being redrawn. In other words, 0,0 is the pixel just below the window's titlebar and frame. If you have screen coordinates you must convert them to be relative to that point.
lprcUpdate (and probably hrgnUpdate) must be NULL if RDW_FRAME is used. If you don't pass a NULL rect then it seems random bits of the frame are randomly not redrawn (especially if you ask the window to redraw its frame several times in quick succession).

Since the rect is client-relative, and the documentation explicitly says that RDW_FRAME respects the update region (and that the rect defines that if the region is not given), you might think you could pass a rect with negative starting coordinates but that does not seem to work. Nor does using screen coordinates when passing RDW_FRAME. It has to be NULL. It does work sometimes if you don't pass NULL but not always and code which tries anything else WILL leave junk in titlebars from time to time.

(As a corollary of this, I don't think you can reliably request that only part of the non-client area be repainted; it has to be the whole thing. That in turn means if you only want to redraw part of a window -- minimizing excessive painting -- then you need to call RedrawWindow twice: Once to get the entire non-client area to redraw and again to get just the part of the client area you want to redraw.)

At least, these are my observations after a couple of hours experimenting and fighting with this API and documentation on a Windows 7 machine set to Classic mode.

History

3/30/2011
Leo Davidson