Documentation on widget coordinates and layout, plus new test programs (#304)

Add coordinates and layout section to user manual

add section to user manual to clarify the use of window-relative
coordinates in both Fl_Group and Fl_Window containers, and include
brief descriptions of current layout manager widgets in one place.

add test/coordinates.cxx, test/wizard.cxx and related screenshots
under documentation/src.

update CMakeLists.txt, Makefile and .gitignore for new files.

Co-authored-by: Albrecht Schlosser <albrechts.fltk@online.de>

8 files changed, 179 insertions, 6 deletions

diff --git a/documentation/src/common.dox b/documentation/src/common.dox
index 4950065a5..ca2613f32 100644
--- a/documentation/src/common.dox
+++ b/documentation/src/common.dox
@@ -640,8 +640,8 @@ combined with any modifiers like \p Shift , \p Alt , and \p Control.
     <a class="el" href="index.html">[Index]</a>
   </td>
   <td width="45%" align="RIGHT">
-    <a class="el" href="resize.html">
-    How does resizing work?
+    <a class="el" href="coordinates.html">
+    Coordinates and Layout Widgets
     [Next]
     </a>
   </td>
diff --git a/documentation/src/coordinates.dox b/documentation/src/coordinates.dox
new file mode 100644
index 000000000..ca996e64e
--- /dev/null
+++ b/documentation/src/coordinates.dox
@@ -0,0 +1,171 @@
+/**
+
+ \page coordinates Coordinates and Layout Widgets
+
+This chapter describes the coordinate systems that apply when
+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
+
+All widgets have constructors with \p x and \p y parameters to
+let the programmer specify the desired initial position of the
+top left corner during explicit manual layout within Fl_Window
+and Fl_Group container widgets.
+
+This position is always relative to the enclosing Fl_Window,
+which is usually, but not always, the top-level application
+window, or a free-floating pop-up dialog window.
+In some cases it could also be a subwindow embedded in a
+higher-level window, as shown in the figure below.
+
+\image html  coordinates.png "FLTK coordinate system"
+\image latex coordinates.png "FLTK coordinate system" width=6cm
+
+The positions of the TL and BR sub-windows and the TR and BL
+groups are all relative to the top-left corner of the main window.
+The positions of the boxes inside the TR and BL groups are also
+relative to the main window, but the boxes inside the TL and BR
+sub-windows are positioned relative to the enclosing sub-window.
+
+In other words, the widget hierarchy and positions can be summarized as:
+<pre>
+    Fl_Window main window
+      Fl_Window TL subwindow     # x, y relative to main window
+        Fl_Box  tl box           # x, y relative to TL subwindow
+      Fl_Window BR subwindow     # x, y relative to main window
+        Fl_Box  br box           # x, y relative to BR subwindow
+      Fl_Group  TR group         # x, y relative to main window
+        Fl_Box  tr box           # x, y relative to main window
+      Fl_Group  BL group         # x, y relative to main window
+        Fl_Box  bl box           # x, y relative to main window
+</pre>
+
+
+\section coordinate_layout Layout and container widgets
+
+There are four main groups of widgets derived from Fl_Group for
+a range of different purposes.
+
+The first group are composite widgets that each contain a fixed
+set of components that work together for a specific purpose,
+rather than layout widgets as such, and are not discussed here.
+
+The second group are basically containers offering the same manual
+layout features as Fl_Group, as described above, but which add one
+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.
+
+The final group consists of Fl_Window and its derivatives.
+Their special capability is that they can be top-level application
+windows and dialogs that interface with the operating system window
+manager, but can also be embedded within other windows and groups
+as shown in the example above.
+Note that the window manager may impose its own constraints on
+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.
+
+
+\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.
+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_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.
+
+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
+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
+
+
+\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
+horizontal and/or vertical scrollbars may appear automatically
+so that you can scroll and view the entire contents.
+
+\image html  Fl_Scroll.png "Fl_Scroll container widget"
+\image latex Fl_Scroll.png "Fl_Scroll container widget" width=4cm
+
+
+\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.
+The user can switch between panels by clicking on the small
+tabs that protrude from the panels. The appearance of each tab
+is determined by the child widget's label and related attributes.
+
+\image html  tabs.png "Fl_Tabs container widget"
+\image latex tabs.png "Fl_Tabs container widget" width=8cm
+
+
+\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.
+However, the programmer must first explicitly layout the child widgets
+so that their borders exactly fill the width and height of the Fl_Tile
+without having any gaps between them, or at the edges.
+Some care is needed when initially positioning the children and setting
+the resizable() widget within the Fl_Tile to prevent squeezing a child
+to have a zero width or height.
+For more information see the Fl_Tile widget manual page, and \ref resize.
+
+
+\image html  Fl_Tile.png "The Fl_Tile layout widget"
+\image latex Fl_Tile.png "The Fl_Tile layout widget" width=4cm
+
+
+\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
+panel, the programmer uses the prev(), next() or value() methods
+to show the appropriate panel.
+For example, the user might be able to click on "Next" and "Prev"
+navigation buttons or keys, as shown below.
+
+\image html  wizard.png "FL_Wizard container widget"
+\image latex wizard.png "FL_Wizard container widget" width=4cm
+
+
+\htmlonly
+<hr>
+<table summary="navigation bar" width="100%" border="0">
+<tr>
+  <td width="45%" align="LEFT">
+    <a class="el" href="common.html">
+    [Prev]
+    Common Widgets and Attributes
+    </a>
+  </td>
+  <td width="10%" align="CENTER">
+    <a class="el" href="index.html">[Index]</a>
+  </td>
+  <td width="45%" align="RIGHT">
+    <a class="el" href="resize.html">
+    How Does Resizing Work?
+    [Next]
+    </a>
+  </td>
+</tr>
+</table>
+\endhtmlonly
+
+*/
diff --git a/documentation/src/coordinates.png b/documentation/src/coordinates.png
new file mode 100644
index 000000000..d712474ef
--- /dev/null
+++ b/documentation/src/coordinates.png
diff --git a/documentation/src/editor.dox b/documentation/src/editor.dox
index 8a0eb3cd7..eaafe3aec 100644
--- a/documentation/src/editor.dox
+++ b/documentation/src/editor.dox
@@ -900,7 +900,7 @@ style_parse(const char *text,
   <td width="45%" align="LEFT">
     <a class="el" href="resize.html">
     [Prev]
-    How does resizing work?
+    How Does Resizing Work?
     </a>
   </td>
   <td width="10%" align="CENTER">
diff --git a/documentation/src/index.dox b/documentation/src/index.dox
index 6e3bb4f53..e50474cce 100644
--- a/documentation/src/index.dox
+++ b/documentation/src/index.dox
@@ -43,6 +43,8 @@
         - \ref common_labels
         - \ref drawing_images
 
+    \subpage coordinates
+
     \subpage resize
 
     \subpage editor
diff --git a/documentation/src/pack.png b/documentation/src/pack.png
new file mode 100644
index 000000000..df87e06ef
--- /dev/null
+++ b/documentation/src/pack.png
diff --git a/documentation/src/resize.dox b/documentation/src/resize.dox
index c3b30daf9..29f687997 100644
--- a/documentation/src/resize.dox
+++ b/documentation/src/resize.dox
@@ -1,6 +1,6 @@
 /**
 
- \page resize How does resizing work?
+ \page resize How Does Resizing Work?
 
 This chapter describes the basic mechanism behind the creation
 of resizable user interface elements in FLTK.
@@ -280,9 +280,9 @@ To summarize the key points of the new technique:
 <table summary="navigation bar" width="100%" border="0">
 <tr>
   <td width="45%" align="LEFT">
-    <a class="el" href="common.html">
+    <a class="el" href="coordinates.html">
     [Prev]
-    Common Widgets and Attributes
+    Coordinates and Layout Widgets
     </a>
   </td>
   <td width="10%" align="CENTER">
diff --git a/documentation/src/wizard.png b/documentation/src/wizard.png
new file mode 100644
index 000000000..4357648d0
--- /dev/null
+++ b/documentation/src/wizard.png