Stob Here is a little contest, to which all fellow Windows programmers are invited. What is the API function LockWindowUpdate for? How might you use it? You are definitely allowed, nay encouraged, to use the official Microsoft documentation.
Here is the function description on MSDN, and here is the same documentation on the upgraded, new MSDN2, presumably so-called because it takes twice as long to display (Really. MSDN-1 takes 8-10 seconds here, versus 15-20 seconds for MSDN2, depending on time of day. Try it. Or better yet, choose your own function for the experiment, in case some MS wiseacre does a little spot of optimisation)
I first came upon this entry about 10 years ago or more, when I noticed that an MDI app that I had made used to flicker like mad while the code was opening up a shed load of database tables. I wanted to stop this. Searching MSDN on CD-ROM, I eventually stumbled on LockWindowUpdate, which from the cited function description looked like the business. So I wrapped up my update code in an exception-protected pair of calls, and congratulated myself on an excellent spot in the face of the sprawling hugeness of the Windows API.
I have previously mentioned Raymond Chen's blog. I recently came across this series of one, two, three, four and five articles, but the passage that secured my full attention is this bit from number four:
People see the "the window you lock won't be able to redraw itself" behavior of LockWindowUpdate and use it as a sort of lazy version of the WM_SETREDRAW message. Though sending the WM_SETREDRAW message really isn't that much harder than calling LockWindowUpdate. It's 20 more characters of typing, half that if you use the SetWindowRedraw macro in <windowsx.h>.
Gah?
So, just to get this straight, people who call LockWindowUpdate are lazy, are they Mr Chen? That would be as opposed to people who are so lazy that, for example, they don't bother to document their own API, eh Mr Chen?
Mr Chen's articles say, believably, that LockWindowUpdate is exclusively intended for dragging operations. You lock somebody else's window, you draw your dragged stuff on top of it, it can't mess up what you draw because you've locked it. There. I just accomplished in 25 odd words what MSDN fails to say in 10 times as many – ie to describe the intent of the function.
Because there is absolutely no way you can get from the information supplied in the MSDN to the intended purpose of this function, as explained by Mr Chen. You stand no chance whatsoever. The reference I gave you above makes no mention at all of this dragging stuff: not a scintilla of a sniff of a soupcon of a suggestion. Absolutely zip. If you relied on MSDN's entry of this function, you would never, ever use it correctly. You are dead meat.
Ok, so the function reference page is pants. What about MSDN's overview material? Mr Chen mocks those who have not read it ("there's more to documentation than dry function descriptions, people!"), but since there's no direct link to it from the function page, why would you find it? (And why isn't there a direct link? Easily generated automatically by a suitable program, I offer this to Microsoft as a free idea to improve MSDN at one bound, and generously undertake not to apply for a software patent for it)
By my reckoning, a minimum of three lucky clicks – at 20 slow seconds a shot on drive-time MSDN2, remember – will bring you to this page. What a disappointment when you get there. Instead of explaining how you, the punter, can use the function, it mostly discusses how "the system" (ie Windows itself) draws a "tracking rectangle". This is probably an excellent example if you happen to use Microsoft's jargon for "tracking rectangles" (I think from Mr Chen's discussion it means the XORed boundary line you used to get when dragging windows back in the days before they painted content on the move; a little picture would be good here). And, of course, if you happen to have the relevant Windows source code to hand.
As it is, I say the entry is more or less useless, although I admit, when you know what it is trying to say, it does corroborate Mr Chen's explanation of the function's purpose.
I suppose it's possible Mr Chen was attempting a joke with this "lazy" business. He complains at the end of his series that his jokes have been misunderstood. Reading carefully through the sequence, I haven't found anything at all that I believed was a joke, so it is therefore feasible that this is what the "20 more characters of typing" stuff is intended to be. I have to tell him that "Hahaha! Look what I know that you don't know because we don't tell you," doesn't feel very funny when viewed from outside Microsoft.
In the follow-ups to his blog, many others have raised the points I make here. What does Mr Chen think? In an early reply, Mr C hands out defensive guff about
the tension between "descriptive" and "prescriptive" documentation
which would seem to imply that he supports the MSDN stew that we find. But then later on he distances himself haughtily:
It appears that everybody is under the impression that I approve of the documentation
Yes, I wonder why that is?
Mr Chen surely knows that MSDN's coverage of LockWindowUpdate is a load of horse poo. He is able to supply an intelligible description of how it is supposed to be used, and his opening salvo in the first article ("Poor misunderstood LockWindowUpdate") makes it clear that he is aware that almost nobody outside the charmed circle groks it. In the past, Mr Chen has occasionally taken pride in shooting down other Microsoftees when he thinks it is deserved. Why, then, does he hold his fire here?
How about this: because LockWindowUpdate is entirely typical of MSDN. The whole, bloated thing is jam-packed with function descriptions that tell you everything about the function except what you need to know, huge, dull, explaining-by-not-explaining articles extracted like rotten teeth from MSDN Magazine and its predecessor MSJ, and filled with bogus enthusiasm for, say, this month's approved way of interfacing to databases.
Then there are the dreadful, slow searches, compulsory in the CD-ROM only days, now happily alleviated by Google (What is it about Microsoft and indexed searchable text? They always seem to get it badly wrong: think Windows Search, think those old help file indexes that always needed rebuilding). And why the almost complete absence of pictures? This is, after all, supposed to be the documentation for a graphical operating system.
