The DWM API is certainly a curious little bugger. Being the newest in the GUI API family, it still has quite a few kinks that need to be worked out.
One of the most common errors made with the DWM API involves the DwmExtendFrameIntoClientArea function. This function is used to extend the Aero glass border around a window into the client region so that controls can be placed onto it, much like in Windows Explorer and Microsoft Word.
Occassionally, the need arises to extend the glass into the entire window. There are plenty of tutorials out there on how to do this, so I will not bother describing the method in which this accomplished. However, each of these guides have one common error in common: they do not emphasize how to properly set the MARGINS struct passed to the DwmExtendFrameIntoClientArea function.
MSDN states only that “Negative margins are used to create the ‘sheet of glass’ effect where the client area is rendered as a solid surface with no window border.” It then goes on to provide an example in which the margin is set to { -1 }, which equates to { -1, 0, 0, 0 }. This is wrong.
Intentionally or not, some portions of the DWM API do not observe the rule that if any of the margin properties is negative, the glass should fill the entire window. Rather, they only check the specific property that concerns them. While the effects of this problem are rarely visible, under certain circumstances, odd bugs will begin to occur. For example, if a custom frame is rendered by returning 0 when sent a WM_NCCALCSIZE message, and DwmDefWindowProc is then used to process WM_NCHITTEST for caption buttons (HTCLOSE, HTMINBOX, HTMAXBOX), DwmDefWindowProc will refuse to process the message. When the message then default to DefWindowProc, HTCLOSE, HTMINBOX, and HTMAXBOX are returned as if the displayed buttons were Windows NT-style instead of Aero. This becomes apparent if a user clicks where a minimize/maximize button would be in a Windows NT-style form, drags outside the button, and then releases the mouse button on an improperly created form.
If you are the author of a tutorial or documentation describing the use of DwmExtendFrameIntoClientArea, please be sure to emphasize this common caveat in the DWM API. I am sure many of your readers will appreciate the hours of debugging and tinkering you will save them. Please note that, at the time of this writing, there was no documentation of this bug or its workaround on the Internet to the best of my knowledge. With customized borders quickly becoming more popular with the advent of Aero, I have no doubt more than a few developers will encounter this problem—the faster the word gets out, the better.
Paul Buonopane
April 9, 2010
10:43 PM EDT (GMT-4:00)