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>

4 files changed, 195 insertions, 0 deletions

diff --git a/test/.gitignore b/test/.gitignore
index 53dc8498a..eb25c06d8 100644
--- a/test/.gitignore
+++ b/test/.gitignore
@@ -33,6 +33,7 @@ clipboard
 clock
 colbrowser
 color_chooser
+coordinates
 cube
 CubeView
 CubeViewUI.cxx
@@ -133,6 +134,7 @@ valuators
 valuators.cxx
 valuators.h
 windowfocus
+wizard
 
 # macOS binary files
 
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index 13a5f76f4..9169fc776 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -76,6 +76,7 @@ CREATE_EXAMPLE (clipboard clipboard.cxx "fltk_images;fltk")
 CREATE_EXAMPLE (clock clock.cxx fltk ANDROID_OK)
 CREATE_EXAMPLE (colbrowser colbrowser.cxx fltk)
 CREATE_EXAMPLE (color_chooser color_chooser.cxx fltk ANDROID_OK)
+CREATE_EXAMPLE (coordinates coordinates.cxx fltk)
 CREATE_EXAMPLE (cursor cursor.cxx fltk ANDROID_OK)
 CREATE_EXAMPLE (curve curve.cxx fltk ANDROID_OK)
 CREATE_EXAMPLE (demo demo.cxx fltk)
@@ -146,6 +147,7 @@ CREATE_EXAMPLE (utf8 utf8.cxx fltk)
 CREATE_EXAMPLE (valuators valuators.fl fltk)
 CREATE_EXAMPLE (unittests unittests.cxx fltk)
 CREATE_EXAMPLE (windowfocus windowfocus.cxx fltk)
+CREATE_EXAMPLE (wizard wizard.cxx fltk)
 
 # create additional test programs (used by developers for testing)
 if (extra_tests)
diff --git a/test/coordinates.cxx b/test/coordinates.cxx
new file mode 100644
index 000000000..d888b7d46
--- /dev/null
+++ b/test/coordinates.cxx
@@ -0,0 +1,125 @@
+//
+// Coordinate demonstration program for the Fast Light Tool Kit (FLTK).
+//
+// Copyright 1998-2021 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_Box.H>
+#include <FL/Fl_Window.H>
+#include <stdio.h>
+
+class Box : public Fl_Box {
+public:
+  Box(int X, int Y, int W, int H, Fl_Color C, const char* T)
+  : Fl_Box(X, Y, W, H, T) {
+    align(FL_ALIGN_INSIDE | FL_ALIGN_CENTER);
+    box(FL_DOWN_BOX);
+    labelcolor(C);
+    labelsize(11);
+  }
+};
+
+class Title : public Fl_Box {
+public:
+  Title(int X, int Y, int W, int H, Fl_Color C, const char* T)
+  : Fl_Box(X, Y, W, H, T) {
+    align(FL_ALIGN_INSIDE | FL_ALIGN_CENTER | FL_ALIGN_TOP);
+    box(FL_NO_BOX);
+    labelcolor(C);
+    labelsize(12);
+  }
+};
+
+class MainWindow : public Fl_Window {
+public:
+  MainWindow(int X, int Y, const char* T)
+  : Fl_Window(X, Y, T) {
+
+    Fl_Window* tl_window = new Fl_Window(0, 0, 250, 100);
+    tl_window->box(FL_ENGRAVED_BOX);
+    Title* tl_title = new Title(10, 10, 230, 40, FL_RED,
+      "Fl_Window TL(0, 0, 250, 100)\nx, y relative to main window");
+    Box* tl_box = new Box(25, 50, 200, 40, FL_RED,
+      "Fl_Box tl(25, 50, 200, 40)\nx, y relative to TL window");
+    tl_window->end();
+
+    Fl_Window* br_window = new Fl_Window(250, 100, 250, 100);
+    br_window->box(FL_ENGRAVED_BOX);
+    Title* br_title = new Title(10, 10, 230, 40, FL_MAGENTA,
+      "Fl_Window BR(250, 100, 250, 100)\nx, y relative to main window");
+    Box* br_box = new Box(25, 50, 200, 40, FL_MAGENTA,
+      "Fl_Box br(25, 50, 200, 40)\nx, y relative to BR window");
+    br_window->end();
+
+    Fl_Group* tr_group = new Fl_Group(250, 0, 250, 100);
+    tr_group->box(FL_ENGRAVED_BOX);
+    Title* tr_title = new Title(260, 10, 230, 40, FL_BLUE,
+      "Fl_Group TR(250, 0, 250, 100)\nx, y relative to main window");
+    Box* tr_box = new Box(275, 50, 200, 40, FL_BLUE,
+      "Fl_Box tr(275, 50, 200, 40)\nx, y relative to main window");
+    tr_group->end();
+  
+    Fl_Group* bl_group = new Fl_Group(0, 100, 250, 100);
+    bl_group->box(FL_ENGRAVED_BOX);
+    Title* bl_title = new Title(10, 110, 230, 40, FL_BLACK,
+      "Fl_Group BL(0, 100, 250, 100)\nx, y relative to main window");
+    Box* bl_box = new Box(25, 150, 200, 40, FL_BLACK,
+      "Fl_Box bl(25, 150, 200, 40)\nx, y relative to main window");
+    bl_group->end();
+  
+    // member variable
+    message_box = new Fl_Box(0, 201, 500, 30);
+    message_box->align(FL_ALIGN_INSIDE | FL_ALIGN_CENTER);
+    message_box->box(FL_ENGRAVED_BOX);
+    message_box->labelfont(FL_COURIER);
+    message_box->labelsize(12);
+
+    end();
+  }
+
+protected:
+  int handle(int event) {
+    static char buffer[128];
+    static const char* fmt = "Mouse position relative to main window: %3d,%3d";
+    int result = Fl_Window::handle(event);
+    switch (event) {
+      case FL_ENTER:
+      case FL_LEAVE:
+        result = 1;
+        message_box->copy_label("");
+        break;
+      case FL_MOVE:
+      case FL_DRAG:
+        result = 1;
+        if (0 < Fl::event_x() && Fl::event_x() < w() &&
+            0 < Fl::event_y() && Fl::event_y() < h()) {
+          snprintf(buffer, 128-1, fmt, Fl::event_x(), Fl::event_y());
+          message_box->copy_label(buffer);
+        } else message_box->copy_label("");
+        break;
+      default:
+        break;
+    }
+    return result;
+  }
+
+private:
+  Fl_Box* message_box;
+};
+
+int main(int argc, char** argv) {
+  MainWindow window(500, 232, "FLTK Coordinate Systems");
+  window.show(argc, argv);
+  return Fl::run();
+}
diff --git a/test/wizard.cxx b/test/wizard.cxx
new file mode 100644
index 000000000..3baa051dc
--- /dev/null
+++ b/test/wizard.cxx
@@ -0,0 +1,66 @@
+#include <FL/Fl.H>
+#include <FL/Fl_Button.H>
+#include <FL/Fl_Window.H>
+#include <FL/Fl_Wizard.H>
+
+class Panel : public Fl_Group {
+public:
+  Panel(int X, int Y, int W, int H, Fl_Color C, const char* T)
+  : Fl_Group(X, Y,  W, H, T) {
+    align(FL_ALIGN_INSIDE | FL_ALIGN_CENTER);
+    box(FL_ENGRAVED_BOX);
+    labelcolor(C);
+    labelsize(20);
+    end();
+  }
+};
+
+class Wizard : public Fl_Wizard {
+public:
+  Wizard(int X, int Y, int W, int H, const char* T=0)
+  : Fl_Wizard(X, Y, W, H, T) {
+    p1 = new Panel(X, Y, W, H, FL_RED,     "Panel 1");
+    p2 = new Panel(X, Y, W, H, FL_MAGENTA, "Panel 2");
+    p3 = new Panel(X, Y, W, H, FL_BLUE,    "Panel 3");
+    value(p1);
+  }
+  void next_panel() {
+    Panel* p = (Panel*)value();
+    if (p == p3) value(p1); else next();
+  }
+  void prev_panel() {
+    Panel* p = (Panel*)value();
+    if (p == p1) value(p3); else prev();
+  }
+private:
+  Panel *p1, *p2, *p3;
+};
+
+void next_callback(Fl_Widget *widget, void *data) {
+  Wizard *pWizard = (Wizard*)data;
+  pWizard->next_panel();
+}
+
+void prev_callback(Fl_Widget *widget, void *data) {
+  Wizard *pWizard = (Wizard*)data;
+  pWizard->prev_panel();
+}
+
+int main(int argc, char** argv) {
+   Fl_Window window(300, 165, "Fl_Wizard test");
+   Wizard wizard(5, 5, 290, 100);
+   wizard.end();
+   Fl_Group buttons(5, 110, 290, 50);
+   buttons.box(FL_ENGRAVED_BOX);
+   Fl_Button prev_button( 15, 120, 110, 30, "@< Prev Panel");
+   prev_button.callback(prev_callback, (void*)&wizard);
+   prev_button.align(FL_ALIGN_INSIDE | FL_ALIGN_CENTER | FL_ALIGN_LEFT);
+   Fl_Button next_button(175, 120, 110, 30, "Next Panel @>");
+   next_button.align(FL_ALIGN_INSIDE | FL_ALIGN_CENTER | FL_ALIGN_RIGHT);
+   next_button.callback(next_callback, (void*)&wizard);
+   buttons.end();
+   window.end();
+   window.show(argc, argv);
+   return Fl::run();
+}
+