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

documentation/Doxyfile.in

@@ -557,6 +557,7 @@ INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/preface.dox
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/intro.dox
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/basics.dox
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/common.dox
+INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/resize.dox
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/editor.dox
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/drawing.dox
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/events.dox

documentation/Makefile

@@ -29,6 +29,7 @@ HTMLFILES	= 	 \
                          $(SRC_DOCDIR)/intro.dox \
                          $(SRC_DOCDIR)/basics.dox \
                          $(SRC_DOCDIR)/common.dox \
+                         $(SRC_DOCDIR)/resize.dox \
                          $(SRC_DOCDIR)/editor.dox \
                          $(SRC_DOCDIR)/drawing.dox \
                          $(SRC_DOCDIR)/events.dox \

documentation/src/common.dox

@@ -23,7 +23,7 @@ FLTK provides many types of buttons:
 
 \li Fl_Round_Button - A button with a radio circle.
 
-\image html buttons.png "Figure 3-1: FLTK Button Widgets"
+\image html buttons.png "Figure 5.1: FLTK Button Widgets"
 \image latex buttons.png "FLTK Button Widgets" width=10cm
 
 All of these buttons just need the corresponding
@@ -110,7 +110,7 @@ strings. FLTK provides the following valuators:
 
 \li Fl_Value_Slider - A slider that shows the current value.
 
-\image html valuators.png "Figure 3-2: FLTK valuator widgets"
+\image html valuators.png "Figure 5.2: FLTK valuator widgets"
 \image latex valuators.png "FLTK valuator widgets" width=10cm
 
 The \p value() method gets and sets the current value
@@ -249,15 +249,15 @@ the nearest entry in the colormap.
 The type Fl_Boxtype stored and returned in Fl_Widget::box()
 is an enumeration defined in Enumerations.H.
 
-Figure 3-3 shows the standard box types included with FLTK.
+Figure 5.3 shows the standard box types included with FLTK.
 
-\image html boxtypes.png "Figure 3-3: FLTK box types"
+\image html boxtypes.png "Figure 5.3: FLTK box types"
 \image latex boxtypes.png "FLTK box types" width=12cm
 
 \p FL_NO_BOX means nothing is drawn at all, so whatever is
 already on the screen remains. The <tt>FL_..._FRAME</tt> types only
 draw their edges, leaving the interior unchanged. The blue color in
-Figure 3-3 is the area that is not drawn by the frame types.
+Figure 5.3 is the area that is not drawn by the frame types.
 
 \subsection common_custom_boxtypes Making Your Own Boxtypes
 
@@ -351,9 +351,9 @@ labeling of widgets.
 The \p label() method sets the string that is displayed
 for the label. Symbols can be included with the label string by
 escaping them using the "@" symbol - "@@" displays a single at
-sign. Figure 3-4 shows the available symbols.
+sign. Figure 5.4 shows the available symbols.
 
-\image html symbols.png "Figure 3-4: FLTK label symbols"
+\image html symbols.png "Figure 5.4: FLTK label symbols"
 \image latex symbols.png "FLTK label symbols" width=10cm
 
 <!-- NEED 2in -->
@@ -379,7 +379,7 @@ Symbols and text can be combined in a label, however the symbol must be at
 the beginning and/or at the end of the text. If the text spans multiple lines,
 the symbol or symbols will scale up to match the height of all the lines.
 
-\image html symbol-examples.png "Figure 3-5: FLTK symbols and text"
+\image html symbol-examples.png "Figure 5.5: FLTK symbols and text"
 \image latex symbol-examples.png "FLTK symbols and text" width=10cm
 
 <!-- NEED 2in -->
@@ -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="editor.html">
+    <a class="el" href="resize.html">
-    Designing a Simple Text Editor
+    How does resizing work?
     [Next]
     </a>
   </td>

documentation/src/drawing.dox

@@ -251,7 +251,7 @@ standard colors and color cube for the first 256 colors. All of
 these are named with symbols in
 \ref enumerations "<FL/Enumerations.H>". Example:
 
-\image html fltk-colormap.png "FLTK default colormap (Fl_Color 0x00 - 0xff)"
+\image html fltk-colormap.png "Figure 8.1: FLTK default colormap (Fl_Color 0x00 - 0xff)"
 \image latex fltk-colormap.png "FLTK default colormap (Fl_Color 0x00 - 0xff)" width=6cm
 
 Color values greater than 255 are treated as 24-bit RGB
@@ -511,7 +511,7 @@ box. The two angles are measured in degrees counter-clockwise from
 must be greater or equal to \p a1.
 
 \par
-\image html  fl_pie_arc_diagram.png "fl_pie() and fl_arc()"
+\image html  fl_pie_arc_diagram.png "Figure 8.1: fl_pie() and fl_arc()"
 \image latex fl_pie_arc_diagram.png "fl_pie() and fl_arc()" width=6cm
 
 \par
@@ -654,7 +654,7 @@ If \p end is less than \p start then it draws the arc in a clockwise
 direction.
 
 \par
-\image html  fl_arc_xyr_diagram.png "fl_arc(x,y,r,a1,a2)"
+\image html  fl_arc_xyr_diagram.png "Figure 8.3: fl_arc(x,y,r,a1,a2)"
 \image latex fl_arc_xyr_diagram.png "fl_arc(x,y,r,a1,a2)" width=6cm
 
 void fl_circle(double x, double y, double r)

documentation/src/editor.dox

@@ -143,7 +143,7 @@ Fl_Input widgets, the "replace all" and
 the "replace next " button is a
 Fl_Return_Button widget:
 
-\image html editor-replace.png "Figure 4-1: The search and replace dialog"
+\image html editor-replace.png "Figure 7.1: The search and replace dialog"
 \image latex editor-replace.png "The search and replace dialog" width=10cm
 
 \code
@@ -604,9 +604,9 @@ Congratulations, you've just built your own text editor!
 
 \section editor_final_product The Final Product
 
-The final editor window should look like the image in Figure 4-2.
+The final editor window should look like the image in Figure 7.2.
 
-\image html editor.png "Figure 4-2: The completed editor window"
+\image html editor.png "Figure 7.2: The completed editor window"
 \image latex editor.png "The completed editor window" width=12cm
 
 \section editor_advanced_features Advanced Features
@@ -897,9 +897,9 @@ style_parse(const char *text,
 <table summary="navigation bar" width="100%" border="0">
 <tr>
   <td width="45%" align="LEFT">
-    <a class="el" href="common.html">
+    <a class="el" href="resize.html">
     [Prev]
-    Common Widgets and Attributes
+    How does resizing work?
     </a>
   </td>
   <td width="10%" align="CENTER">

documentation/src/examples.dox

@@ -757,7 +757,7 @@ the display \b should look when running the example programs.
 The \c cairo_test demo program shows three shiny buttons drawn with Cairo
 in an Fl_Cairo_Window.
 
-  \image html cairo_test.png "Buttons drawn with Cairo"
+  \image html cairo_test.png "Figure 22.1: Buttons drawn with Cairo"
   \image latex cairo_test.png "Buttons drawn with Cairo" width=8cm
 
 
@@ -767,7 +767,7 @@ in an Fl_Cairo_Window.
 The \c icon program lets you set the program icon from an image (here
 an Fl_RGB_Image).
 
-  \image html icon.png "Green icon (Windows 10)"
+  \image html icon.png "Figure 22.2: Green icon (Windows 10)"
   \image latex icon.png "Green icon (Windows 10)" width=6cm
 
 
@@ -777,7 +777,7 @@ an Fl_RGB_Image).
 Select "drawing images" in the browser at the left side to see the
 image drawing example:
 
-  \image html unittest_images.png "Image Drawing"
+  \image html unittest_images.png "Figure 22.3: Image Drawing"
   \image latex unittest_images.png "Image Drawing" width=12cm
 
 
@@ -795,7 +795,9 @@ image drawing example:
     <a class="el" href="index.html">[Index]</a>
   </td>
   <td width="45%" align="RIGHT">
-    &nbsp;
+    <a class="el" href="faq.html">
+    Frequently Asked Questions
+    [Next]
     </a>
   </td>
 </tr>

documentation/src/faq.dox

@@ -143,5 +143,26 @@ void my_callback(Fl_Widget*, void*) {
 \endcode
 
 
+\htmlonly
+<hr>
+<table summary="navigation bar" width="100%" border="0">
+<tr>
+  <td width="45%" align="LEFT">
+    <a class="el" href="examples.html">
+    [Prev]
+    Example Source Code
+    </a>
+  </td>
+  <td width="10%" align="CENTER">
+    <a class="el" href="index.html">[Index]</a>
+  </td>
+  <td width="45%" align="RIGHT">
+    &nbsp;
+    </a>
+  </td>
+</tr>
+</table>
+\endhtmlonly
+
 */
 

documentation/src/fluid.dox

@@ -47,7 +47,7 @@ the <tt>.h</tt> file or they can
 \p \#include
 the <tt>.cxx</tt> file so it still appears to be a single source file.
 
- \image html  fluid-org.png "Figure 9-1: FLUID organization"
+ \image html  fluid-org.png "Figure 12.1: FLUID organization"
  \image latex fluid-org.png "FLUID organization" width=12cm
 
 Normally the FLUID file defines one or more functions or classes which
@@ -181,7 +181,7 @@ accomplish seemingly simple tasks with it. This tutorial will
 show you how to generate a complete user interface class with
 FLUID that is used for the CubeView program provided with FLTK.
 
-\image html cubeview.png "Figure 9-2: CubeView demo"
+\image html cubeview.png "Figure 12.2: CubeView demo"
 \image latex cubeview.png "CubeView demo" width=10cm
 
 The window is of class CubeViewUI, and is completely generated by FLUID,
@@ -407,7 +407,7 @@ menu item. Name the class "CubeViewUI" and leave the subclass blank.
 We do not need any inheritance for this window. You should see the
 new class declaration in the FLUID browser window.
 
-\image html  fluid1.png "Figure 9-3: FLUID file for CubeView"
+\image html  fluid1.png "Figure 12.3: FLUID file for CubeView"
 \image latex fluid1.png "FLUID file for CubeView" width=10cm
 
 \par Adding the Class Constructor
@@ -435,7 +435,7 @@ CubeViewUI.
 
 When you are finished you should have something like this:
 
-\image html fluid2.png "Figure 9-4: FLUID window containing CubeView demo"
+\image html fluid2.png "Figure 12.4: FLUID window containing CubeView demo"
 \image latex fluid2.png "FLUID window containing CubeView demo" width=10cm
 
 We will talk about the \p show() method that is highlighted
@@ -463,7 +463,7 @@ This \p \#include is important, as we have just included
 CubeView as a member of CubeViewUI, so any public CubeView methods are
 now available to CubeViewUI.
 
-\image html fluid3-cxx.png "Figure 9-5: CubeView methods"
+\image html fluid3-cxx.png "Figure 12.5: CubeView methods"
 \image latex fluid3-cxx.png "CubeView methods" width=10cm
 
 \par Defining the Callbacks
@@ -500,7 +500,7 @@ Make sure the top level CubeViewUI is selected and select
 not be adding any widgets to this method FLUID will assign it a return
 type of \p void.
 
-\image html fluid4.png "Figure 9-6: CubeView constructor"
+\image html fluid4.png "Figure 12.6: CubeView constructor"
 \image latex fluid4.png "CubeView constructor" width=10cm
 
 Once the new method has been added, highlight its name and select
@@ -762,7 +762,7 @@ button the code file will include the header file automatically.
 Under the "Internationalization" tab are the \ref fluid_i18n "internationalization"
 options, described later in this chapter.
 
-\image html fluid-edit-proj-settings.png "Figure 9-7: FLUID Project Settings Window"
+\image html fluid-edit-proj-settings.png "Figure 12.7: FLUID Project Settings Window"
 \image latex fluid-edit-proj-settings.png "FLUID Project Settings Window" width=10cm
 
 \par Edit/GUI Settings... (Shift+Alt+p)
@@ -770,7 +770,7 @@ options, described later in this chapter.
 \par
 Displays the GUI Settings panel, used to control the user interface settings.
 
-\image html fluid-edit-gui-settings.png "Figure 9-7a: FLUID GUI Settings Window"
+\image html fluid-edit-gui-settings.png "Figure 12.8: FLUID GUI Settings Window"
 \image latex fluid-edit-gui-settings.png "FLUID GUI Settings Window" width=10cm
 
 \par Edit/Global FLTK Settings... (Shift+Alt+g)
@@ -786,7 +786,7 @@ Tooltips provide descriptions of each option.
 At the lower-right, "User Settings" causes changes to only affect the current user,
 "System Settings" causes changes to be applied to all users on the current machine.
 
-\image html fluid-edit-global-fltk-settings.png "Figure 9-7b: FLUID Global Settings Window"
+\image html fluid-edit-global-fltk-settings.png "Figure 12.9: FLUID Global Settings Window"
 \image latex fluid-edit-global-fltk-settings.png "FLUID Global Settings Window" width=10cm
 
 \par New/Code/Function
@@ -875,7 +875,7 @@ This panel controls the grid that all widgets snap to when you move
 and resize them, and for the "snap" which is how far a widget has to be
 dragged from its original position to actually change.
 
-\image html fluid-layout-grid-and-size-settings.png "Figure 9-7c: FLUID Layout/Grid Settings Window"
+\image html fluid-layout-grid-and-size-settings.png "Figure 12.10: FLUID Layout/Grid Settings Window"
 \image latex fluid-layout-grid-and-size-settings.png "FLUID Layout/Grid Settings Window" width=10cm
 
 \par Shell/Execute Command... (Alt+x)
@@ -934,7 +934,7 @@ undone, however.
 
 <!-- NEW PAGE -->
 
-\image html fluid_widget_gui.png "Figure 9-8: The FLUID widget GUI attributes"
+\image html fluid_widget_gui.png "Figure 12.11: The FLUID widget GUI attributes"
 \image latex fluid_widget_gui.png "The FLUID widget GUI attributes" width=10cm
 
 \section fluid_widget_attributes GUI Attributes
@@ -1049,7 +1049,7 @@ as the class. This can change the icon or window decorations.
 On most (all?) window managers you will have to close the window
 and reopen it to see the effect.
 
-\image html fluid_widget_style.png "Figure 9-9: The FLUID widget Style attributes"
+\image html fluid_widget_style.png "Figure 12.12: The FLUID widget Style attributes"
 \image latex fluid_widget_style.png "The FLUID widget Style attributes" width=10cm
 
 \subsection fluid_style_attributes Style Attributes
@@ -1120,7 +1120,7 @@ when they have the focus.
 Some widgets display text, such as input fields, pull-down
 menus, and browsers.
 
-\image html fluid_widget_cxx.png "Figure 9-10: The FLUID widget C++ attributes"
+\image html fluid_widget_cxx.png "Figure 12.13: The FLUID widget C++ attributes"
 \image latex fluid_widget_cxx.png "The FLUID widget C++ attributes" width=10cm
 
 \subsection fluid_cpp_attributes C++ Attributes
@@ -1499,7 +1499,7 @@ fields will then appear to control the include file and
 function/macro name to use when retrieving the localized label
 strings.
 
- \image html fluid-gettext.png "Figure 9-11: Internationalization using GNU gettext"
+ \image html fluid-gettext.png "Figure 12.14: Internationalization using GNU gettext"
  \image latex fluid-gettext.png "Internationalization using GNU gettext" width=10cm
 
 The \b \#include
@@ -1524,7 +1524,7 @@ input fields will then appear to control the include file,
 catalog file, and set number for retrieving the localized label
 strings.
 
- \image html fluid-catgets.png "Figure 9-12: Internationalization using POSIX catgets"
+ \image html fluid-catgets.png "Figure 12.15: Internationalization using POSIX catgets"
  \image latex fluid-catgets.png "Internationalization using POSIX catgets" width=10cm
 
 The \b \#include

documentation/src/index.dox

@@ -43,6 +43,8 @@
         - \ref common_labels
         - \ref drawing_images
 
+    \subpage resize
+
     \subpage editor
 
     \subpage drawing

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
+
+*/