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.

5 files changed, 74 insertions, 44 deletions

diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index 42f313e51..688310e08 100644
--- a/documentation/src/drawing.dox
+++ b/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()
 
diff --git a/documentation/src/events.dox b/documentation/src/events.dox
index 38dabeb6f..765e0720d 100644
--- a/documentation/src/events.dox
+++ b/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
-of the Fl_Window that the window system says they
-belong to.  The window (actually the Fl_Group that
-Fl_Window is a subclass of) is responsible for sending
-the events on to any child widgets.  To make the
-Fl_Group code somewhat easier, FLTK sends some events
-(\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
+Most events are sent directly to the \p handle() method of the Fl_Window that
+the window system says they belong to. The window (actually the Fl_Group that
+Fl_Window is a subclass of) is responsible for sending the events on to any
+child widgets. To make the Fl_Group code somewhat easier, FLTK sends some
+events (\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
diff --git a/documentation/src/forms.dox b/documentation/src/forms.dox
index 816da55e6..545dd3af9 100644
--- a/documentation/src/forms.dox
+++ b/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
-(configure/Makefiles) or \c fltk::forms (CMake) can be disabled with
-one of these commands:
+Since FLTK 1.5 building the Forms compatibility library \c fltk_forms
+(aka \c fltk::forms) is disabled by default and can be enabled by one
+of the following commands:
   \code
-    - ./configure --disable-forms ...
-    - cmake -D FLTK_BUILD_FORMS:BOOL=OFF ...
-    - cmake-gui ...
+    - cmake -D FLTK_BUILD_FORMS:BOOL=ON ...
+    - cmake-gui ... (edit option FLTK_BUILD_FORMS)
   \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
-library will not be built by default or will be removed entirely.
+In the next minor or major release (1.6 or higher) the Forms compatibility
+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
-C++ compiler.  The FLTK library does not provide C bindings or header
-files.
+You will also have to compile your Forms or XForms program using a C++
+compiler. The FLTK library does not provide C bindings or header 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
-that would add code that would not be linked in if the feature is
+a goal of FLTK.  Compatibility was limited to things that were free,
+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
diff --git a/documentation/src/migration_1_5.dox b/documentation/src/migration_1_5.dox
index cbe98919b..107bfe061 100644
--- a/documentation/src/migration_1_5.dox
+++ b/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
-to use at least C++11 yourself.
+the FLTK libraries. Otherwise you may need to set the compiler flags to use
+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
-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.
+or earlier have been removed in FLTK 1.5.0.
 
-The following (very likely incomplete) list may help to identify such removed
-methods and functions:
+If you need help with these functions because old code still uses them, please
+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
diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
index 43e29463e..ce8a7fa74 100644
--- a/documentation/src/osissues.dox
+++ b/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
-fl_ask(),
-for instance, it will not return until the modal function
-returns.
+a modal window by calling fl_choice(), for instance, it will not
+return until the modal function returns.
 
 \subsection osissues_drawing_xlib Drawing using Xlib