Apply Guichan's changes from ac25684370f72e5e204bd994fd736e630fb8425a…

… (Sept 15th 2008)

Documentation of Widget::getChildrenArea has been enhanced.

TODO

@@ -1,4 +1,4 @@
-* Continue rebasing from ac25684370f72e5e204bd994fd736e630fb8425a
+* Continue rebasing from 8075bee1c45ba7221ebdc127d0413628591622c6
 * Add a focus listener interface.
 * Make focus apply synchronously.
 * Graphics and input objects for DirectX.

include/guisan/widget.hpp

@@ -861,9 +861,23 @@ namespace gcn
         virtual const std::list<FocusListener*>& _getFocusListeners();
 
         /**
-         * Gets the area of the widget that the widget's children occupy.
-         *
-         * @return The area of the widget that the widget's children occupy.
+         * Gets the area of the widget occupied by the widget's children.
+         * By default this method returns an empty rectangle as not all
+         * widgets are containers. If you want to make a container this
+         * method should return the area where the children resides. This
+         * method is used when drawing children of a widget when computing
+         * clip rectangles for the children.
+         *
+         * An example of a widget that overloads this method is ScrollArea.
+         * A ScrollArea has a view of its contant and that view is the
+         * children area. The size of a ScrollArea's children area might
+         * vary depending on if the scroll bars of the ScrollArea is shown
+         * or not.
+         *
+         * @return The area of the widget occupied by the widget's children.
+         * @see BasicContainer
+         * @see BasicContainer::getChildrenArea
+         * @see BasicContainer::drawChildren
          * @since 0.1.0
          */
         virtual Rectangle getChildrenArea();