Add an option and the first program to create screenshots

This is the first step in creating additional programs for saving
screenshots for documentation purposes. These screenshots must be
saved in the documentation/images directory and checked into the
Git repository.

These programs allow developers to create new screenshots or change
existing ones. More screenshots may be created by programs in the
/test/ folder.

To-do: add more *new* screenshot programs, and if useful, move some
  existing programs from the `/test/` folder to `/screenshots/`,
  such as `test/resize-example*.cxx` and maybe more.

6 files changed, 221 insertions, 8 deletions

diff --git a/CMake/options.cmake b/CMake/options.cmake
index 063dc48b6..589550c73 100644
--- a/CMake/options.cmake
+++ b/CMake/options.cmake
@@ -458,18 +458,19 @@ option(FLTK_BUILD_SHARED_LIBS
 
 #######################################################################
 
-option(FLTK_OPTION_PRINT_SUPPORT      "allow print support"        ON)
-option(FLTK_OPTION_FILESYSTEM_SUPPORT "allow file system support"  ON)
+option(FLTK_OPTION_PRINT_SUPPORT      "allow print support"          ON)
+option(FLTK_OPTION_FILESYSTEM_SUPPORT "allow file system support"    ON)
 
-option(FLTK_BUILD_FORMS        "Build forms compatibility library" OFF)
-option(FLTK_BUILD_FLUID        "Build FLUID"                       ON)
-option(FLTK_BUILD_FLTK_OPTIONS "Build fltk-options"                ON)
-option(FLTK_BUILD_EXAMPLES     "Build example programs"            OFF)
+option(FLTK_BUILD_FORMS        "Build forms compatibility library"   OFF)
+option(FLTK_BUILD_FLUID        "Build FLUID"                         ON)
+option(FLTK_BUILD_FLTK_OPTIONS "Build fltk-options"                  ON)
+option(FLTK_BUILD_EXAMPLES     "Build example programs"              OFF)
+option(FLTK_BUILD_SCREENSHOTS  "Build screenshot programs for docs"  OFF)
 
 if(FLTK_IS_TOPLEVEL)
-  option(FLTK_BUILD_TEST       "Build test/demo programs"          ON)
+  option(FLTK_BUILD_TEST       "Build test/demo programs"            ON)
 else()
-  option(FLTK_BUILD_TEST       "Build test/demo programs"          OFF)
+  option(FLTK_BUILD_TEST       "Build test/demo programs"            OFF)
 endif()
 
 if(FLTK_BUILD_FORMS)
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 6da0edc94..75878202e 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -282,14 +282,24 @@ include(CMake/export.cmake)
 # options to build test/demo and example programs
 #######################################################################
 
+# general test programs for FLTK development
+
 if(FLTK_BUILD_TEST)
   add_subdirectory(test)
 endif(FLTK_BUILD_TEST)
 
+# example programs for FLTK users
+
 if(FLTK_BUILD_EXAMPLES)
   add_subdirectory(examples)
 endif(FLTK_BUILD_EXAMPLES)
 
+# screenshot programs for FLTK developers
+
+if(FLTK_BUILD_SCREENSHOTS)
+  add_subdirectory(screenshots)
+endif(FLTK_BUILD_SCREENSHOTS)
+
 #######################################################################
 # Create and install version config file 'FLTKConfigVersion.cmake'
 #######################################################################
diff --git a/README.CMake.txt b/README.CMake.txt
index 781ab4c49..77a404482 100644
--- a/README.CMake.txt
+++ b/README.CMake.txt
@@ -232,6 +232,11 @@ FLTK_BUILD_GL - default ON
     Build the OpenGL support library fltk_gl (fltk::gl) and enable OpenGL
     support in user programs using fltk_gl.
 
+FLTK_BUILD_SCREENSHOTS - default OFF
+    Build the programs in the "screenshots" directory for developers
+    who want to create or modify screenshots for documentation.
+    Please see 'screenshots/README.txt' for details and instructions.
+
 FLTK_BUILD_SHARED_LIBS - default OFF
     Normally FLTK is built as static libraries which makes more portable
     binaries. If you want to use shared libraries, setting this option ON
diff --git a/screenshots/CMakeLists.txt b/screenshots/CMakeLists.txt
new file mode 100644
index 000000000..31dad6434
--- /dev/null
+++ b/screenshots/CMakeLists.txt
@@ -0,0 +1,67 @@
+#
+# CMakeLists.txt to create screenshot programs for FLTK documentation
+#
+# Copyright 2026 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
+#
+
+########################################################################
+# Screenshot programs for FLTK documentation
+########################################################################
+
+# The programs in this subdirectory are intended to be used by
+# developers to create screenshots for our Doxygen documentation.
+# See README.txt for more info.
+
+# These programs are not "installed" on target systems, they are only
+# built in the FLTK build tree.
+
+########################################################################
+# Define a list of programs that will be built w/o extension.
+# All programs must use the 'scr_' prefix and the '.cxx' extension.
+# Define the names in the list below w/o prefix and extension.
+########################################################################
+
+set(NAMES
+    unicode      # Unicode text example
+    # add more programs here ...
+)
+
+########################################################################
+# Build a special CMake "object library" for common (screenshot) code
+########################################################################
+
+# not yet implemented
+
+########################################################################
+# Build all programs with common options
+########################################################################
+
+set(EXECUTABLE_OUTPUT_PATH
+    ${CMAKE_CURRENT_BINARY_DIR}/../bin/screenshots)
+
+set(PREFIX scr_) # will be prepended to target names
+
+foreach(_prog ${NAMES})
+
+  set(_target ${PREFIX}${_prog}) # enforce the target prefix !
+
+  add_executable(${_target} WIN32 MACOSX_BUNDLE ${_prog}.cxx)
+
+  target_link_libraries(${_target} PRIVATE fltk::images)
+
+  set_target_properties(${_target} PROPERTIES
+    OUTPUT_NAME ${_target}
+    EXCLUDE_FROM_ALL TRUE
+  )
+
+endforeach()
diff --git a/screenshots/README.txt b/screenshots/README.txt
new file mode 100644
index 000000000..8229261d8
--- /dev/null
+++ b/screenshots/README.txt
@@ -0,0 +1,71 @@
+Screenshot Programs for FLTK Documentation
+
+Contents
+
+  All programs in this subdirectory of the FLTK source tree are intended to
+  be used for screenshot generation for the documentation.
+
+  Each program should open one window (maybe more in the future) that can be
+  used as an image for our documentation. Here should be programs developed
+  only for the documentation that are not included in the /test/ or /examples/
+  folders.
+
+Rationale
+
+  Creating screenshots "manually" and storing only the results as (PNG)
+  images should be avoided. There *should* be a source file for each image
+  in the `documentation/images` directory. Many of the existing images can
+  be reproduced by programs in the /test/ folder, but some images used for
+  illustration can currently not be reproduced easily by developers if
+  necessary or wanted.
+
+  These programs are NOT intended to be used automatically by documentation
+  generation. All screenshots generated by these programs shall be checked
+  in (committed) to the FLTK repository for consistency.
+
+Development Status
+
+  Source files for screenshots are collected here. As of today (Jan. 2026)
+  Screenshots must be taken manually but this shall be simplified later.
+
+  This folder is in an early development phase. For now the most important
+  point is to collect the code to prepare for future changes.
+
+Future Development
+
+  The intention is to use a commandline to automate screenshot generation or
+  to output one or more specific screenshot images per program automatically,
+  similar to the code screenshot generation and Fluid's documentation.
+  Details are yet to be defined.
+
+Build System
+
+  The programs in this directory are not built by default in the standard
+  FLTK build.
+
+CMake Option FLTK_BUILD_SCREENSHOTS
+
+  CMake option FLTK_BUILD_SCREENSHOTS (Default: 'OFF') can be set to 'ON'
+  to build all screenshot programs.
+
+  Developers are advised to set FLTK_BUILD_SCREENSHOTS=ON to build the
+  screenshot programs to verify that they compile and work.
+
+Adding New Screenshot Programs
+
+  To add a new program, add the source code here, and add it to the list
+  of programs in CMakeLists.txt. All programs should be built with similar
+  options (using fltk::fltk and fltk::images).
+  Some programs may also use fltk::gl for OpenGL screenshots.
+
+  Note: CMake and some of its supported "generators" (like Ninja) need
+  unique "target" names throughout the entire build system. To avoid
+  conflicts all programs in this folder will be built using a target
+  name with the prefix 'scr_' in folder `bin/screenshots/`.
+  The program is not affected by this prefix.
+
+  Example:
+
+    source file name:          unicode.cxx
+    CMake target name:         scr_unicode
+    Executable:                bin/screenshots/unicode (.exe, .app)
diff --git a/screenshots/unicode.cxx b/screenshots/unicode.cxx
new file mode 100644
index 000000000..d7372b400
--- /dev/null
+++ b/screenshots/unicode.cxx
@@ -0,0 +1,59 @@
+//
+// Unicode test program for the Fast Light Tool Kit (FLTK).
+//
+// Copyright 2025-2026 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
+//
+
+// Generate screenshot with international text
+
+#include <FL/Fl.H>
+#include <FL/platform.H>
+#include <FL/Fl_Double_Window.H>
+#include <FL/Fl_Box.H>
+#include <FL/fl_draw.H>
+#include <string>
+
+static const char *label_text =
+  "ISO-8859-15: ¡¢£¤¥¦§¨©ª«¬­®¯ äöüß € µ ÀÁÂÃÄÅÆÇÈÉÊË ðñòóôõö÷øùúû\n"
+  "Japanese:    FLTKは素晴らしいグラフィックライブラリです\n"
+  "Chinese:     FLTK 是一個非常棒的圖形庫\n"
+  "Greek:       Το FLTK είναι μια καταπληκτική βιβλιοθήκη γραφικών\n"
+  "Korean:      FLTK는 훌륭한 그래픽 라이브러리입니다.\n"
+  "Russian:     FLTK — это потрясающая графическая библиотека.\n"
+  "Hindi:       FLTK एक शानदार ग्राफ़िक्स लाइब्रेरी है\n"
+  "Armenian:    FLTK-ն հիանալի գրաֆիկական գրադարան է\n"
+  "Arab:        FLTK هي مكتبة رائعة لواجهات المستخدم الرسومية\n"
+  "Hebrew:      FLTK היא ספריית ממשק משתמש גרפי מעולה";
+
+int main(int argc, char **argv) {
+  static const Fl_Font font = FL_COURIER;
+  static const int fsize = 20;
+  static const Fl_Color bg = Fl_Color(0xf7f7ff00);
+  fl_open_display();
+  fl_font(font, fsize);
+  int bw = 0, bh = 0;
+  fl_measure(label_text, bw, bh, 0); // measure text
+  auto win = new Fl_Double_Window(bw + 12, bh + 8, "FLTK international text");
+  auto box = new Fl_Box(4, 4, bw, bh, label_text);
+  box->box(FL_FLAT_BOX);
+  box->color(bg);
+  box->labelfont(font);
+  box->labelsize(fsize);
+  box->align(FL_ALIGN_LEFT | FL_ALIGN_INSIDE);
+  win->end();
+  win->color(bg);
+  win->resizable(box);
+  win->size_range(win->w(), win->h());
+  win->show(argc, argv);
+  return Fl::run();
+}