Update docs and screenshot for fl_line_style() (#1016)

As a follow-up to the discussion I used the posted screenshot demo
(thanks to Greg), redesigned it using Fl_Grid, and added it as a
new test program, including Makefiles and CMakeLists.txt.

New file: test/line_style_docs.cxx to create screenshot. Note that the
old test/line_style.cxx is not obsolete, it can be used to test the
line styles interactively.

Docs have been updated in both chapter "Drawing Things" and the
function description.

Also added the new demo to test/demo.menu under "Images for Manual...".

7 files changed, 144 insertions, 18 deletions

diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index cc23b28e9..99fe1045f 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -224,7 +224,7 @@ inline void fl_point(int x, int y) {
   using \c fl_line_style(0).
 
   \image html  fl_line_style.png "fl_line_style() styles"
-  \image latex fl_line_style.png "fl_line_style() styles" width=4cm
+  \image latex fl_line_style.png "fl_line_style() styles" width=12cm
 
   \param[in] style A bitmask which is a bitwise-OR of \ref LineStyles "Line Styles",
     a cap style, and a join style. If you don't specify a dash type you
@@ -256,7 +256,7 @@ inline void fl_line_style(int style, int width = 0, char *dashes = 0) {
 /// \anchor LineStyles
 ///
 ///  \image html  fl_line_style.png "fl_line_style() styles"
-///  \image latex fl_line_style.png "fl_line_style() styles" width=4cm
+///  \image latex fl_line_style.png "fl_line_style() styles" width=12cm
 ///
 enum {
   FL_SOLID      = 0,      ///< line style: solid line
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index 140d73cee..809f9751b 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -433,23 +433,16 @@ Please see the documentation for details.
 
 \subsection drawing_lines Line Dashes and Thickness
 
-FLTK supports drawing of lines with different styles and
-widths. Full functionality is not available under Windows 95, 98,
-and Me due to the reduced drawing functionality these operating
-systems provide.
+FLTK supports drawing of lines with different styles and widths.
 
-void fl_line_style(int style, int width, char* dashes)
+  void fl_line_style(int style, int width, char* dashes)
 
-\par
-Set how to draw lines (the "pen").  If you change this it is your
-responsibility to set it back to the default with
-\p fl_line_style(0).
+  \image html  fl_line_style.png "fl_line_style() styles"
+  \image latex fl_line_style.png "fl_line_style() styles" width=12cm
 
 \par
-\b Note:
-Because of how line styles are implemented on Windows systems, you \e must
-set the line style \e after setting the drawing color. If you set the
-color after the line style you will lose the line style settings!
+Set how to draw lines (the "pen").  If you change this it is your
+responsibility to set it back to the default with \p fl_line_style(0).
 
 \par
 \p style is a bitmask which is a bitwise-OR of the following
@@ -483,10 +476,18 @@ terminated with a zero-length entry. A \p NULL pointer or a zero-length
 array results in a solid line. Odd array sizes are not supported and
 result in undefined behavior.
 
+<!--
 \par
-\b Note:
-The dashes array does not work under Windows 95, 98, or Me, since those
-operating systems do not support complex line styles.
+\b Notes:
+-->
+\note
+- Full functionality is not available under Windows 95, 98, and Me due to
+  the reduced drawing functionality these operating systems provide.
+- Because of how line styles are implemented on Windows systems, you \e must
+  set the line style \e after setting the drawing color. If you set the
+  color after the line style you will lose the line style settings!
+- The dashes array does not work under Windows 95, 98, or Me, since those
+  operating systems do not support complex line styles.
 
 
 \subsection drawing_fast Drawing Fast Shapes
diff --git a/documentation/src/fl_line_style.png b/documentation/src/fl_line_style.png
index 55683801e..2e0b29cdb 100644
--- a/documentation/src/fl_line_style.png
+++ b/documentation/src/fl_line_style.png
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index 692730db1..a92d700a3 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -129,6 +129,7 @@ fl_create_example(input_choice input_choice.cxx fltk::fltk)
 fl_create_example(keyboard "keyboard.cxx;keyboard_ui.fl" fltk::fltk)
 fl_create_example(label label.cxx fltk::fltk)
 fl_create_example(line_style line_style.cxx fltk::fltk)
+fl_create_example(line_style_docs line_style_docs.cxx fltk::fltk)
 fl_create_example(list_visuals list_visuals.cxx fltk::fltk)
 fl_create_example(mandelbrot "mandelbrot_ui.fl;mandelbrot.cxx" fltk::fltk)
 fl_create_example(menubar menubar.cxx fltk::fltk)
diff --git a/test/Makefile b/test/Makefile
index 8145134af..c6401b262 100644
--- a/test/Makefile
+++ b/test/Makefile
@@ -91,6 +91,7 @@ CPPFILES =\
 	keyboard.cxx \
 	label.cxx \
 	line_style.cxx \
+	line_style_docs.cxx \
 	list_visuals.cxx \
 	mandelbrot.cxx \
 	menubar.cxx \
@@ -180,6 +181,7 @@ ALL =	\
 	input_choice$(EXEEXT) \
 	label$(EXEEXT) \
 	line_style$(EXEEXT) \
+	line_style_docs$(EXEEXT) \
 	list_visuals$(EXEEXT) \
 	menubar$(EXEEXT) \
 	message$(EXEEXT) \
@@ -494,6 +496,8 @@ label$(EXEEXT): label.o
 
 line_style$(EXEEXT): line_style.o
 
+line_style_docs$(EXEEXT): line_style_docs.o
+
 list_visuals$(EXEEXT): list_visuals.o
 
 mandelbrot$(EXEEXT): mandelbrot_ui.o mandelbrot.o
diff --git a/test/demo.menu b/test/demo.menu
index e608f54e8..2869c6cf9 100644
--- a/test/demo.menu
+++ b/test/demo.menu
@@ -103,6 +103,7 @@
 	@i:clock:clock
 	@i:popups:message
 	@i:boxtypes:boxtype
+	@i:line styles:line_style_docs
 	@i:Resize Examples\n...:@ir
 		@ir:Example\n1:resize-example1
 		@ir:Example\n2:resize-example2
diff --git a/test/line_style_docs.cxx b/test/line_style_docs.cxx
new file mode 100644
index 000000000..650918474
--- /dev/null
+++ b/test/line_style_docs.cxx
@@ -0,0 +1,119 @@
+//
+// Line style image (docs) for the Fast Light Tool Kit (FLTK).
+//
+// Copyright 2024 by Bill Spitzak and others.
+//
+// This library is free software. Distribution and use rights are outlined in
+// the file "COPYING" which should have been included with this file.  If this
+// file is missing or damaged, see the license at:
+//
+//     https://www.fltk.org/COPYING.php
+//
+// Please see the following page on how to report bugs and issues:
+//
+//     https://www.fltk.org/bugs.php
+//
+
+#include <FL/Fl.H>
+#include <FL/Fl_Double_Window.H>
+#include <FL/Fl_Grid.H>
+#include <FL/Fl_Box.H>
+#include <FL/fl_draw.H>
+
+// constants
+
+static const int len = 35;          // length of line segments
+static const int sep = 15;          // separation between items
+static const int width[] = {0, 4};  // line widths (thin + thick)
+
+// This class draws a box with one line style inside an Fl_Grid widget.
+// Row and column parameters are used to position the box inside the grid.
+
+class StyleBox : public Fl_Box {
+  int style;              // line style
+public:
+  StyleBox(int S, int row, int col) // style, row, column
+    : Fl_Box(0, 0, 0, 0) {
+    box(FL_FLAT_BOX);
+    color(FL_WHITE);
+    style = S;
+    Fl_Grid *grid = (Fl_Grid *)parent();
+    grid->widget(this, row, col, FL_GRID_FILL);
+  }
+  const char *style_str(int style) {
+    switch(style) {
+      case FL_SOLID       : return "FL_SOLID"      ;
+      case FL_DASH        : return "FL_DASH"       ;
+      case FL_DOT         : return "FL_DOT"        ;
+      case FL_DASHDOT     : return "FL_DASHDOT"    ;
+      case FL_DASHDOTDOT  : return "FL_DASHDOTDOT" ;
+      case FL_CAP_FLAT    : return "FL_CAP_FLAT"   ;
+      case FL_CAP_ROUND   : return "FL_CAP_ROUND"  ;
+      case FL_CAP_SQUARE  : return "FL_CAP_SQUARE" ;
+      case FL_JOIN_MITER  : return "FL_JOIN_MITER" ;
+      case FL_JOIN_ROUND  : return "FL_JOIN_ROUND" ;
+      case FL_JOIN_BEVEL  : return "FL_JOIN_BEVEL" ;
+      default             : return "(?)";
+    }
+  }
+  void draw() FL_OVERRIDE {
+    int X = x() + sep / 2;
+    int Y = y() + (h() - len) / 2;
+    draw_box();
+    fl_font(FL_HELVETICA, 12);
+    fl_color(FL_BLACK);
+    // draw the text
+    fl_draw(style_str(style), X, y() + h()/2 + fl_height()/2 - 2);
+    X += 110;
+    for (int i = 0; i < 2; i++, X += len + sep) { // thin + thick lines
+      fl_line_style(style, width[i]);
+      // ___
+      //    |
+      //    |
+      fl_line(X, Y, X + len, Y, X + len, Y + len);
+      X += len + sep;
+      // ___
+      //   /
+      //  /
+      fl_line(X, Y, X + len, Y, X, Y + len);
+    }
+    fl_line_style(FL_SOLID, 0); // restore to default
+  }
+};
+
+int main(int argc, char **argv) {
+  Fl_Double_Window win(660, 340, "fl_line_style()");
+  win.color(FL_WHITE);
+  Fl_Grid grid(4, 4, win.w() - 8, win.h() - 8);
+  grid.box(FL_FLAT_BOX);
+  grid.color(0xd0d0d000);   // margins and gaps
+  grid.layout(6, 2, 4, 4);  // 6 rows, 2 columns
+
+  // first column
+  StyleBox sb00(FL_SOLID,      0, 0);
+  StyleBox sb01(FL_DASH,       1, 0);
+  StyleBox sb02(FL_DOT,        2, 0);
+  StyleBox sb03(FL_DASHDOT,    3, 0);
+  StyleBox sb04(FL_DASHDOTDOT, 4, 0);
+
+  // empty box in row 5
+  Fl_Box empty(0, 0, 0, 0);
+  empty.box(FL_FLAT_BOX);
+  empty.color(FL_WHITE);
+  grid.widget(&empty, 5, 0, FL_GRID_FILL);
+
+  // second column
+  StyleBox sb05(FL_CAP_FLAT,   0, 1);
+  StyleBox sb06(FL_CAP_ROUND,  1, 1);
+  StyleBox sb07(FL_CAP_SQUARE, 2, 1);
+  StyleBox sb08(FL_JOIN_MITER, 3, 1);
+  StyleBox sb09(FL_JOIN_ROUND, 4, 1);
+  StyleBox sb10(FL_JOIN_BEVEL, 5, 1);
+
+  grid.end();
+  win.end();
+  // win.resizable(win);
+  // win.size_range(win.w(), win.h()); // don't allow to shrink
+  win.show(argc, argv);
+  return Fl::run();
+}