SDK and API Errata

Poor Prior Planning Yields Piss Poor Results
Over the years and far too many projects, we have ran across some just plain wrong documentation in the SDK (Software Development Kit) from Microsoft. This documentation is commonly referred to as the Microsoft Developer Network, or MSDN. All of it is online from Microsoft, and most people get an update on CD whenever Microsoft feels like putting it out (three times a year or so). This is nice since hitting F1 brings up the docs.
Now we all know that programmers, as a class, do not write documentation, let alone good documentation. That is why there are people whose job it is to write these things. In most organizations that we've worked at over the last twenty years, this involves some sort of communication between staff members, and a review at some point (if not several) to verify the accuracy of the documentation.
However, it seems that Microsoft has a bad habit of not doing this. When they can throw 300+ people at the Visual C++ project, why can't there be CORRECT DOCUMENTATION? We're not talking good (it's boring stuff like WM_MOUSEMOVE) but just plain CORRECT.
But that's enough of a rant. Where possible, we've linked to the actual MSDN page on Microsoft.com for documentation in question.

Trackbars
The Trackbar or slider control has a lot of bugs in it:

• When using the the TBS_AUTOTICKS style and the TBM_SETTICFREQ call, TBM_GETTICPOS and TBM_GETPTICS do not return the position of the tick mark as the documentation says they do. Instead, they return some odd values that have no relation whatsoever to the position of the ticks (they seem to always run from 14 to 75, even when the control is like 140 pixels wide). However, if you instead use TBM_SETTIC to set up your own tic marks or tic array, then TBM_GETTICPOS and TBM_GETPTICS do return the correct values.
• The documentation for Selection Ranges seems to indicate that the control will limit what the user can select; this does not hold true. If you think about it, selection ranges seem rather odd and of limited if any use.
• The message TBM_GETCHANNELRECT returns the rectangle that the channel rectangle will be drawn into. If the control is Vertical (TBS_VERT), then the rectangle returned is screwed up and is flipped all around. The left/top and bottom/right values need flipped to be correct. The companion TBM_GETTHUMBRECT message returns the correct rectangle no matter the orientation.

Tree Controls
The tree control is a very interesting item in Windows - almost everything you do uses it. However, if you're trying to extended it beyond what you want it to do, you're going to be beating your head into the way. Also, we've uncovered some interesting features.

• Did you know that you can pass the HTREEITEM from another tree control into any tree control? If you actually take some time and mess around with the memory blocks and handles that the HTREEITEM points to, you'll realize that these items are a two-way double-linked list (ie: parent and child pointer, previous and next). There is no pointer back to the tree that owns it! This means you can make a fake CTreeCtrl that has no items in it and drive all of the htreeitems through it. Why would you want to do this? It opens up some interesting Windows messing around at the very least, and you could - in theory - have two tree controls that use the same visual list of data. May be of little or no use, of course!

--

Updated: Thursday, Sep 18, 2008 Contents copyright © 1999-2003 by NOPcode.com and its subsidiaries. Reproduction in part or in whole prohibited unless explicitly granted. All information and products, be it documentation, essays, source code, programs, or installs, are provided "as-is" and neither the author nor NOPcode.com will be held responsible for any resulting damages, either physical or mental. No warranty is expressed nor implied. All rights reserved. All trademarks used are property of their respected companies. For further information contact .