From 5bab46940c9dc6ad272e4cbf7970a7261aaff210 Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Fri, 7 Jan 2022 16:34:44 +0100
Subject: 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.
---
 src/Fl_compose.cxx | 35 +++++++++++++++++++----------------
 1 file changed, 19 insertions(+), 16 deletions(-)

(limited to 'src/Fl_compose.cxx')

diff --git a/src/Fl_compose.cxx b/src/Fl_compose.cxx
index e05819eb2..356823ee1 100644
--- a/src/Fl_compose.cxx
+++ b/src/Fl_compose.cxx
@@ -40,32 +40,35 @@ int Fl::compose_state = 0;
  <p>If <i>false</i> is returned, the keys should be treated as function
  keys, and del is set to zero. You could insert the text anyways, if
  you don't know what else to do.
+ 
+ <p>Text editing widgets can preferentially call fl_set_spot() to indicate the window
+ coordinates of the bottom of the current insertion point and the line height.
+ This way, auxiliary windows that help choosing among alternative characters
+ with some text input methods appear just below or above the insertion point.
+ If widgets don't do that, such auxiliary windows appear at the widget's bottom.
 
- <p>On the Mac OS platform, text input can involve marked text, that is,
+ <p>On some platforms, text input can involve marked text, that is,
  temporary text replaced by other text during the input process. This occurs,
- e.g., when using dead keys or when entering CJK characters.
+ e.g., under macOS when using dead keys or when entering CJK characters.
  Text editing widgets should preferentially signal
  marked text, usually underlining it. Widgets can use
  <tt>int Fl::compose_state</tt> <i>after</i> having called Fl::compose(int&)
  to obtain the length in bytes of marked text that always finishes at the
  current insertion point. Widgets should also call
- <tt>void Fl::reset_marked_text()</tt> when processing FL_UNFOCUS
- events. Optionally, widgets can also call
- <tt>void Fl::insertion_point_location(int x, int y, int height)</tt> to indicate the window
- coordinates of the bottom of the current insertion point and the line height.
- This way, auxiliary windows that help choosing among alternative characters
- appear just below the insertion point. If widgets don't do that,
- auxiliary windows appear at the widget's bottom. The
- Fl_Input and Fl_Text_Editor widgets underline marked text.
+ void fl_reset_spot() when processing FL_UNFOCUS
+ events. The Fl_Input and Fl_Text_Editor widgets underline marked text.
  If none of this is done by a user-defined text editing widget,
  text input will work, but will not signal to the user what text is marked.
- Finally, text editing widgets should call <tt>set_flag(MAC_USE_ACCENTS_MENU);</tt>
- in their constructor if they want to use the feature introduced with Mac OS 10.7 "Lion"
- where pressing and holding certain keys on the keyboard opens an accented-character menu window.
 
- <p>Though the current implementation returns immediately, future
- versions may take quite awhile, as they may pop up a window or do
- other user-interface things to allow characters to be selected.
+ <p>Finally, text editing widgets should call <tt>set_flag(MAC_USE_ACCENTS_MENU);</tt>
+ in their constructor if they want to use, on the macOS platform, the feature introduced with Mac OS 10.7 "Lion"
+ where pressing and holding certain keys on the keyboard opens a diacritic marks popup window.
+ 
+ \note For compatibility with FLTK 1.3, text editing widgets can call
+ <tt>Fl::insertion_point_location(int x, int y, int height)</tt> and <tt>Fl::reset_marked_text()</tt>
+ <u>only under the macOS platform</u>  to indicate/reset the coordinates of the current insertion point.
+ This is deprecated in version 1.4 because redundant with the platform-independent
+ fl_set_spot() and fl_reset_spot() functions.
  */
 int Fl::compose(int& del) {
   return Fl::screen_driver()->compose(del);
-- 
cgit v1.2.3