Re-organize cross-platform support for text input methods.

FLTK 1.3 supports complex text input methods (TIMs) for the 3 platforms
(X11, Windows, macOS). This support has an interface with FLTK that is
common for X11 and Windows, via (undocumented) functions fl_set_spot(),
fl_set_status() and fl_reset_spot().
In contrast, and because it's been developed independently, the
interface between the macOS TIM and FLTK 1.3 is completely different :
static functions FL::insertion_point_location() and Fl::reset_marked_text().

The present change implements a single TIM/FLTK interface
used by all platforms based on functions fl_set_spot() and
fl_reset_spot().

The previous macOS-specific functions FL::insertion_point_location() and
Fl::reset_marked_text() are maintained only for compatibility with 1.3
and deprecated.

2 files changed, 23 insertions, 4 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index 3c887b665..37ec2ca13 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -146,8 +146,11 @@ public:
 
   static Fl_Screen_Driver *screen_driver();
   static Fl_System_Driver *system_driver();
-  static void reset_marked_text(); // resets marked text
-  static void insertion_point_location(int x, int y, int height); // sets window coordinates & height of insertion point
+#ifdef __APPLE__ // deprecated in 1.4 - only for compatibility with 1.3
+  static void reset_marked_text();
+  static void insertion_point_location(int x, int y, int height);
+#endif
+
 
   /** Get the box shadow width of all "shadow" boxtypes in pixels.
     \since 1.4.0
diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index c11dc9f7d..8db59b43b 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -1076,9 +1076,25 @@ FL_EXPORT const char *fl_expand_text(const char *from, char *buf, int maxbuf, do
 // XIM:
 /** \todo provide user documentation for fl_set_status function */
 FL_EXPORT void fl_set_status(int X, int Y, int W, int H);
-/** \todo provide user documentation for fl_set_spot function */
+/** Inform text input methods about the current text insertion cursor.
+ \param font Font currently in use in text input.
+ \param size Size of the current font.
+ \param X,Y Position of the bottom of the current text insertion cursor.
+ \param W,H Width and height of the current text insertion cursor.
+ \param win Points to the Fl_Window object containing the current text widget, or NULL.
+ */
 FL_EXPORT void fl_set_spot(int font, int size, int X, int Y, int W, int H, Fl_Window *win = 0);
-/** \todo provide user documentation for fl_reset_spot function*/
+/** Resets marked text.
+
+ In many languages, typing a character can involve multiple keystrokes. For
+ example, the Ä can be composed of two dots (¨) on top of the
+ character, followed by the letter A (on a Mac with U.S. keyboard, you'd
+ type Alt-U, Shift-A. To inform the user that the dots may be followed by
+ another character, the ¨ is underlined).
+
+ Call this function if character composition needs to be aborted for some
+ reason. One such example would be the text input widget losing focus.
+ */
 FL_EXPORT void fl_reset_spot(void);