(svn r16370) -Doc: Improvements to the nested widgets documentation, added explanation about computations, fixed typo in param description.

1 files changed, 35 insertions, 10 deletions

diff --git a/src/widget.cpp b/src/widget.cpp
index 6aff0679e..b64f0dddf 100644
--- a/src/widget.cpp
+++ b/src/widget.cpp
@@ -658,18 +658,43 @@ void Window::DrawSortButtonState(int widget, SortButtonState state) const
  * Hierarchical widgets, also known as nested widgets, are widgets stored in a tree. At the leafs of the tree are (mostly) the 'real' widgets
  * visible to the user. At higher levels, widgets get organized in container widgets, until all widgets of the window are merged.
  *
+ * \section nestedwidgetkinds Hierarchical widget kinds
  * A leaf widget is one of
- * - #NWidgetLeaf for widgets visible for the user, or
- * - #NWidgetSpacer for creating (flexible) empty space between widgets.
+ * <ul>
+ * <li> #NWidgetLeaf for widgets visible for the user, or
+ * <li> #NWidgetSpacer for creating (flexible) empty space between widgets.
+ * </ul>
+ * The purpose of a leaf widget is to provide interaction with the user by displaying settings, and/or allowing changing the settings.
  *
  * A container widget is one of
- * - #NWidgetHorizontal for organizing child widgets in a (horizontal) row. The row switches order depending on the language setting (thus supporting
- *   right-to-left languages),
- * - #NWidgetHorizontalLTR for organizing child widgets in a (horizontal) row, always in the same order. All childs below this container will also
- *   never swap order.
- * - #NWidgetVertical for organizing child widgets underneath each other.
- * - #NWidgetBackground for adding a background behind its child widget.
- * - #NWidgetStacked for stacking child widgets on top of each other.
+ * <ul>
+ * <li> #NWidgetHorizontal for organizing child widgets in a (horizontal) row. The row switches order depending on the language setting (thus supporting
+ *      right-to-left languages),
+ * <li> #NWidgetHorizontalLTR for organizing child widgets in a (horizontal) row, always in the same order. All childs below this container will also
+ *      never swap order.
+ * <li> #NWidgetVertical for organizing child widgets underneath each other.
+ * <li> #NWidgetBackground for adding a background behind its child widget.
+ * <li> #NWidgetStacked for stacking child widgets on top of each other.
+ * </ul>
+ * The purpose of a container widget is to structure its leafs and sub-containers to allow proper resizing.
+ *
+ * \section nestedwidgetscomputations Hierarchical widget computations
+ * The first 'computation' is the creation of the nested widgets tree by calling the constructors of the widgets listed above and calling \c Add() for every child,
+ * or by means of specifying the tree as a collection of nested widgets parts and instantiating the tree from the array.
+ *
+ * After the creation step,
+ * - The leafs have their own minimal size (\e min_x, \e min_y), filling (\e fill_x, \e fill_y), and resize steps (\e resize_x, \e resize_y).
+ * - Containers only know what their children are, \e fill_x, \e fill_y, \e resize_x, and \e resize_y are not initialized.
+ *
+ * Computations in the nested widgets take place as follows:
+ * <ol>
+ * <li> A bottom-up sweep by recursively calling NWidgetBase::SetupSmallestSize() to initialize the smallest size (\e smallest_x, \e smallest_y) and
+ *      to propagate filling and resize steps upwards to the root of the tree.
+ * <li> A top-down sweep by recursively calling NWidgetBase::AssignSizePosition() to make the smallest sizes consistent over the entire tree, and to assign
+ *      the top-left (\e pos_x, \e pos_y) position of each widget in the tree. This step uses \e fill_x and \e fill_y at each node in the tree to decide how to
+ *      fill each widget towards consistent sizes.
+ *      For generating a widget array, resize step sizes are made consistent.
+ * </ol>
  *
  * @see NestedWidgetParts
  */
@@ -715,7 +740,7 @@ NWidgetBase::NWidgetBase(WidgetType tp) : ZeroedMemoryAllocator()
  * @param widgets     Widget array to store the nested widgets in.
  * @param length      Length of the array.
  * @param left_moving Left edge of the widget may move due to resizing (right edge if \a rtl).
- * @param top_moving  Top edge of the widget may move due to reisizing.
+ * @param top_moving  Top edge of the widget may move due to resizing.
  * @param rtl         Adapt for right-to-left languages (position contents of horizontal containers backwards).
  *
  * @note When storing a nested widget, the function should check first that the type in the \a widgets array is #WWT_LAST.