Finish release 1.4.0

1) Improve and clarify documentation:
 - update, reformat, and reorder parts of CREDITS.txt
 - make sure that documentation appears in doxygen docs
 - add '\since 1.4.0' to documentation of new methods and functions
 - remove doxygen's '\brief' where not required (we're using
   JAVADOC_AUTOBRIEF = YES)
 - clarify screen scaling, scaling factor, and related stuff
- add more info about backwards compatibility for X11 specific code

2) Update dependencies

CREDITS.txt

@@ -1,5 +1,5 @@
-CREDITS.txt - Fast Light Tool Kit (FLTK)
+CREDITS - Fast Light Tool Kit (FLTK)
-----------------------------------------
+-------------------------------------
 
   This file lists the people responsible for the toolkit you are
   now using.  If you've been looking for your name in lights
@@ -39,8 +39,7 @@ CORE DEVELOPERS
 
 OTHER CONTRIBUTORS
 
-  The following people have contributed fixes or enhancements
+  The following people have contributed fixes or enhancements to FLTK:
-  for FLTK:
 
     Laszlo Z. Antal (LZA)
     Teun Burgers
@@ -51,6 +50,7 @@ OTHER CONTRIBUTORS
     Yuri Fedorchenko
     George Garvey
     Duncan Gibson
+    Daniel Harding
     Mikael Hultgren
     Stuart Levy
     Jean-Marc Lienher (OksiD)
@@ -69,4 +69,3 @@ OTHER CONTRIBUTORS
     Josef Vitu
     Jim Wilson
     Ken Yarnall
-    Daniel Harding

README.Wayland.txt

@@ -72,7 +72,7 @@ should run with a Wayland-enabled FLTK 1.4 library with this single change.
 
 Note 1: this may require some linker flags to enable exporting symbols
 from *executable* programs which FLTK uses to "read" the global symbol
-'fl_disable_wayland'. For for GNU `ld` or any GNU compiler this would
+'fl_disable_wayland'. For GNU `ld` or any GNU compiler this would
 be "-rdynamic".
 
 
@@ -85,15 +85,16 @@ the following techniques:
 
 Option 1: Set target property 'ENABLE_EXPORTS' on all executable
           targets that require to disable the Wayland backend.
-          This is the preferred solution.
+          This is the preferred solution because it works per target.
 
           CMake example:
 
           set_target_properties(myprog PROPERTIES ENABLE_EXPORTS TRUE)
 
-Option 2: Set CMake policy CMP0065 to 'OLD' (to pre-3.4 behavior)
+Option 2: Set CMake policy CMP0065 to 'OLD' (i.e. pre-3.4 behavior)
           This is a quick solution but discouraged because setting
           CMake policies to 'OLD' is "deprecated by definition".
+          CMake may issue warnings or ignore this in the future.
 
           CMake code:
 

documentation/src/migration_1_4.dox

@@ -8,10 +8,10 @@ to change source code. We also explain how code can be made compatible
 so it can be compiled by both FLTK 1.3.x and 1.4.x.
 
 If you need to migrate your code from prior FLTK versions to FLTK 1.4,
-then you should first consult the relevant appendices in the FLTK 1.3
+please consult the relevant appendices in the FLTK 1.3 online documentation
-online documentation or by downloading the FLTK 1.3 documentation.
+or by downloading the FLTK 1.3 documentation.
-See https://www.fltk.org/doc-1.3/index.html and/or
+See https://www.fltk.org/doc-1.3/migration_1_3.html and/or
-https://www.fltk.org/software.php , respectively.
+https://www.fltk.org/software.php, respectively.
 
 
 \section migration_1_4_headers Changes in Header Files
@@ -20,34 +20,34 @@ We strive to include only necessary header files in the public headers
 of the FLTK library to reduce dependencies and hence compile times.
 
 We try to avoid including system header files as far as possible. Known
-exceptions are \<stdio.h> where file system structures and functions are
+exceptions are \c \<stdio.h> where file system structures and functions are
-visible in the public API, for instance \p FILE*, and sometimes essential
+visible in the public API, for instance \c FILE*, and sometimes essential
-header files like \<stdlib.h> and/or \<stddef.h>. Some required system
+header files like \c \<stdlib.h> and/or \c \<stddef.h>. Some required
-headers \b may be included in platform specific header files like
+system headers \b may be included in platform specific header files like
-\<FL/platform.H> or \<FL/platform_types.h>.
+\c \<FL/platform.H> or \c \<FL/platform_types.h>.
 
 In earlier versions (1.3.x) some of the public FLTK headers included some
 not strictly required system headers by accident.
 
-The consequence for building user programs with FLTK 1.4 is that if you
+The consequence for building user programs with FLTK 1.4 is: if you
 require a system or FLTK header in your user program that you don't
-\e \#include explicitly but which has been included by FLTK 1.3.x your
+\c \#include explicitly but which has been included by FLTK 1.3.x your
-FLTK 1.3 program may issue compiler errors or warnings about missing header
+FLTK 1.3 program may issue compiler errors or warnings about missing
-files or missing declarations when compiled with FLTK 1.4.
+header files or missing declarations when compiled with FLTK 1.4.
 
 This is not a fault of FLTK 1.4 but a fault of the source code that did
 not include all required headers.
 
-In FLTK 1.4 inclusion of \<FL/Fl.H> is no longer a strict requirement as
+In FLTK 1.4 inclusion of \c \<FL/Fl.H> is no longer a strict requirement
-it was required and documented in FLTK 1.3.x. In FLTK 1.4 you may still
+as it was required and documented in FLTK 1.3.x. In FLTK 1.4 you may still
-need to '\#include \<FL/Fl.H>' if you are using enumerations or methods
+need to \c '\#include \c \<FL/Fl.H>' if you are using enumerations or methods
 of class \c Fl like Fl::run() but there are exceptions where this header
-is included by other FLTK headers, like Fl_Window.H and other subclasses.
+is included by other FLTK headers, like \c Fl_Window.H and other subclasses.
 
 Suggested solution: include all FLTK and system header files your source
 code requires explicitly and don't rely on FLTK headers to include a
 particular header file. If you want your code to be as much as possible
-compatible with FLTK 1.3.x, then you should \c '\#include \<FL/Fl.H>'
+compatible with FLTK 1.3.x, then you should \c '\#include \c \<FL/Fl.H>'
 as required by 1.3.x.
 
 You don't need to include headers of base classes - this is done by all
@@ -94,7 +94,7 @@ change your program to use these new constants instead of those without the
 \p "_L" suffix. For more information see the documentation of Fl_Preferences.
 
 
-\section migration_1_4_add_timeout Fl::add_timeout and friends
+\section migration_1_4_timeout Fl::add_timeout and friends
 
 Since FLTK 1.4.0 internal timeout handling has been unified across platforms.
 This ensures equal timeout handling, improved accuracy of Fl::repeat_timeout(),
@@ -180,6 +180,87 @@ Code example in header file:
 Note the \p 'const' attribute \b and the \p FL_OVERRIDE macro.
 
 
+\section migration_1_4_x11_compat Using X11 specific code with a "hybrid" FLTK library
+
+Read this section if your FLTK 1.3 program uses X11 specific code with platform
+specific guards like
+\code
+  #if defined(WIN32)
+    // Windows specific code here
+  #elif defined(__APPLE__)
+    // macOS specific code here
+  #else
+    // X11 specific code here
+  #endif
+\endcode
+
+or similar.
+
+You may skip this section if you don't use platform (X11) specific code.
+
+FLTK 1.4 introduced Wayland support on Unix-like systems that support Wayland
+at runtime. The default build selects the Wayland runtime if it exists at
+program startup and falls back to using X11 if Wayland is not supported.
+On all currently known Wayland-enabled systems X11 programs are still supported
+by using "XWayland" which must be installed and enabled on the system. This is
+usually the case (as of this writing in November 2024).
+
+Since using the Wayland runtime is the default you may get runtime errors
+if your program uses X11 specific code with the Wayland runtime.
+
+There are two solutions:
+
+ -# Change the conditional code shown above everywhere in your program. This
+    is the best and recommended long-term solution but may require some work.
+ -# Disable the Wayland backend (runtime) for your program. This can be a
+    short-term solution for quick "porting" success.
+
+Details about solution 1 are beyond the scope of this documentation but here's
+an example how such code can be rewritten in FLTK 1.4 for all platforms. This
+code is now in test/fltk-versions.cxx but may be changed in the future. Change
+this as you need.
+
+  \code
+    static const char *get_platform() {
+    #if defined(_WIN32)
+      return "Windows";
+    #elif defined(FLTK_USE_X11) || defined(FLTK_USE_WAYLAND)
+    # if defined(FLTK_USE_X11)
+      if (fl_x11_display())
+        return "Unix/Linux (X11)";
+    # endif
+    # if defined(FLTK_USE_WAYLAND)
+      if (fl_wl_display())
+        return "Unix/Linux (Wayland)";
+    # endif
+      return "X11 or Wayland (backend unknown or display not opened)";
+    #elif defined(__APPLE__)
+      return "macOS (native)";
+    #endif
+      return "platform unknown, unsupported, or display not opened";
+    }
+  \endcode
+
+
+Solution 2 is described in chapter 2.1 of README.Wayland.txt. Please read this
+chapter if you need to support X11 specific code w/o the Wayland runtime.
+
+Excerpt from README.Wayland.txt:
+
+  It is possible to force a program linked to a Wayland-enabled FLTK library
+  to use X11 in all situations by putting this declaration somewhere in the
+  source code:
+
+  \code
+      FL_EXPORT bool fl_disable_wayland = true;
+  \endcode
+
+Please note that you may need to do more to link and run your program
+successfully, depending on the build system.
+
+Additional info can be found in chapter \ref osissues_wl_x11_hybrid.
+
+
 \section migration_1_4_modern_cmake Modern CMake
 
 FLTK 1.4.0 supports "modern" CMake rather than old or "classic" CMake

src/Fl.cxx

@@ -164,6 +164,7 @@ void Fl::scrollbar_size(int W) {
 /**
   Gets the default line spacing used by menus.
   \returns The default line spacing, in pixels.
+  \since 1.4.0
 */
 int Fl::menu_linespacing() {
   return menu_linespacing_;
@@ -173,6 +174,7 @@ int Fl::menu_linespacing() {
   Sets the default line spacing used by menus.
   Default is 4.
   \param[in] H The new default line spacing between menu items, in pixels.
+  \since 1.4.0
 */
 void Fl::menu_linespacing(int H) {
   menu_linespacing_ = H;
@@ -872,19 +874,23 @@ void Fl::add_handler(Fl_Event_Handler ha) {
 }
 
 
-/** Returns the last function installed by a call to Fl::add_handler() */
+/** Returns the last function installed by a call to Fl::add_handler().
+
+  \since 1.4.0
+*/
 Fl_Event_Handler Fl::last_handler() {
   return handlers ? handlers->handle : NULL;
 }
 
 
 /** Install a function to parse unrecognized events with less priority than another function.
- Install function \p ha to handle unrecognized events
+  Install function \p ha to handle unrecognized events
- giving it the priority just lower than that of function \p before
+  giving it the priority just lower than that of function \p before
- which was previously installed.
+  which was previously installed.
- \see Fl::add_handler(Fl_Event_Handler)
+  \see Fl::add_handler(Fl_Event_Handler)
- \see Fl::last_handler()
+  \see Fl::last_handler()
- */
+  \since 1.4.0
+*/
 void Fl::add_handler(Fl_Event_Handler ha, Fl_Event_Handler before) {
   if (!before) return Fl::add_handler(ha);
   handler_link *l = handlers;
@@ -1028,10 +1034,10 @@ Fl_Widget* fl_oldfocus; // kludge for Fl_Group...
     \e test if the widget wants the focus (by it returning non-zero from
     handle()).
 
-    Widgets can set the NEEDS_KEYBOARD flag to indicate that a keyboard is
+    Since FLTK 1.4.0 widgets can set the NEEDS_KEYBOARD flag to indicate that
-    essential for the widget to function. Touchscreen devices will be sent a
+    a keyboard is essential for the widget to function. Touchscreen devices
-    request to show an on-screen keyboard if no hardware keyboard is
+    will be sent a request to show an on-screen keyboard if no hardware keyboard
-    connected.
+    is connected.
 
     \see Fl_Widget::take_focus()
     \see Fl_Widget::needs_keyboard() const
@@ -1273,9 +1279,11 @@ static int send_event(int event, Fl_Widget* to, Fl_Window* window) {
 }
 
 /**
- \brief Give the reason for calling a callback.
+  Give the reason for calling a callback.
- \return the reason for the current callback
+
- \see Fl_Widget::when(), Fl_Widget::do_callback(), Fl_Widget::callback()
+  \return the reason for the current callback
+  \see Fl_Widget::when(), Fl_Widget::do_callback(), Fl_Widget::callback()
+  \since 1.4.0
  */
 Fl_Callback_Reason Fl::callback_reason() {
   return callback_reason_;
@@ -2109,27 +2117,27 @@ bool Fl::option(Fl_Option opt)
 }
 
 /**
- \brief Override an option while the application is running.
+  Override an option while the application is running.
 
- Apps can override the machine settings and the user settings by calling
+  Apps can override the machine settings and the user settings by calling
- `Fl::option(option, bool)`. The override takes effect immediately for this
+  `Fl::option(option, bool)`. The override takes effect immediately for this
- option for all widgets in the app for the life time of the app.
+  option for all widgets in the app for the life time of the app.
 
- The override is not saved anywhere, and relaunching the app will restore the
+  The override is not saved anywhere, and relaunching the app will restore the
- old settings.
+  old settings.
 
- Example:
+  Example:
- \code
+  \code
-     Fl::option(Fl::OPTION_ARROW_FOCUS, true);     // on
+    Fl::option(Fl::OPTION_ARROW_FOCUS, true);     // on
-     Fl::option(Fl::OPTION_ARROW_FOCUS, false);    // off
+    Fl::option(Fl::OPTION_ARROW_FOCUS, false);    // off
- \endcode
+  \endcode
 
- \param opt which option
+  \param opt which option
- \param val set to true or false
+  \param val set to true or false
 
  \see enum Fl::Fl_Option
  \see bool Fl::option(Fl_Option)
- */
+*/
 void Fl::option(Fl_Option opt, bool val)
 {
   if (opt<0 || opt>=OPTION_LAST)
@@ -2281,16 +2289,24 @@ void fl_close_display()
 }
 
 #ifdef FL_DOXYGEN
-/** Prevent the FLTK library from using its Wayland backend and forces it to use its X11 backend.
+/** Prevent the FLTK library from using its Wayland backend and force it to use its X11 backend.
- Put this declaration somewhere in your code outside the body of any function  :
+
- \code
+  Put this declaration somewhere in your source code outside the body of any function:
- FL_EXPORT bool fl_disable_wayland = true;
+  \code
- \endcode
+    FL_EXPORT bool fl_disable_wayland = true;
- This declaration makes sure source code developed for FLTK 1.3, including X11-specific code,
+  \endcode
- will build and run with FLTK 1.4 and its Wayland platform with this single source code level change.
+  This declaration makes sure that source code developed for FLTK 1.3, including
- This declaration has no effect on non-Wayland platforms.
+  X11-specific code, will build and run with FLTK 1.4 and its Wayland platform
- Don't put this declaration if you want the Wayland backend to be used when it's available.
+  with a single line source code level change.
- */
+  This declaration has no effect on non-Wayland platforms.
+  Don't add this declaration if you want the Wayland backend to be used when
+  it's available.
+
+  \note Please see also chapter 2.1 of README.Wayland.txt for further information
+    on how to build your application to ensure that this declaration is effective.
+
+  \since 1.4.0
+*/
 FL_EXPORT bool fl_disable_wayland = true;
 #endif // FL_DOXYGEN
 
@@ -2331,15 +2347,44 @@ int Fl::get_font_sizes(Fl_Font fnum, int*& sizep) {
   return Fl_Graphics_Driver::default_driver().get_font_sizes(fnum, sizep);
 }
 
-/** Current value of the GUI scaling factor for screen number \p n (n ∈ [0 , Fl::screen_count()-1]) */
+/** Gets the GUI scaling factor of screen number \p n.
+
+  The valid range of \p n is 0 .. Fl::screen_count() - 1.
+
+  The return value is \c 1.0 if screen scaling is not supported or
+  \p n is outside the valid range.
+
+  \return Current screen scaling factor (default: \c 1.0)
+
+  \see Fl::screen_count()
+  \see Fl::screen_scaling_supported()
+
+  \since 1.4.0
+*/
 float Fl::screen_scale(int n) {
-  if (!Fl::screen_scaling_supported() || n < 0 || n >= Fl::screen_count()) return 1.;
+  if (!Fl::screen_scaling_supported() || n < 0 || n >= Fl::screen_count())
+    return 1.;
   return Fl::screen_driver()->scale(n);
 }
 
-/** Sets the value of the GUI scaling factor for screen number \p n (n ∈ [0 , Fl::screen_count()-1]).
+/** Sets the GUI scaling factor of screen number \p n.
- Also sets the scale factor value of all windows mapped to screen number \p n, if any.
+
- */
+  The valid range of \p n is 0 .. Fl::screen_count() - 1.
+
+  This method does nothing if \p n is out of range or screen scaling
+  is not supported by this platform.
+
+  Otherwise it also sets the scaling factor of all windows mapped to
+  screen number \p n or all screens, depending on the type of screen
+  scaling support on the platform.
+
+  \param[in] n        screen number
+  \param[in] factor   scaling factor of screen \p n
+
+  \see Fl::screen_scaling_supported()
+
+  \since 1.4.0
+*/
 void Fl::screen_scale(int n, float factor) {
   Fl_Screen_Driver::APP_SCALING_CAPABILITY capability = Fl::screen_driver()->rescalable();
   if (!capability || n < 0 || n >= Fl::screen_count()) return;
@@ -2347,16 +2392,21 @@ void Fl::screen_scale(int n, float factor) {
     for (int s = 0; s < Fl::screen_count(); s++) {
       Fl::screen_driver()->rescale_all_windows_from_screen(s, factor, factor);
     }
-  } else Fl::screen_driver()->rescale_all_windows_from_screen(n, factor, factor);
+  } else
+    Fl::screen_driver()->rescale_all_windows_from_screen(n, factor, factor);
 }
 
 /**
-  See if scaling factors are supported by this platform.
+  Returns whether scaling factors are supported by this platform.
- \return 0 if scaling factors are not supported by this platform,
+
- 1 if a single scaling factor value is shared by all screens, 2 if each screen
+  \retval 0 scaling factors are not supported by this platform
- can have its own scaling factor value.
+  \retval 1 a single scaling factor is shared by all screens
+  \retval 2 each screen can have its own scaling factor
+
   \see Fl::screen_scale(int)
- */
+
+  \since 1.4.0
+*/
 int Fl::screen_scaling_supported() {
   return Fl::screen_driver()->rescalable();
 }
@@ -2373,6 +2423,8 @@ int Fl::screen_scaling_supported() {
 
   \param value 0 to stop recognition of ctrl/+/-/0/ (or cmd/+/-/0/ under macOS)
     keys as window scaling.
+
+  \since 1.4.0
 */
 void Fl::keyboard_screen_scaling(int value) {
   Fl_Screen_Driver::keyboard_screen_scaling = value;

src/Fl_Window.cxx

@@ -1,7 +1,7 @@
 //
 // Window widget class for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2022 by Bill Spitzak and others.
+// Copyright 1998-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
@@ -679,16 +679,19 @@ void Fl_Window::size_range(int minWidth, int minHeight,
 }
 
 /**
- Gets the allowable range to which the user can resize this window.
+  Gets the allowable range to which the user can resize this window.
 
- \param[out] minWidth, minHeight, maxWidth, maxHeight, deltaX, deltaY, aspectRatio
+  \param[out] minWidth, minHeight, maxWidth, maxHeight, deltaX, deltaY, aspectRatio
     are all pointers to integers that will receive the current respective value
     during the call. Every pointer can be NULL if that value is not needed.
- \retval 0 if size range not set
+
- \retval 1 if the size range was explicitly set by a call to Fl_Window::size_range()
+  \retval 0 if size range not set
-    or has been calculated
+  \retval 1 if the size range was explicitly set by a call to Fl_Window::size_range()
- \see Fl_Window::size_range(int minWidth, int minHeight, int maxWidth, int maxHeight, int deltaX, int deltaY, int aspectRatio)
+            or has been calculated
- */
+  \see Fl_Window::size_range(int minWidth, int minHeight, int maxWidth, int maxHeight, int deltaX, int deltaY, int aspectRatio)
+
+  \since 1.4.0
+*/
 uchar Fl_Window::get_size_range(int *minWidth, int *minHeight,
                                 int *maxWidth, int *maxHeight,
                                 int *deltaX, int *deltaY, int *aspectRatio) {
@@ -780,6 +783,8 @@ uchar Fl_Window::get_size_range(int *minWidth, int *minHeight,
 
   If this is not what you want, please use Fl_Window::size_range()
   explicitly so you can set any appropriate range.
+
+  \since 1.4.0
 */
 void Fl_Window::default_size_range() {
 
@@ -859,6 +864,8 @@ void Fl_Window::default_size_range() {
   \retval  3  the window is resizable in both directions (w and h)
 
   \see default_size_range()
+
+  \since 1.4.0
 */
 int Fl_Window::is_resizable() {
   default_size_range();
@@ -868,27 +875,59 @@ int Fl_Window::is_resizable() {
   return ret;
 }
 
-/** The number of the screen containing the mapped window */
+/** The number of the screen containing the mapped window.
+
+  This method returns the screen number (0 .. n) of the window
+  if it is shown, otherwise the result value is undefined.
+
+  \note The return value is undefined before the window is shown and
+    if the window has been hidden after it was previously shown.
+
+  To position a window on a particular screen, use
+  Fl_Window::screen_num(int) \b before you show() it.
+
+  \return screen number of the window if it is shown
+
+  \see Fl_Window::screen_num(int)
+
+  \since 1.4.0
+ */
 int Fl_Window::screen_num() {
   return pWindowDriver->screen_num();
 }
 
 /** Set the number of the screen where to map the window.
- Call this and set also the window's desired position before show()'ing the window.
+
- This can be necessary when a system has several screens with
+  Call this and set also the window's desired x/y position before show()'ing
- distinct scaling factor values because the window's x() and y() may not suffice to
+  the window. This can be necessary if a system has several screens with
- uniquely identify one screen.
+  distinct scaling factors because the window's x() and y() may not suffice
- To see that, consider a system with two screens where the screen at left is A pixel-wide
+  to uniquely identify one screen.
- and has a scale factor of 1 whereas the screen at right has a scale factor of 2.
+
- For the sake of simplicity, consider only
+  Consider a system with two screens where the left screen is A pixels wide and
- the X coordinates of windows. FLTK coordinates translate directly to pixel coordinates on the
+  has a scaling factor of 1 whereas the right screen has a scaling factor of 2.
- left screen, whereas FLTK coordinates multiplied by 2 correspond to pixel coordinates
+  For the sake of simplicity, consider only the X coordinate of the window.
- on the right screen. Consequently, FLTK coordinates between A/2 + 1 and A-1 can map to both
+  FLTK coordinates translate directly to pixel coordinates on the left screen,
- screens.  Both window coordinates and screen number are necessary to uniquely identify
+  whereas FLTK coordinates multiplied by 2 correspond to pixel coordinates
- where a window is to be mapped.
+  on the right screen. Consequently, FLTK coordinates between A/2 + 1 and A-1
- */
+  can map to both screens. Therefore both the window coordinates and the screen
+  number are necessary to uniquely identify where a window is to be mapped.
+
+  The valid range of \p screen_num is 0 .. Fl::screen_count() - 1.
+
+  This method does nothing if
+  - the window is already shown() or
+  - the given screen number is out of range.
+
+  \param[in] screen_num screen number where the window is to be mapped
+
+  \see Fl_Window::screen_num()
+  \see Fl::screen_count()
+
+  \since 1.4.0
+*/
 void Fl_Window::screen_num(int screen_num) {
-  if (!shown() && screen_num >= 0 && screen_num < Fl::screen_count()) pWindowDriver->screen_num(screen_num);
+  if (!shown() && screen_num >= 0 && screen_num < Fl::screen_count())
+    pWindowDriver->screen_num(screen_num);
 }
 
 /** Assigns a non-rectangular shape to the window.
@@ -934,29 +973,43 @@ void Fl_Window::shape(const Fl_Image* img) {pWindowDriver->shape(img);}
  */
 void Fl_Window::shape(const Fl_Image& img) {pWindowDriver->shape(&img);}
 
-/** Returns the image controlling the window shape or NULL */
+/** Returns the image controlling the window shape or NULL.
+
+  \since 1.4.0
+*/
 const Fl_Image* Fl_Window::shape() {return pWindowDriver->shape();}
 
-/** Returns true when a window is being rescaled */
+/** Returns true when a window is being rescaled.
+
+  \since 1.4.0
+*/
 bool Fl_Window::is_a_rescale() {return Fl_Window_Driver::is_a_rescale_;}
 
 /** Returns a platform-specific identification of a shown window, or 0 if not shown.
- \note This identification may differ from the platform-specific reference of an
+
- Fl_Window object used by functions fl_x11_xid(), fl_mac_xid(), fl_x11_find(), and fl_mac_find().
+  \note This identification may differ from the platform-specific reference
- \li X11 platform: the window's XID.
+        of an Fl_Window object used by functions fl_x11_xid(), fl_mac_xid(),
- \li macOS platform: The window number of the window’s window device.
+        fl_x11_find(), and fl_mac_find().
- \li other platforms: 0.
+
- */
+  - X11 platform: the window's XID.
+  - macOS platform: The window number of the window’s window device.
+  - other platforms: 0.
+
+  \since 1.4.0
+*/
 fl_uintptr_t Fl_Window::os_id() { return pWindowDriver->os_id();}
 
 /**
- Maximizes a top-level window to its current screen.
+  Maximizes a top-level window to its current screen.
 
- This function is effective only with a show()'n, resizable, top-level window.
+  This function is effective only with a show()'n, resizable, top-level window.
- Bordered and borderless windows can be used.
+  Bordered and borderless windows can be used.
- Fullscreen windows can't be used.
+  Fullscreen windows can't be used.
- \see Fl_Window::un_maximize(), Fl_Window::maximize_active()
+
- */
+  \see Fl_Window::un_maximize(), Fl_Window::maximize_active()
+
+  \since 1.4.0
+*/
 void Fl_Window::maximize() {
   if (!shown() || parent() || !is_resizable() || maximize_active() || fullscreen_active())
     return;
@@ -965,8 +1018,10 @@ void Fl_Window::maximize() {
 }
 
 /**
- Returns a previously maximized top-level window to its previous size.
+  Returns a previously maximized top-level window to its previous size.
- \see Fl_Window::maximize()
+  \see Fl_Window::maximize()
+
+  \since 1.4.0
 */
 void Fl_Window::un_maximize() {
   if (!shown() || parent() || !is_resizable() || !maximize_active() || fullscreen_active()) return;
@@ -980,8 +1035,11 @@ void Fl_Window::is_maximized_(bool b) {
 }
 
 /** Allow this subwindow to expand outside the area of its parent window.
- This is presently implemented only for the Wayland platform to help support window docking.
+
- \since 1.4.0
+  This is presently implemented only for the Wayland platform to help
+  support window docking.
+
+  \since 1.4.0
 */
 void Fl_Window::allow_expand_outside_parent() {
   if (parent()) pWindowDriver->allow_expand_outside_parent();

src/makedepend

@@ -3701,6 +3701,7 @@ fl_shortcut.o: Fl_Screen_Driver.H
 fl_shortcut.o: Fl_System_Driver.H
 Fl_Shortcut_Button.o: ../config.h
 Fl_Shortcut_Button.o: ../FL/Enumerations.H
+Fl_Shortcut_Button.o: ../FL/filename.H
 Fl_Shortcut_Button.o: ../FL/Fl.H
 Fl_Shortcut_Button.o: ../FL/fl_attr.h
 Fl_Shortcut_Button.o: ../FL/Fl_Button.H
@@ -3709,6 +3710,7 @@ Fl_Shortcut_Button.o: ../FL/fl_casts.H
 Fl_Shortcut_Button.o: ../FL/fl_config.h
 Fl_Shortcut_Button.o: ../FL/fl_draw.H
 Fl_Shortcut_Button.o: ../FL/Fl_Export.H
+Fl_Shortcut_Button.o: ../FL/Fl_Preferences.H
 Fl_Shortcut_Button.o: ../FL/Fl_Shortcut_Button.H
 Fl_Shortcut_Button.o: ../FL/fl_string_functions.h
 Fl_Shortcut_Button.o: ../FL/fl_types.h
@@ -3716,6 +3718,7 @@ Fl_Shortcut_Button.o: ../FL/fl_utf8.h
 Fl_Shortcut_Button.o: ../FL/Fl_Widget.H
 Fl_Shortcut_Button.o: ../FL/platform_types.h
 Fl_Shortcut_Button.o: flstring.h
+Fl_Shortcut_Button.o: Fl_System_Driver.H
 fl_show_colormap.o: ../config.h
 fl_show_colormap.o: ../FL/Enumerations.H
 fl_show_colormap.o: ../FL/Fl.H

src/screen_xywh.cxx

@@ -1,7 +1,7 @@
 //
 // Screen/monitor bounding box API for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2018 by Bill Spitzak and others.
+// Copyright 1998-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
@@ -57,7 +57,7 @@ int Fl::h()
 
 /**
   Gets the total count of available screens.
-  \note Screen numbers range from 0 to Fl::screen_count()-1 in the FLTK API.
+  \note Screen numbers range from 0 to Fl::screen_count() - 1 in the FLTK API.
 */
 int Fl::screen_count()
 {
@@ -133,13 +133,16 @@ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my, int mw, int
 
 
 /**
-  Gets the screen number of a screen
+  Gets the screen number of a screen that contains the specified
-  that contains the specified screen position \p x, \p y
+  screen position \p x, \p y.
+
   \param[in] x, y the absolute screen position
   \return a screen number ∈ [0 , Fl::screen_count()-1]
-  \attention When the running system contains screens with different scaling factor values, this API
+
- may become ambiguous because a given value pair (\p x, \p y) may belong to distinct screens.
+  \attention When the running system contains screens with different scaling
- In that situation, other APIs should be preferred, e.g., Fl_Window::screen_num() and Fl::screen_scale(int).
+    factors, this API may become ambiguous because a given value pair (\p x, \p y)
+    may belong to distinct screens. In that situation other APIs should be
+    preferred, e.g. Fl_Window::screen_num() and Fl::screen_scale(int).
 */
 int Fl::screen_num(int x, int y)
 {
@@ -148,12 +151,13 @@ int Fl::screen_num(int x, int y)
 
 
 /**
-  Gets the screen number for the screen
+  Gets the screen number of the screen which intersects the most with
-  which intersects the most with the rectangle
+  the rectangle defined by \p x, \p y, \p w, \p h.
-  defined by \p x, \p y, \p w, \p h.
+
   \param[in] x, y, w, h the rectangle to search for intersection with
+
   \return a screen number ∈ [0 , Fl::screen_count()-1]
-  */
+*/
 int Fl::screen_num(int x, int y, int w, int h)
 {
   return screen_driver()->screen_num(x, y, w, h);

test/makedepend

@@ -953,10 +953,16 @@ fltk-versions.o: ../FL/Fl_Cairo.H
 fltk-versions.o: ../FL/fl_casts.H
 fltk-versions.o: ../FL/fl_config.h
 fltk-versions.o: ../FL/Fl_Export.H
+fltk-versions.o: ../FL/Fl_Grid.H
+fltk-versions.o: ../FL/Fl_Group.H
+fltk-versions.o: ../FL/Fl_Rect.H
 fltk-versions.o: ../FL/fl_types.h
 fltk-versions.o: ../FL/fl_utf8.h
+fltk-versions.o: ../FL/Fl_Widget.H
 fltk-versions.o: ../FL/Fl_Window.H
+fltk-versions.o: ../FL/platform.H
 fltk-versions.o: ../FL/platform_types.h
+fltk-versions.o: ../FL/x11.H
 fonts.o: ../FL/Enumerations.H
 fonts.o: ../FL/filename.H
 fonts.o: ../FL/Fl.H