Move global FLTK options into new app fltk-admin (#560)

7 files changed, 191 insertions, 5 deletions

diff --git a/documentation/src/advanced.dox b/documentation/src/advanced.dox
index 7489a4698..19ee40041 100644
--- a/documentation/src/advanced.dox
+++ b/documentation/src/advanced.dox
@@ -425,9 +425,9 @@ Fl::thread_message().
 <table summary="navigation bar" width="100%" border="0">
 <tr>
   <td width="45%" align="LEFT">
-    <a class="el" href="fluid.html">
+    <a class="el" href="fltk-options.html">
     [Prev]
-    Programming with FLUID
+    FLTK Runtime Options
     </a>
   </td>
   <td width="10%" align="CENTER">
diff --git a/documentation/src/fltk-config.man b/documentation/src/fltk-config.man
index 6b53958b8..e021930df 100644
--- a/documentation/src/fltk-config.man
+++ b/documentation/src/fltk-config.man
@@ -81,7 +81,7 @@ Enables image file support.
 .br
 Displays the current FLTK version number, e.g. "1.1.0".
 .SH SEE ALSO
-fluid(1), fltk(3)
+fluid(1), fltk-options(1), fltk(3)
 .br
 FLTK Programming Manual
 .br
diff --git a/documentation/src/fltk-options.dox b/documentation/src/fltk-options.dox
new file mode 100644
index 000000000..c9603fc6d
--- /dev/null
+++ b/documentation/src/fltk-options.dox
@@ -0,0 +1,85 @@
+/**
+
+ \page  fltk-options   FLTK Runtime Options
+
+In this chapter, we will cover how to access and alter settings for
+applications created using FLTK, both as an administrator and as
+a regular user.
+
+Subchapters:
+
+\li \ref fltk-options_basics
+\li \ref fltk-options_access
+\li \ref fltk-options_app
+\li \ref fltk-options_options
+
+\section fltk-options_basics Runtime Options
+
+FLTK keeps track of various aspects of the user interface in a system-wide
+database. Users have the ability to set their own preferences and override
+default or system settings. For instance, FLTK will display a dotted
+rectangle around the widget with current focus. This might not be desirable
+for users who do not use keyboard navigation and do not need the rectangle.
+This can be turned off by setting the OPTION_VISIBLE_FOCUS option to 'off'
+for that user, which will disable the focus rectangle in all FLTK-based
+applications.
+
+\section fltk-options_access Obtaining Current Settings
+
+Options are kept in preference files using the signature
+`Fl_Preferences::CORE_SYSTEM, "fltk.org", "fltk"` for system-wide settings
+and `Fl_Preferences::CORE_USER, "fltk.org", "fltk"` for individual users.
+They can be accessed by using the function `bool Fl::option(Fl_Option opt)`.
+If an application needs to temporarily override user or system settings,
+it can use the function `void option(Fl_Option opt, bool val)`.
+
+To make changes to options permanently, FLTK provides an administrative
+tool called fltk-options.
+
+\section fltk-options_app Administrative Tool
+
+`fltk-options` is a hybrid app that is part of FLTK and can be installed on
+the target system. It includes an up-to-date man page.
+
+When fltk-options is called without any command-line arguments, it opens in
+interactive mode and provides a user interface to view and alter all
+system and current user options.
+
+Starting the tool from a shell, the command-line options `-S` and `-U` can be
+used to display or change system or user options. On MS-Windows, `fltk-options`
+is also available as `fltk-options-cmd.exe`.
+
+\section fltk-options_options List of Options
+
+Calling `fltk-options --help` gives a list of all available commands, and
+options and their values. `fltk-options --help OPTION` prints more detailed
+information for OPTION if available. In interactive mode, tooltips provide
+this additional information.
+
+A full list of options can be found in the maunal at \ref Fl_Option .
+
+
+\htmlonly
+<hr>
+<table summary="navigation bar" width="100%" border="0">
+<tr>
+  <td width="45%" align="LEFT">
+    <a class="el" href="fluid.html">
+    [Prev]
+    Programming with FLUID
+    </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="advanced.html">
+    Advanced FLTK
+    [Next]
+    </a>
+  </td>
+</tr>
+</table>
+\endhtmlonly
+
+*/
diff --git a/documentation/src/fltk-options.man b/documentation/src/fltk-options.man
new file mode 100644
index 000000000..c3beae1c1
--- /dev/null
+++ b/documentation/src/fltk-options.man
@@ -0,0 +1,98 @@
+.TH fltk\-options 1 "Fast Light Tool Kit" "13. January 2023"
+.SH NAME
+fltk\-options \- application to get and modify FLTK runtime options.
+.sp
+.SH SYNOPSIS
+fltk\-options
+[ \-S\fIoption[=value]\fR ]
+[ \-U\fIoption[=value]\fR ]
+[ \-L ]
+[ \-LS ]
+[ \-LU ]
+[ \-f ]
+[ \-v ] [ \-\-verbose ]
+[ \-h[option] ] [ \-\-help [option] ]
+.SH DESCRIPTION
+\fIfltk\-options\fR is a tool that allows you to access and change settings
+related to the user interface in applications built with FLTK. These settings
+will be applied when the program is launched. They can be set at the system
+level or by the individual user. User settings take precedence
+over system settings.
+.LP
+The following command line arguments are supported:
+.TP 5
+\-S\fIoption[=value]\fR
+.br
+Change or print system wide option.
+.TP 5
+\-U\fIoption[=value]\fR
+.br
+Change or print user option. Values can be "0" or "OFF" to clear,
+or "1" or "ON" to set the option. The value "-1" or "DEFAULT" sets
+the option to its default value.
+If no value is given, the current setting is returned as "-1", "0", or "1".
+.TP 5
+\-L
+.br
+List the value of all options.
+.TP 5
+\-LS
+.br
+List the value of all system options.
+.TP 5
+\-LU
+.br
+List the value of all user options.
+.TP 5
+\-f
+.br
+Suppress error messages concerning file access permissions.
+.TP 5
+\-v, \-\-verbose
+.br
+Print additional information in command line mode.
+.TP 5
+\-h[option], \-\-help [option]
+.br
+Prints a help page. If an option is give, print detailed information
+for that option.
+.LP
+The following FLTK options are supported:
+.TP 5
+OPTION_VISIBLE_FOCUS
+.br
+Draw a dotted rectangle in widget with keyboard focus.
+.TP 5
+OPTION_ARROW_FOCUS
+.br
+Arrow keys will move focus beyond text input field.
+.TP 5
+OPTION_SHOW_TOOLTIPS
+.br
+Show or hide tooltips.
+.TP 5
+OPTION_DND_TEXT
+.br
+User can drag text from FLTK into other apps.
+.TP 5
+OPTION_FNFC_USES_GTK
+.br
+Use GTK file chooser instead of FLTK if available.
+.TP 5
+OPTION_PRINTER_USES_GTK
+.br
+Use GTK printer dialog instead of FLTK if available.
+.TP 5
+OPTION_SHOW_SCALING
+.br
+Show the zoom factor in a transient popup window.
+.LP
+Calling fltk-options without options will launch fltk-options interactive mode.
+.SH SEE ALSO
+fluid(1), fltk-config(1), fltk(3)
+.br
+FLTK Programming Manual
+.br
+FLTK Web Site, https://www.fltk.org/
+.SH AUTHORS
+Bill Spitzak and others.
diff --git a/documentation/src/fluid.dox b/documentation/src/fluid.dox
index fc020f7d7..4cbf2c04a 100644
--- a/documentation/src/fluid.dox
+++ b/documentation/src/fluid.dox
@@ -1694,8 +1694,8 @@ On Apple computers, use the Apple Command key instead of Ctrl.
     <a class="el" href="index.html">[Index]</a>
   </td>
   <td width="45%" align="RIGHT">
-    <a class="el" href="advanced.html">
-    Advanced FLTK
+    <a class="el" href="fltk-options.html">
+    FLTK Runtime Options
     [Next]
     </a>
   </td>
diff --git a/documentation/src/index.dox b/documentation/src/index.dox
index 7d3858d57..b7e04ac99 100644
--- a/documentation/src/index.dox
+++ b/documentation/src/index.dox
@@ -72,6 +72,8 @@
         - \ref fluid_selecting_moving
         - \ref fluid_images
 
+    \subpage fltk-options
+
     \subpage advanced
 
     \subpage unicode
diff --git a/documentation/src/preface.dox b/documentation/src/preface.dox
index 168240570..95e0216f1 100644
--- a/documentation/src/preface.dox
+++ b/documentation/src/preface.dox
@@ -31,6 +31,7 @@ This manual is organized into the following chapters and appendices:
 \li \ref subclassing
 \li \ref opengl
 \li \ref fluid
+\li \ref fltk-options
 \li \ref advanced
 \li \ref unicode
 \li \ref enumerations