Rob Bradford authored Feb 26, 2013 and Matthias Clasen committed Mar 17, 2013

Update the documentation and users of this function to handle
the future case that that we have some internal decorations to the window and
useable allocation is thus smaller.

By having a separate out parameter there is no need to have an in/out function
and allows for greater robustness.

The current implementation simply returns the allocation provided.