Remove deprecated methods and functions

In FLTK 1.5 we remove most (but not all) methods and functions that
were deprecated in FLTK 1.3 or earlier.

FL/Fl.H

@@ -1322,10 +1322,6 @@ private:
 public:
   /** See grab(Fl_Window*) */
   static void grab(Fl_Window& win) {grab(&win);}
-  /** Releases the current grabbed window, equals grab(0).
-  \deprecated Use Fl::grab(0) instead.
-  \see grab(Fl_Window*) */
-  static void release() {grab(0);}
 
   // Visible focus methods...
   /**

FL/Fl_Group.H

@@ -244,13 +244,6 @@ public:
 
   // back compatibility functions:
 
-  /**
-    \deprecated This is for backwards compatibility only. You should use
-    \e W->%take_focus() instead.
-    \sa Fl_Widget::take_focus();
-  */
-  void focus(Fl_Widget* W) {W->take_focus();}
-
   /** This is for forms compatibility only */
   Fl_Widget* & _ddfdesign_kludge() {return resizable_;}
 

FL/Fl_Menu_Item.H

@@ -528,30 +528,6 @@ struct FL_EXPORT Fl_Menu_Item {
     Fl::callback_reason_ = reason; callback_(o, (void*)(fl_intptr_t)arg);
   }
 
-  /** Back compatibility only.
-    \deprecated
-      Please use Fl_Menu_Item::value() instead.
-      This method will be removed in FLTK 1.5.0 or later.
-    \see value()
-  */
-  inline int checked() const {return value();}
-
-  /** Back compatibility only.
-    \deprecated
-      Please use Fl_Menu_Item::set() instead.
-      This method will be removed in FLTK 1.5.0 or later.
-    \see set()
-  */
-  inline void check() {set();}
-
-  /** Back compatibility only.
-    \deprecated
-      Please use Fl_Menu_Item::clear() instead.
-      This method will be removed in FLTK 1.5.0 or later.
-    \see clear()
-  */
-  inline void uncheck() {clear();}
-
   int insert(int,const char*,int,Fl_Callback*,void* =0, int =0);
   int add(const char*, int shortcut, Fl_Callback*, void* =0, int = 0);
 

FL/Fl_Widget.H

@@ -1,7 +1,7 @@
 //
 // Widget header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2024 by Bill Spitzak and others.
+// Copyright 1998-2025 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
@@ -119,7 +119,7 @@ class FL_EXPORT Fl_Widget {
   Fl_Label label_;
   unsigned int flags_;
   Fl_Color color_;
-  Fl_Color color2_;
+  Fl_Color selection_color_;
   uchar type_;
   uchar damage_;
   uchar box_;
@@ -470,7 +470,7 @@ public:
       \return the current selection color
       \see selection_color(Fl_Color), color(Fl_Color, Fl_Color)
    */
-  Fl_Color selection_color() const {return color2_;}
+  Fl_Color selection_color() const {return selection_color_;}
 
   /** Sets the selection color.
       The selection color is defined for Forms compatibility and is usually
@@ -480,7 +480,7 @@ public:
       \param[in] a the new selection color
       \see selection_color(), color(Fl_Color, Fl_Color)
    */
-  void selection_color(Fl_Color a) {color2_ = a;}
+  void selection_color(Fl_Color a) {selection_color_ = a;}
 
   /** Sets the background and selection color of the widget.
 
@@ -489,7 +489,7 @@ public:
       \param[in] sel selection color
       \see color(unsigned), selection_color(unsigned)
    */
-  void color(Fl_Color bg, Fl_Color sel) {color_=bg; color2_=sel;}
+  void color(Fl_Color bg, Fl_Color sel) {color_ = bg; selection_color_ = sel;}
 
   /** Gets the current label text.
       \return a pointer to the current label text
@@ -1247,16 +1247,6 @@ public:
    */
   int use_accents_menu() { return flags() & MAC_USE_ACCENTS_MENU; }
 
-  /** For back compatibility only.
-      \deprecated Use selection_color() instead.
-  */
-  Fl_Color color2() const {return (Fl_Color)color2_;}
-
-  /** For back compatibility only.
-      \deprecated Use selection_color(unsigned) instead.
-  */
-  void color2(unsigned a) {color2_ = a;}
-
   /** Sets whether the widget's label uses '&' to indicate shortcuts.
    By default, all objects of classes Fl_Menu_ (and derivatives), Fl_Button (and derivatives),
    Fl_Text_Display, Fl_Value_Input, and Fl_Input_ (and derivatives)

FL/fl_ask.H

@@ -26,6 +26,23 @@
 
 #include <string>
 
+// Note to FLTK developers: fl_ask() had been deprecated since FLTK 1.1.7
+// (released Jan 17, 2006 !) but was still available in FLTK 1.4.x.
+// FLTK 1.5 disables it by using an *undocumented* preprocessor macro.
+// This allows us to restore it (as a last resort) if there are too many
+// complaints that fl_ask() is missing. If users don't complain, the
+// conditional implementation of fl_ask() should be removed in FLTK 1.6.
+
+#ifndef FL_DOXYGEN
+
+// undocumented feature: include fl_ask() if requested; see comment above.
+
+#ifndef FLTK_INCLUDE_FL_ASK
+#define FLTK_INCLUDE_FL_ASK 0  // set this to 1 to include fl_ask()
+#endif
+
+#endif // FL_DOXYGEN
+
 class Fl_Widget;
 
 /** Defines the different system beeps available.
@@ -48,12 +65,16 @@ FL_EXPORT void fl_beep(int type = FL_BEEP_DEFAULT);
 FL_EXPORT void fl_message(const char *, ...) __fl_attr((__format__(__printf__, 1, 2)));
 FL_EXPORT void fl_alert(const char *, ...) __fl_attr((__format__(__printf__, 1, 2)));
 
+#if FLTK_INCLUDE_FL_ASK
+
 // fl_ask() is deprecated since it uses "Yes" and "No" for the buttons,
 // which does not conform to the current FLTK Human Interface Guidelines.
 // Use fl_choice() or fl_choice_n() with the appropriate verbs instead.
 
 FL_EXPORT int fl_ask(const char *, ...) __fl_attr((__format__(__printf__, 1, 2), __deprecated__));
 
+#endif // FLTK_INCLUDE_FL_ASK
+
 FL_EXPORT int fl_choice(const char *q, const char *b0, const char *b1, const char *b2, ...)
     __fl_attr((__format__(__printf__, 1, 5)));
 FL_EXPORT const char *fl_input(const char *label, const char *deflt = 0, ...) __fl_attr((__format__(__printf__, 1, 3)));

FL/fl_draw.H

@@ -88,17 +88,6 @@ inline Fl_Color fl_color() {
 inline void fl_push_clip(int x, int y, int w, int h) {
   fl_graphics_driver->push_clip(x, y, w, h);
 }
-/**
-  Intersect the current clip region with a rectangle and push this
-  new region onto the stack (deprecated).
-  \param[in] x,y,w,h position and size
-  \deprecated
-    Please use fl_push_clip(int x, int y, int w, int h) instead.
-    fl_clip(int, int, int, int) will be removed in FLTK 1.5.
-*/
-inline void fl_clip(int x, int y, int w, int h) {
-  fl_graphics_driver->push_clip(x, y, w, h);
-}
 /**
   Push an empty clip region onto the stack so nothing will be clipped.
 */

README.Wayland.txt

@@ -91,7 +91,7 @@ Option 1: Set target property 'ENABLE_EXPORTS' on all executable
 
           set_target_properties(myprog PROPERTIES ENABLE_EXPORTS TRUE)
 
-Option 2: Set CMake policy CMP0065 to 'OLD' (i.e. 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.

documentation/src/drawing.dox

@@ -189,15 +189,11 @@ In addition, the system may provide clipping when updating windows
 which may be more complex than a simple rectangle.
 
 void fl_push_clip(int x, int y, int w, int h) <br>
-void fl_clip(int x, int y, int w, int h)
 
 \par
 Intersect the current clip region with a rectangle and push this new
 region onto the stack.
 
-\par
-The \p %fl_clip() version is deprecated and
-will be removed from future releases.
 
 void fl_push_no_clip()
 

documentation/src/events.dox

@@ -458,15 +458,12 @@ event by returning 1. FLTK will then remove the event and wait for further event
 from the host. If the widget's handle function returns 0, FLTK may redistribute
 the event based on a few rules.
 
-Most events are sent directly to the \p handle() method
+Most events are sent directly to the \p handle() method of the Fl_Window that
-of the Fl_Window that the window system says they
+the window system says they belong to. The window (actually the Fl_Group that
-belong to.  The window (actually the Fl_Group that
+Fl_Window is a subclass of) is responsible for sending the events on to any
-Fl_Window is a subclass of) is responsible for sending
+child widgets. To make the Fl_Group code somewhat easier, FLTK sends some
-the events on to any child widgets.  To make the
+events (\p FL_DRAG, \p FL_RELEASE, \p FL_KEYBOARD, \p FL_SHORTCUT,
-Fl_Group code somewhat easier, FLTK sends some events
+\p FL_UNFOCUS, and \p FL_LEAVE) directly to leaf widgets. These procedures
-(\p FL_DRAG, \p FL_RELEASE, \p FL_KEYBOARD,
-\p FL_SHORTCUT, \p FL_UNFOCUS, and \p FL_LEAVE)
-directly to leaf widgets. These procedures
 control those leaf widgets:
 
 \li Fl::add_handler()
@@ -475,7 +472,6 @@ control those leaf widgets:
 \li Fl::grab()
 \li Fl::modal()
 \li Fl::pushed()
-\li Fl::release() (deprecated, see Fl::grab(0))
 \li Fl_Widget::take_focus()
 
 FLTK propagates events along the widget hierarchy depending on the kind of event

documentation/src/forms.dox

@@ -7,22 +7,21 @@ This appendix describes the Forms compatibility included with FLTK.
 
 \note The Forms compatibility library is deprecated, no longer actively
   maintained since FLTK 1.3.0, and likely to be removed completely
-  in FLTK 1.5.
+  in FLTK 1.6. Building it was optional (ON) in FLTK 1.4.
 
-Since FLTK 1.4 building the Forms compatibility library \c fltk_forms
+Since FLTK 1.5 building the Forms compatibility library \c fltk_forms
-(configure/Makefiles) or \c fltk::forms (CMake) can be disabled with
+(aka \c fltk::forms) is disabled by default and can be enabled by one
-one of these commands:
+of the following commands:
   \code
-    - ./configure --disable-forms ...
+    - cmake -D FLTK_BUILD_FORMS:BOOL=ON ...
-    - cmake -D FLTK_BUILD_FORMS:BOOL=OFF ...
+    - cmake-gui ... (edit option FLTK_BUILD_FORMS)
-    - cmake-gui ...
   \endcode
 
-Fluid can still import Forms and XForms designer (.fd) files but w/o
+Fluid can still \b import Forms and XForms designer (.fd) files but w/o
 any guarantees for working results. Manual fixes may be necessary.
 
-In the next minor or major release (1.5 or higher) the Forms compatibility
+In the next minor or major release (1.6 or higher) the Forms compatibility
-library will not be built by default or will be removed entirely.
+library may be removed entirely.
 
 
 \section forms_importing Importing Forms Layout Files
@@ -48,15 +47,14 @@ Take a look at <FL/forms.H> to see how it works, but the basic trick
 is lots of inline functions. Most of the XForms demo programs work
 without changes.
 
-You will also have to compile your Forms or XForms program using a
+You will also have to compile your Forms or XForms program using a C++
-C++ compiler.  The FLTK library does not provide C bindings or header
+compiler. The FLTK library does not provide C bindings or header files.
-files.
 
 Although FLTK was designed to be compatible with the GL Forms
 library (version 0.3 or so), XForms has bloated severely and its
 interface is X-specific.  Therefore, XForms compatibility is no longer
-a goal of FLTK.  Compatibility was limited to things that were free, or
+a goal of FLTK.  Compatibility was limited to things that were free,
-that would add code that would not be linked in if the feature is
+or that would add code that would not be linked in if the feature is
 unused, or that was not X-specific.
 
 To use any new features of FLTK, you should rewrite your code to not

documentation/src/migration_1_5.dox

@@ -31,8 +31,8 @@ build.
 
 If you use "Modern CMake" (basically CMake in CONFIGURE mode) to build your
 own projects the appropriate options are inherited from the properties of
-the FLTK libraries as well. Otherwise you may need to set the compiler flags
+the FLTK libraries. Otherwise you may need to set the compiler flags to use
-to use at least C++11 yourself.
+at least C++11 yourself.
 
 
 \section migration_1_5_forms Default for FORMS compatibility is now OFF
@@ -61,20 +61,62 @@ FLTK requires C++11 anyway.
 For more details please see \ref migration_1_4_fl_override.
 
 
-\section migration_1_5_deprecated Deprecated methods and functions removed
+\section migration_1_5_removed Removed Methods and Functions
 
 Methods, functions, and global symbols that have been deprecated in FLTK 1.3
-or earlier have been removed. If you need help with those functions because
+or earlier have been removed in FLTK 1.5.0.
-your old code still uses one or more of them, please consult the FLTK 1.3 or
-1.4 documentation for how to replace them with newer functions/methods.
 
-The following (very likely incomplete) list may help to identify such removed
+If you need help with these functions because old code still uses them, please
-methods and functions:
+consult the table below for a quick solution. If this doesn't help please read
+the FLTK 1.3 or 1.4 documentation to find out how to replace them with newer
+functions or methods, for instance https://www.fltk.org/doc-1.4/deprecated.html.
 
-Removed symbol            | Replace with ...
---------------------------|-------------------------
-Fl::release()             | Fl::grab(0)
 
+The following (possibly incomplete) list can help to identify and replace
+these removed methods and functions.
+
+Removed Symbol                          | Please Replace With ...
+----------------------------------------|-------------------------
+Fl::release()                           | Fl::grab(0)
+Fl::set_idle(Fl_Old_Idle_Handler cb)    | Fl::add_idle(cb [, data])
+fl_ask(const char *fmt,...)             | fl_choice()
+fl_clip(int, int, int, int)             | fl_push_clip(int x, int y, int w, int h)
+Fl_Group::focus(Fl_Widget *W)           | (Fl_Widget*) W->take_focus()
+Fl_Menu_Item::check()                   | Fl_Menu_Item::set()
+Fl_Menu_Item::checked() const           | int Fl_Menu_Item::value() const
+Fl_Menu_Item::uncheck()                 | Fl_Menu_Item::clear()
+Fl_Widget::color2() const               | Fl_Widget::selection_color() const
+Fl_Widget::color2(unsigned)             | Fl_Widget::selection_color(unsigned)
+
+
+
+\section migration_1_5_deprecated More Deprecated Methods and Functions
+
+All methods deprecated in <b> FLTK 1.4.x or earlier </b> are likely to be
+removed in the next minor FLTK version, presumably 1.6.0.
+
+Please update your code!
+
+The following list is currently incomplete and will be extended later.
+
+
+Symbol To Be Removed In The Next Minor Release         | Please Replace With ...
+-------------------------------------------------------|-------------------------
+void Fl_Window::icon(const void *ic)                   | void Fl_Window::icon(const Fl_RGB_Image *icon)
+const void *Fl_Window::icon() const                    | no replacement (was platform specific)
+&nbsp;                                                 | &nbsp;
+Fl_Tree::first_visible()                               | in 1.3.3 ABI
+Fl_Tree::first_visible_item()                          | ?
+Fl_Tree::item_clicked(Fl_Tree_Item *val)               | callback_item()
+Fl_Tree::item_clicked()                                | callback_item()
+Fl_Tree::last_visible()                                | last_visible_item()
+&nbsp;                                                 | &nbsp;
+Fl_Tree_Item::Fl_Tree_Item(const Fl_Tree_Prefs &prefs) | Fl_Tree_Item(Fl_Tree*)
+Fl_Tree_Item::next_displayed(Fl_Tree_Prefs &prefs)     | next_visible()
+Fl_Tree_Item::prev_displayed(Fl_Tree_Prefs &prefs)     | prev_visible()
+
+For details please refer to the documentation of FLTK 1.4 at
+https://www.fltk.org/doc-1.4/deprecated.html.
 
 
 \htmlonly

documentation/src/osissues.dox

@@ -160,10 +160,8 @@ periodically so that FLTK redraws its windows.
 \par
 This function will call the callback functions. It will not
 return until they complete. In particular, if a callback pops up
-a modal window by calling
+a modal window by calling fl_choice(), for instance, it will not
-fl_ask(),
+return until the modal function returns.
-for instance, it will not return until the modal function
-returns.
 
 \subsection osissues_drawing_xlib Drawing using Xlib
 

src/Fl.cxx

@@ -1,7 +1,7 @@
 //
 // Main event handling code for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2024 by Bill Spitzak and others.
+// Copyright 1998-2025 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
@@ -1800,7 +1800,7 @@ static Fl_Widget  **dwidgets = 0;
 
   To avoid early deletion of widgets, this function should be called
   toward the end of a callback and only after any call to the event
-  loop (Fl::wait(), Fl::flush(), Fl::check(), fl_ask(), etc.).
+  loop (Fl::wait(), Fl::flush(), Fl::check(), fl_choice(), etc.).
 
   When deleting groups or windows, you must only delete the group or
   window widget and not the individual child widgets.

src/Fl_Message.cxx

@@ -24,7 +24,7 @@
   \file Fl_Message.cxx - Base class for common dialogs.
 
   This is the base class for all common FLTK dialog windows used in
-  fl_message(), fl_ask(), fl_choice(), fl_input(), and fl_password().
+  fl_message(), fl_choice(), fl_input(), and fl_password().
 
   \note <b>Internal use only. This class may be changed as required
     without notice.</b>\n
@@ -46,7 +46,7 @@
 #include <FL/Fl.H>
 #include "flstring.h"
 #include <FL/fl_ask.H>
-#include "Fl_Message.h"     // intentionally "hidden" in src/...
+#include "Fl_Message.h"               // intentionally "hidden" in src/...
 #include "FL/fl_string_functions.h"   // fl_strdup()
 
 #include <FL/Fl_Window.H>
@@ -403,8 +403,8 @@ int Fl_Message::innards(const char *fmt, va_list ap, const char *b0, const char
 /**
   Gets the default icon container (Fl_Box) used in common dialogs.
 
-  Many common dialogs like fl_message(), fl_alert(), fl_ask(),
+  Many common dialogs like fl_message(), fl_alert(),  fl_choice(),
-  fl_choice(), fl_input(), and fl_password() display an icon.
+  fl_input(), and fl_password() display an icon.
 
   You can use this method to get the icon box (Fl_Box) and modify
   the icon's box type, font, fontsize etc.
@@ -514,7 +514,7 @@ const char *Fl_Message::input_innards(const char *fmt, va_list ap, const char *d
 /** Sets the title of the dialog window used in many common dialogs.
 
   This window \p title will be used in the next call of one of the
-  common dialogs like fl_message(), fl_alert(), fl_ask(), fl_choice(),
+  common dialogs like fl_message(), fl_alert(), fl_choice(),
   fl_input(), fl_password().
 
   The \p title string is copied internally, so that you can use a
@@ -537,7 +537,7 @@ void Fl_Message::message_title(const char *title) {
 /** Sets the default title of the dialog window used in many common dialogs.
 
   This window \p title will be used in all subsequent calls of one of the
-  common dialogs like fl_message(), fl_alert(), fl_ask(), fl_choice(),
+  common dialogs like fl_message(), fl_alert(), fl_choice(),
   fl_input(), fl_password(), unless a specific title has been set
   with fl_message_title(const char *title).
 

src/Fl_Widget.cxx

@@ -1,7 +1,7 @@
 //
 // Base widget class for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2022 by Bill Spitzak and others.
+// Copyright 1998-2025 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
@@ -110,28 +110,28 @@ Fl_Widget::Fl_Widget(int X, int Y, int W, int H, const char* L) {
 
   x_ = X; y_ = Y; w_ = W; h_ = H;
 
-  label_.value   = L;
+  label_.value     = L;
-  label_.image   = 0;
+  label_.image     = 0;
-  label_.deimage = 0;
+  label_.deimage   = 0;
-  label_.type    = FL_NORMAL_LABEL;
+  label_.type      = FL_NORMAL_LABEL;
-  label_.font    = FL_HELVETICA;
+  label_.font      = FL_HELVETICA;
-  label_.size    = FL_NORMAL_SIZE;
+  label_.size      = FL_NORMAL_SIZE;
-  label_.color   = FL_FOREGROUND_COLOR;
+  label_.color     = FL_FOREGROUND_COLOR;
-  label_.align_  = FL_ALIGN_CENTER;
+  label_.align_    = FL_ALIGN_CENTER;
   label_.h_margin_ = label_.v_margin_ = 0;
-  label_.spacing = 0;
+  label_.spacing   = 0;
-  tooltip_       = 0;
+  tooltip_         = 0;
-  callback_      = default_callback;
+  callback_        = default_callback;
-  user_data_     = 0;
+  user_data_       = 0;
-  type_          = 0;
+  type_            = 0;
-  flags_         = VISIBLE_FOCUS;
+  flags_           = VISIBLE_FOCUS;
-  damage_        = 0;
+  damage_          = 0;
-  box_           = FL_NO_BOX;
+  box_             = FL_NO_BOX;
-  color_         = FL_GRAY;
+  color_           = FL_GRAY;
-  color2_        = FL_GRAY;
+  selection_color_ = FL_GRAY;
-  when_          = FL_WHEN_RELEASE;
+  when_            = FL_WHEN_RELEASE;
 
-  parent_ = 0;
+  parent_ = nullptr;
   if (Fl_Group::current()) Fl_Group::current()->add(this);
 }
 

src/fl_ask.cxx

@@ -1,7 +1,7 @@
 //
 // Standard dialog functions for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2022 by Bill Spitzak and others.
+// Copyright 1998-2025 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
@@ -29,7 +29,7 @@
   - fl_alert()
   - fl_beep()
   - fl_message()
-  - fl_ask()
+  - fl_ask()      // deprecated since 1.1.7 (2006), see comment in FL/fl_ask.H
   - fl_choice()
   - fl_input()
   - fl_input_str()
@@ -129,6 +129,8 @@ void fl_alert(const char *fmt, ...) {
   va_end(ap);
 }
 
+#if FLTK_INCLUDE_FL_ASK // see FL/fl_ask.H
+
 /** Shows a dialog displaying the \p fmt message,
     this dialog features 2 yes/no buttons.
 
@@ -154,6 +156,8 @@ int fl_ask(const char *fmt, ...) {
   return r;
 }
 
+#endif // FLTK_INCLUDE_FL_ASK
+
 /** Shows a dialog displaying the printf style \p fmt message.
 
   This dialog features up to 3 customizable choice buttons

src/fl_rect.cxx

@@ -1,7 +1,7 @@
 //
 // Rectangle drawing routines for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2018 by Bill Spitzak and others.
+// Copyright 1998-2025 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
@@ -21,7 +21,7 @@
 
 // These routines from fl_draw.H are used by the standard boxtypes
 // and thus are always linked into an fltk program.
-// Also all fl_clip routines, since they are always linked in so
+// Also all fl_*_clip routines, since they are always linked in so
 // that minimal update works.
 
 #include <FL/platform.H>