Fix position() methods that shadow Fl_Widget::position()

* `FL_DEPRECATED` macro to mark `position()` method that shadow `Fl_Widget::position()` #69 (#666)

6 files changed, 152 insertions, 57 deletions

diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H
index 03550b67a..207bd7082 100644
--- a/FL/Fl_Browser_.H
+++ b/FL/Fl_Browser_.H
@@ -243,8 +243,15 @@ public:
     the list are scrolled off the top edge of the screen.
     \see position(), hposition()
   */
-  int position() const { return position_; }
-  void position(int pos); // scroll to here
+  int vposition() const { return position_; }
+  FL_DEPRECATED("Please use vposition() instead.",
+  int position() const) { return vposition(); }
+
+  void vposition(int pos); // scroll to here
+  FL_DEPRECATED("Please use vposition(pos) instead.",
+  void position(int pos)) { return vposition(pos); }
+  void position(int x, int y) { Fl_Group::position(x, y); }
+  
   /**
     Gets the horizontal scroll position of the list as a pixel position \p pos.
     The position returned is how many pixels of the list are scrolled off the left edge
diff --git a/FL/Fl_Input_.H b/FL/Fl_Input_.H
index 7d3f90cc3..6c1a3eea4 100644
--- a/FL/Fl_Input_.H
+++ b/FL/Fl_Input_.H
@@ -282,31 +282,37 @@ public:
 
   /** Gets the position of the text cursor.
     \return the cursor position as an index in the range 0..size()
-    \see position(int, int)
+    \see insert_position(int, int)
   */
-  int position() const {return position_;}
+  int insert_position() const { return position_; }
+  FL_DEPRECATED("Please use insert_position() instead.",
+  int position() const ) { return insert_position(); }
 
   /** Gets the current selection mark.
     \return index into the text */
   int mark() const {return mark_;}
 
   /* Sets the index for the cursor and mark. */
-  int position(int p, int m);
+  int insert_position(int p, int m);
+  FL_DEPRECATED("Please use insert_position(p, m) or Fl_Widget::position(x, y) instead.",
+  int position(int p, int m)) { return insert_position(p, m); }
 
   /** Sets the cursor position and mark.
     position(n) is the same as <tt>position(n, n)</tt>.
     \param p new index for cursor and mark
     \return 0 if no positions changed
-    \see position(int, int), position(), mark(int)
+    \see insert_position(int, int), insert_position(), mark(int)
   */
-  int position(int p) {return position(p, p);}
+  int insert_position(int p) { return insert_position(p, p); }
+  FL_DEPRECATED("Please use insert_position(p) instead.",
+  int position(int p)) { return insert_position(p); }
 
   /** Sets the current selection mark.
-    mark(n) is the same as <tt>position(position(),n)</tt>.
+    mark(n) is the same as <tt>insert_position(insert_position(),n)</tt>.
     \param m new index of the mark
     \return 0 if the mark did not change
-    \see position(), position(int, int) */
-  int mark(int m) {return position(position(), m);}
+    \see insert_position(), insert_position(int, int) */
+  int mark(int m) {return insert_position(insert_position(), m);}
 
   /* Deletes text from \p b to \p e and inserts the new string \p text. */
   int replace(int b, int e, const char *text, int ilen=0);
@@ -321,7 +327,7 @@ public:
 
     \return 0 if no data was copied
   */
-  int cut() {return replace(position(), mark(), 0);}
+  int cut() {return replace(insert_position(), mark(), 0);}
 
   /**
     Deletes the next \p n bytes rounded to characters before or after the cursor.
@@ -335,7 +341,7 @@ public:
            A negative number will cut characters to the left of the cursor.
     \return 0 if no data was copied
   */
-  int cut(int n) {return replace(position(), position()+n, 0);}
+  int cut(int n) {return replace(insert_position(), insert_position()+n, 0);}
 
   /**
     Deletes all characters between index \p a and \p b.
diff --git a/FL/Fl_Text_Buffer.H b/FL/Fl_Text_Buffer.H
index 727b2a65d..b4e65f8f8 100644
--- a/FL/Fl_Text_Buffer.H
+++ b/FL/Fl_Text_Buffer.H
@@ -164,7 +164,9 @@ public:
   int includes(int pos) const;
 
   // Returns true if selected() and the positions of this selection.
-  int position(int *startpos, int *endpos) const;
+  int selected(int *startpos, int *endpos) const;
+  FL_DEPRECATED("Please use selected(startpos, endpos) instead.",
+  int position(int *startpos, int *endpos) const) { return selected(startpos, endpos); }
 
 protected:
 
diff --git a/FL/Fl_Tile.H b/FL/Fl_Tile.H
index 52d14210c..d6003c286 100644
--- a/FL/Fl_Tile.H
+++ b/FL/Fl_Tile.H
@@ -29,7 +29,10 @@ public:
   int handle(int event) FL_OVERRIDE;
   Fl_Tile(int X, int Y, int W, int H, const char *L=0);
   void resize(int X, int Y, int W, int H) FL_OVERRIDE;
-  void position(int oldx, int oldy, int newx, int newy);
+  void move_intersection(int oldx, int oldy, int newx, int newy);
+  FL_DEPRECATED("Please use move_intersection(p) instead.",
+  void position(int oldx, int oldy, int newx, int newy)) { return move_intersection(oldx, oldy, newx, newy); }
+  void position(int x, int y) { Fl_Group::position(x, y); }
 };
 
 #endif
diff --git a/FL/fl_attr.h b/FL/fl_attr.h
index b8f7d24c4..a75f0c0d8 100644
--- a/FL/fl_attr.h
+++ b/FL/fl_attr.h
@@ -22,13 +22,14 @@
 #ifndef _FL_fl_attr_h_
 #define _FL_fl_attr_h_
 
-#ifdef FL_DOXYGEN
 
 /**
-  This macro makes it safe to use the C++11 keyword \c override with
-  older compilers.
-*/
-#define FL_OVERRIDE override
+ This section lists macros for Doxygen documentation only. The next section
+ will define the actual macros based on the compile used and based on the
+ capabilities of the version of that compiler.
+ */
+#ifdef FL_DOXYGEN
+
 
 /** To be used in prototypes with a variable list of arguments.
  This macro helps detection of mismatches between format string and
@@ -38,67 +39,143 @@
  */
 #define __fl_attr(x)
 
+/**
+  This macro makes it safe to use the C++11 keyword \c override with
+  older compilers.
+*/
+#define FL_OVERRIDE override
+
+/**
+ Enclosing a function or method in FL_DEPRECATED marks it as no longer
+ recommended. This macro syntax can not be used if the return type contains
+ a comma, which is not the case in FLTK.
+
+ \code
+ FL_DEPRECATED("Outdated, don't use", int position()) { return position_; }
+ \endcode
+ */
+#define FL_DEPRECATED(msg, func) [[deprecated(msg)]] func
+
+
 #else
 
 
 /*
-  The GNUC-specific attribute appearing below in prototypes with a variable
-  list of arguments helps detection of mismatches between format string and
-  argument list at compilation time.
+ Declare macros specific to Visual Studio.
 
-  Examples: see fl_ask.H
-*/
+ Visual Studio defines __cplusplus = '199711L' in all its versions which is
+ not helpful for us here. For VS version number encoding see:
+ https://learn.microsoft.com/en-us/cpp/preprocessor/predefined-macros
+ */
 
-#ifdef __GNUC__
-#  define __fl_attr(x) __attribute__ (x)
-#else
-#  define __fl_attr(x)
+#if defined(_MSC_VER)
+
+#if (_MSC_VER >= 1900) // Visual Studio 2015 (14.0)
+#ifndef FL_OVERRIDE
+#define FL_OVERRIDE override
 #endif
+#endif // Visual Studio 2015 (14.0)
 
+#if (_MSC_VER >= 1400) // Visual Studio 2005 (8.0)
+#ifndef FL_DEPRECATED
+#define FL_DEPRECATED(msg, func) __declspec(deprecated(msg)) func
+#endif
+#endif // Visual Studio 2005 (8.0)
 
-#ifdef __cplusplus
+#if (_MSC_VER >= 1310) // Visual Studio .NET 2003 (7.1)
+#ifndef FL_DEPRECATED
+#define FL_DEPRECATED(msg, func) __declspec(deprecated) func
+#endif
+#endif // Visual Studio .NET 2003 (7.1)
 
-// Visual Studio defines __cplusplus = '199711L' which is not helpful.
-// We assume that Visual Studio 2015 (1900) and later support the
-// 'override' keyword. For VS version number encoding see:
-// https://learn.microsoft.com/en-us/cpp/preprocessor/predefined-macros
+#endif // Visual Studio
 
-#if defined(_MSC_VER) && (_MSC_VER >= 1900)
 
-#define FL_OVERRIDE override
+/*
+ Declare macros specific to the C++ standard used.
 
-#else // not Visual Studio or an older version
+ Macros may have been declared already in previous sections.
+ */
+#if (__cplusplus >= 202002L) // C++20
+#endif // C++20
+
+#if (__cplusplus >= 201703L) // C++17
+#endif // C++17
 
-#if (__cplusplus >= 202002L)
-// put here definitions applying to C++20 and above
+#if (__cplusplus >= 201402L) // C++14
+#ifndef FL_DEPRECATED
+#define FL_DEPRECATED(msg, func) [[deprecated(msg)]] func
 #endif
+#endif // C++14
 
-#if (__cplusplus >= 201703L)
-// put here definitions applying to C++17 and above
+#if (__cplusplus >= 201103L) // C++11
+#ifndef FL_OVERRIDE
+#define FL_OVERRIDE override
 #endif
+#endif // C+11
 
-#if (__cplusplus >= 201402L)
-// put here definitions applying to C++14 and above
+#if (__cplusplus >= 199711L) // C++89
+#endif // C++89
+
+
+/*
+ Declare macros specific to clang
+
+ Macros may have been declared already in previous sections.
+ */
+#if defined(__clang__)
+
+#define FL_CLANG_VERSION (__clang_major__ * 10000 + __clang_minor__ * 100 + __clang_patchlevel__)
+
+// -- nothing yet --
+
+#endif // __clang__
+
+
+/*
+ Declare macros specific to gcc.
+
+ Macros may have been declared already in previous sections.
+ */
+#if defined(__GNUC__)
+
+#define FL_GCC_VERSION (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__)
+
+#ifndef __fl_attr
+#define __fl_attr(x) __attribute__ (x)
 #endif
 
-#if (__cplusplus >= 201103L)
-// put here definitions applying to C++11 and above
-#define FL_OVERRIDE override
-#else
-// replace non-existing `override` with no-op
-#define FL_OVERRIDE
+#if FL_GCC_VERSION > 40500 // gcc 4.5.0
+#ifndef FL_DEPRECATED
+#define FL_DEPRECATED(msg, func) func __attribute__((deprecated(msg)))
 #endif
+#endif // gcc 4.5.0
 
-#if (__cplusplus >= 199711L)
-// put here definitions applying to C++98 and above
+#if FL_GCC_VERSION > 30100 // gcc 3.1.0
+#ifndef FL_DEPRECATED
+#define FL_DEPRECATED(msg, func) func __attribute__((deprecated))
 #endif
+#endif // gcc 3.1.0
 
-#endif /* not Visual Studio */
+#endif // __GNUC__
 
-#else
-/* C, not C++ */
 
-#endif /* __cplusplus */
+/*
+ If a macro was not defined in any of the sections above, set it to no-op here.
+ */
+
+#ifndef __fl_attr
+#define __fl_attr(x)
+#endif
+
+#ifndef FL_OVERRIDE
+#define FL_OVERRIDE
+#endif
+
+#ifndef FL_DEPRECATED
+#define FL_DEPRECATED(msg, func) func
+#endif
+
 
 #endif /* FL_DOXYGEN */
 
diff --git a/FL/forms.H b/FL/forms.H
index a25a1c936..594ef0c6d 100644
--- a/FL/forms.H
+++ b/FL/forms.H
@@ -682,7 +682,7 @@ inline void fl_set_input_color(Fl_Widget* o, Fl_Color a, Fl_Color b) {
 }
 // inline void fl_set_input_scroll(Fl_Widget*, int);
 inline void fl_set_input_cursorpos(Fl_Widget* o, int x, int /*y*/) {
-  ((Fl_Input*)o)->position(x);}
+  ((Fl_Input*)o)->insert_position(x);}
 // inline void fl_set_input_selected(Fl_Widget*, int);
 // inline void fl_set_input_selected_range(Fl_Widget*, int, int);
 // inline void fl_set_input_maxchars(Fl_Widget*, int);
@@ -695,7 +695,7 @@ inline void fl_set_input_cursorpos(Fl_Widget* o, int x, int /*y*/) {
 // inline int fl_get_input_topline(Fl_Widget*);
 // inline int fl_get_input_screenlines(Fl_Widget*);
 inline int fl_get_input_cursorpos(Fl_Widget* o, int*x, int*y) {
-  *x = ((Fl_Input*)o)->position(); *y = 0; return *x;}
+  *x = ((Fl_Input*)o)->insert_position(); *y = 0; return *x;}
 // inline int fl_get_input_numberoflines(Fl_Widget*);
 // inline void fl_get_input_format(Fl_Widget*, int*, int*);
 inline const char* fl_get_input(Fl_Widget* o) {return ((Fl_Input*)o)->value();}
@@ -721,7 +721,7 @@ inline void fl_delete_menu_item(Fl_Widget* o, int i) {
 inline void fl_set_menu_item_shortcut(Fl_Widget* o, int i, const char* s) {
     ((Fl_Menu_Button*)o)->shortcut(i-1,fl_old_shortcut(s));}
 inline void fl_set_menu_item_mode(Fl_Widget* o, int i, long x) {
-    ((Fl_Menu_Button*)o)->mode(i-1,x);}
+    ((Fl_Menu_Button*)o)->mode(i-1,(int)x);}
 inline void fl_show_menu_symbol(Fl_Widget*, int ) {
 /*    ((Fl_Menu_Button*)o)->show_menu_symbol(i); */}
 // inline void fl_set_menu_popup(Fl_Widget*, int);