Insights from the Xlib Programming Manual
Virtual Focus Crossing and the detail Member
We will now embark on specifying the types of events sent to each window and the detail member in each event, depending on the relative position in the hierarchy of the origin window (old focus), destination window (new focus), and the pointer window (window containing pointer at time of focus change). Don't even try to figure this out unless you have to.
At least these guys are honest, but how about defining API that is simple enough that it doesn't need to come with a warning?