Update documentation with Fl_Flex and Fl_Grid widgets

1 files changed, 99 insertions, 11 deletions

diff --git a/documentation/src/coordinates.dox b/documentation/src/coordinates.dox
index 5dff210e4..5fc22e797 100644
--- a/documentation/src/coordinates.dox
+++ b/documentation/src/coordinates.dox
@@ -7,7 +7,7 @@ positioning widgets manually, and some of the basics of FLTK
 layout widgets that are used to position widgets automatically.
 
 
-\section coordinates_coordinates The widget coordinate system
+\section coordinates_coordinates The Widget Coordinate System
 
 All widgets have constructors with \p x and \p y parameters to
 let the programmer specify the desired initial position of the
@@ -43,7 +43,7 @@ In other words, the widget hierarchy and positions can be summarized as:
 </pre>
 
 
-\section coordinate_layout Layout and container widgets
+\section coordinate_layout Layout and Container Widgets
 
 There are four main groups of widgets derived from Fl_Group for
 a range of different purposes.
@@ -58,7 +58,7 @@ new capability. These widgets are Fl_Scroll, Fl_Tabs and Fl_Wizard.
 
 The third group are layout managers that relocate and resize the
 child widgets added to them in order to satisfy a particular layout
-algorithm. These widgets are Fl_Pack and Fl_Tile.
+algorithm. These widgets are Fl_Flex, Fl_Grid, Fl_Pack, and Fl_Tile.
 
 The final group consists of Fl_Window and its derivatives.
 Their special capability is that they can be top-level application
@@ -70,8 +70,86 @@ the position of top-level windows, and the \p x and \p y
 position parameters may be treated as hints, or even ignored.
 The Fl_Window class has an extra constructor that omits them.
 
+Descriptions of layout and container widgets follow in alphabetical order.
 
-\subsection coordinates_pack The Fl_Pack layout widget
+
+\subsection coordinates_flex The Fl_Flex Layout Widget
+
+The Fl_Flex widget allows the layout of its direct children as a single row
+or column. If its type() is set to give the row or horizontal layout, the
+children are all resized to have the same height as the Fl_Flex and are
+moved next to each other. If set to give the column or vertical layout,
+the children are all resized to have the same width as the Fl_Flex and
+are then stacked below each other.
+
+Widget positions (x, y) need not be given by the user because widgets are
+positioned inside the Fl_Flex container in the order of its children.
+Widget sizes can be set to (0, 0) as in Fl_Pack since they are calculated
+by Fl_Flex.
+
+This is similar to Fl_Pack described below and Fl_Flex is designed to
+act as a drop-in replacement of Fl_Pack with some minor differences.
+
+Other than Fl_Pack the Fl_Flex widget does \b not resize itself but resizes
+its children to fill the entire space of the Fl_Flex container. Single
+children of Fl_Flex can be set to fixed sizes to inhibit this resizing
+behavior. In this case the remaining space is distributed to all
+non-fixed widgets.
+
+Fl_Flex widgets can be nested inside each other and with Fl_Grid in any
+combination.
+
+The name Fl_Flex was inspired by the CSS 'flex' container.
+
+\image html  Fl_Flex_simple.png "Simple Fl_Flex Layout"
+\image latex Fl_Flex_simple.png "Simple Fl_Flex Layout" width=8cm
+
+Fl_Flex was added in FLTK 1.4.0.
+
+
+\subsection coordinates_grid The Fl_Grid Layout Widget
+
+Fl_Grid is the most flexible layout container in FLTK 1.4. It is based
+on a flexible grid of \b cells that can be assigned one widget per cell
+which is the \e anchor of the widget. Widgets can span multiple rows
+and columns and the cells can constitute a sparse matrix. Widgets can be
+aligned inside their cells in several ways (left, right, top, bottom) and
+can stretch horizontally, vertically, or both, i.e. fill the entire cell.
+
+Widget positions (x, y) need not be given by the user because widgets are
+assigned to a particular grid cell by row and column number. Widget sizes
+can be given as their \b minimal sizes and will be resized appropriately
+depending on the free space.
+
+Optional margins around all cells inside the widget border and gaps between
+rows and cells make the layout even more flexible.
+
+The Fl_Grid widget should be designed with a grid (matrix) and its minimal
+size in mind. It is designed to \b enlarge cells and widgets in a flexible
+way when the Fl_Grid widget itself is created or resized.
+
+Additional free space inside the Fl_Grid container is distributed to widgets
+by considering minimal row heights, column widths, sizes of widgets, and
+row and column \e weights. These weights are used to distribute the free
+space proportionally according to the row and column weights.
+
+Fl_Grid widgets can be nested inside each other and with Fl_Flex and other
+subclasses of Fl_Group in any combination.
+
+\note We don't recommend to use Fl_Pack as child widgets although this
+  \b may work as well.
+
+The name Fl_Grid was inspired by the CSS 'grid' container but it has
+some properties in common with HTML \<table\> containers as well, for
+instance row and column spanning.
+
+\image html  Fl_Grid.png "Simple Fl_Grid Layout"
+\image latex Fl_Grid.png "Simple Fl_Grid Layout" width=8cm
+
+Fl_Grid was added in FLTK 1.4.0.
+
+
+\subsection coordinates_pack The Fl_Pack Layout Widget
 
 The Fl_Pack widget allows the layout of its direct children as a
 single row, or column.
@@ -80,9 +158,8 @@ the children are all resized to have the same height as the Fl_Pack
 and are moved next to each other.
 If set to give the column or vertical layout, the children are all
 resized to have the same width as the Fl_Pack and are then stacked
-below each other.
-The Fl_Pack then resizes itself to shrink-wrap itself around all
-of the children.
+below each other. The Fl_Pack then resizes itself to shrink-wrap itself
+around all of the children.
 
 Fl_Pack widgets are often used inside an Fl_Scroll, as shown in the
 diagram below, to avoid having to deal with tricky resize behavior
@@ -91,8 +168,19 @@ when used with nested widgets.
 \image html  pack.png "Fl_Pack test program screenshot"
 \image latex pack.png "Fl_Pack test program screenshot" width=8cm
 
+Since FLTK 1.4.0 Fl_Flex (described above) can in many cases be used as
+a drop-in replacement for Fl_Pack if this "shrink-wrap" behavior is not
+required. Note that the Fl_Pack layout algorithm can cause some issues
+because its widget size can change depending on its children and
+particularly because this is done late, i.e. during draw() and not
+as usual during resize of the window.
+
+\note We recommend that developers evaluate whether using Fl_Flex or Fl_Grid
+  instead of Fl_Pack can be a better solution with more predictable and
+  reliable resizing behavior of the overall program layout.
+
 
-\subsection coordinates_scroll The Fl_Scroll container widget
+\subsection coordinates_scroll The Fl_Scroll Container Widget
 
 The Fl_Scroll container widget can hold an assortment of widgets
 that may extend beyond its own width and height, in which case
@@ -103,7 +191,7 @@ so that you can scroll and view the entire contents.
 \image latex Fl_Scroll.png "Fl_Scroll container widget" width=4cm
 
 
-\subsection coordinates_tabs The Fl_Tabs container widget
+\subsection coordinates_tabs The Fl_Tabs Container Widget
 
 The Fl_Tabs widget provides a front-to-back stack of individual
 panels which usually contain Fl_Group widgets and their children.
@@ -115,7 +203,7 @@ is determined by the child widget's label and related attributes.
 \image latex tabs.png "Fl_Tabs container widget" width=8cm
 
 
-\subsection coordinates_tile The Fl_Tile layout widget
+\subsection coordinates_tile The Fl_Tile Layout Widget
 
 The Fl_Tile widget allows the user to resize one or more of its children
 by dragging on the border between adjacent child widgets.
@@ -132,7 +220,7 @@ For more information see the Fl_Tile widget manual page, and \ref resize.
 \image latex Fl_Tile.png "The Fl_Tile layout widget" width=4cm
 
 
-\subsection coordinates_wizard The Fl_Wizard container widget
+\subsection coordinates_wizard The Fl_Wizard Container Widget
 
 The Fl_Wizard widget derives from the Fl_Tabs class, but instead
 of having tabs that the user can click to select the corresponding