add resize documentation as per STR3433

add resize chapter to documentation, plus images,
based on Article #415: How does resizing work?
https://www.fltk.org/articles.php?L415

see also https://www.fltk.org/str.php?L3433

1 files changed, 216 insertions, 0 deletions

diff --git a/documentation/src/resize.dox b/documentation/src/resize.dox
new file mode 100644
index 000000000..5eb5a23e0
--- /dev/null
+++ b/documentation/src/resize.dox
@@ -0,0 +1,216 @@
+/**
+
+ \page resize How does resizing work?
+
+This chapter describes the basic mechanism behind the creation
+of resizable user interface elements in FLTK.
+
+FLTK uses a simple, but very versatile system to resize even the
+most complex dialogs and interfaces.
+The resizing is implemented within the Fl_Group widget, and the exact
+resizing behavior of that group is determined by its
+\link Fl_Group::resizable() resizable() \endlink attribute.
+
+
+\section resize_disabled Resizing can be disabled
+
+\code
+  Summary:
+    group = new Fl_Group(xg, yg, wg, hg, "No Resizing");
+    child1 = new Fl_Box(xb, yb, wb, hb, "B"); // or other widget type
+    . . .
+    group->resizable(0); // no resizing
+    group->end()
+\endcode
+
+The \p resizable may be set to zero,
+which means that the group will not resize.
+Note that this is the default behavior for Fl_Window and Fl_Pack
+derived widgets, and therefore the programmer must explicitly set
+the window's \p resizable attribute if they want to allow the
+window to be resized.
+
+
+\section resize_simple Resizing can be simple
+
+\code
+  Summary:
+    group = new Fl_Group(xg, yg, wg, hg, "Simple Resizing");
+    child1 = new Fl_Box(xb, yb, wb, hb, "B"); // or other widget type
+    . . .
+    group->resizable(group); // simple proportional resizing
+    group->end()
+\endcode
+
+The \p resizable may be set to the group itself,
+which means that all widgets within the group will resize
+as the group itself is resized.
+This is the default behavior for Fl_Group widgets,
+and is shown in the diagram below.
+
+If the group is stretched horizontally, the widths of
+the widgets within the group are adjusted proportionally.
+The same is true for vertical resizing.
+
+\image html resize-example1.png "Figure 6.1: Proportional resizing example"
+\image latex resize-example1.png "Proportional resizing example" width=12cm
+
+
+\section resize_complex Resizing can be complex
+
+\code
+  Summary:
+    group = new Fl_Group(xg, yg, wg, hg, "Complex Resizing");
+    child1 = new Fl_Box(xb, yb, wb, hb, "B"); // or other widget type
+    . . .
+    group->resizable(child1); // complex resizing
+    group->end()
+\endcode
+
+It is when the group's \p resizable attribute is set to one of the
+group's child widgets, that things become really interesting.
+
+In the diagram below, imagine vertical lines extending from the
+left and right sides of the yellow widget marked "resizable",
+and horizontal lines extending from the top and bottom sides.
+Exactly which widgets resize, and by how much, is determined
+by which ones lie completely or partially within this cross.
+
+The widgets marked B, C, J, K and M clearly lie completely or
+partially within the vertical part of the cross; the widgets
+marked E, F, G, H and N lie completely or partially within the
+horizontal part of the cross; and the widgets marked A, D, I
+and L do not overlap with the cross at all.
+The resizing behavior is as follows:
+
+\li the width and height of the \p resizable widget increase
+    to match the change in the width and height of the group
+    widget as it is stretched;
+
+\li the widths of those widgets that overlap with the vertical
+    part of the cross increase proportionally as the width of the
+    group widget increases, but their heights remain unchanged,
+    i.e. the widgets marked B, C, J, K and M;
+
+\li the heights of those widgets that overlap with the horizontal
+    part of the cross increase proportionally as the height of
+    the group widget increases, but their widths remain unchanged,
+    i.e. the widgets marked E, F, G, H and N;
+
+\li the widths and heights of the remaining widgets stay the same,
+    i.e. the widgets marked A, D, I and L stay the same size.
+
+\image html resize-example2.png "Figure 6.2: Complex resizing example"
+\image latex resize-example2.png "Complex resizing example" width=12cm
+
+
+\section resize_practical Practical examples
+
+Why is this so powerful, you may ask.
+Well, every widget group can have a completely independent resizing
+strategy.
+By replacing one or more of the group's "normal" child widgets with
+another group widget where all of the above rules can be applied again,
+it is possible to create a hierarchy of group widgets with very complex
+layouts and resizing behavior.
+
+Consider a simple dialog box, consisting of an icon box and a message
+area on the top and a button at the bottom right: which widget should
+be the \p resizable one?
+
+Setting the \p resizable to be the icon box won't give us what we want:
+
+\image html resize-example3a.png "Figure 6.3: Resizing dialog example (a)"
+\image latex resize-example3a.png "Resizing dialog example (a)" width=12cm
+
+The message text area would be the logical choice so that the user
+can expand the dialog to see if there is more of an explanation below
+the short error message. This results in the behaviour shown in the
+diagram below.
+
+\image html resize-example3b.png "Figure 6.4: Resizing dialog example (b)"
+\image latex resize-example3b.png "Resizing dialog example (b)" width=12cm
+
+The result is close to what we want, but not quite:
+the text area will fully resize,
+the "!" icon box will resize vertically but not horizontally,
+which we can live with,
+but the "Darn!" button will - wait a minute - resize horizontally?
+
+That's ugly. How do we stop that from happening?
+Simple: put it in its own group and set the \p resizable to
+an invisible box widget, as shown in the diagram below.
+
+\image html resize-example3c.png "Figure 6.5: Resizing dialog example (c)"
+\image latex resize-example3c.png "Resizing dialog example (c)" width=12cm
+
+Now the invisible box, shown as "R", takes all of the
+horizontal resizing and the "Darn!" box will stay as it is.
+Here's the skeleton code:
+
+\code
+dialog = new Fl_Window(300, 100);
+  icon = new Fl_Box(0, 0, 50, 50, "!");
+  text = new Fl_Box(50, 0, 250, 40, "Out of Memory Error");
+  btns = new Fl_Group(50, 50, 250, 50); // parent group
+  darn = new Fl_Button(200, 50, 100, 50, "Darn!");
+     R = new Fl_Box(50, 50, 150, 50);   // "invisible" box "R"
+     R->hide();                         // make sure it's invisible
+  btns->resizable(R);                   // make "R" parent group resizable
+  btns->end();
+dialog->resizable(text);
+dialog->end();
+\endcode
+
+Imagine instead that you have a group that has a button, an input field,
+another button and a second input field, all next to each other, and
+you want the input fields to resize equally, but not the buttons.
+How could you achieve this?
+
+Setting either of the input fields to be the \p resizable leaves the
+other one fixed, as shown below:
+
+\image html resize-example4a.png "Figure 6.6: Resizing input fields example (a)"
+\image latex resize-example4a.png "Resizing input fields example (b)" width=12cm
+
+The answer is to leave the \p resizable of the group set to itself,
+and to create two equal size subgroups, each of which will resize
+equally. Add a button and input field to each subgroup, and set
+each subgroup's \p resizable to the input field, as shown below.
+Tada!
+
+\image html resize-example4b.png "Figure 6.7: Resizing input fields example (b)"
+\image latex resize-example4b.png "Resizing inut fields example (b)" width=12cm
+
+In FLTK it is possible to solve almost any layout and resizing
+problem by introducing an invisible box into a group, or an extra
+group into the widget hierarchy.
+It might take some thought to achieve exactly what you want and
+sometimes it is necessary to introduce parallel hierarchies in
+order to get widgets in different groups to resize together.
+
+
+\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="editor.html">
+    Designing a Simple Text Editor
+    [Next]
+    </a>
+  </td>
+</tr>
+</table>
+\endhtmlonly
+
+*/