From 2a15b94200abe8ee0df2dddc296f3dafd55655f8 Mon Sep 17 00:00:00 2001
From: mitchell <unknown>
Date: Thu, 11 Jul 2019 14:12:28 -0400
Subject: Backport: Bug [#2038]. Source of input reported in SCN_CHARADDED.
 This may be SC_CHARACTERSOURCE_DIRECT_INPUT,
 SC_CHARACTERSOURCE_TENTATIVE_INPUT, or SC_CHARACTERSOURCE_IME_RESULT.

Backport of changeset 7613:4cfac35c71bd.
---
 doc/ScintillaDoc.html | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

(limited to 'doc/ScintillaDoc.html')

diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html
index 3252c7823..21b288a21 100644
--- a/doc/ScintillaDoc.html
+++ b/doc/ScintillaDoc.html
@@ -3815,7 +3815,7 @@ struct Sci_TextToFind {
      Scintilla may ignore this call in some cases. For example, the inline behaviour might only be supported for some languages.</p>
      <p>When the inline IME mode is active, characters are added tentatively before being finalised and an
      <a class="message" href="#SCN_CHARADDED">SCN_CHARADDED</a>
-     notification is sent for each character.</p>
+     notification (with <code class="parameter">characterSource</code> set to <code>SC_CHARACTERSOURCE_TENTATIVE_INPUT</code>) is sent for each character.</p>
 
     <p><b id="SCI_GRABFOCUS">SCI_GRABFOCUS</b><br />
      <b id="SCI_SETFOCUS">SCI_SETFOCUS(bool focus)</b><br />
@@ -7303,7 +7303,7 @@ struct SCNotification {
 	int updated;	/* SCN_UPDATEUI */
 	int listCompletionMethod;
 	/* SCN_AUTOCSELECTION, SCN_AUTOCCOMPLETED, SCN_USERLISTSELECTION */
-
+	int characterSource;	/* SCN_CHARADDED */
 };
 </pre>
 
@@ -7405,6 +7405,44 @@ href="#SCI_POSITIONFROMLINE">SCI_POSITIONFROMLINE</a>(lineNumber);
         for DBCS, it is (first byte * 256 + second byte) for 2 byte characters and the byte value for 1 byte characters.
         This notification is sent before the character has been styled so processing that depends on
         styling should instead be performed in the SCN_UPDATEUI notification.</p>
+    <p>The <code>SCNotification::characterSource</code> field is the source of the character.</p>
+
+    <table class="standard" summary="Character Source">
+      <tbody>
+        <tr>
+          <th align="left">Symbol</th>
+          <th>Value</th>
+          <th align="left">Meaning</th>
+        </tr>
+      </tbody>
+      <tbody>
+        <tr>
+          <td><code>SC_CHARACTERSOURCE_DIRECT_INPUT</code></td>
+          <td>0</td>
+          <td>Direct input characters, including characters generated by calling keyboard commands like <a class="seealso" href="#SCI_NEWLINE">SCI_NEWLINE</a>.</td>
+        </tr>
+
+        <tr>
+          <td><code>SC_CHARACTERSOURCE_TENTATIVE_INPUT</code></td>
+          <td>1</td>
+          <td>Tentative input characters. They are used by IME (inline mode, see <a class="seealso" href="#SCI_SETIMEINTERACTION">SCI_SETIMEINTERACTION</a>)
+          to composite final string, normally different from final composited string (which is the string that has been truly added into current document),
+          and may be withdrawn when the user cancels typing (e.g. by pressing Esc key).
+          Some system (at least Cocoa) also use tentative input for non-IME features like using dead key to composite diacritical marks (grave accent, etc.).
+          These characters are not added to macro recording. Most applications can simply ignore the notification when this value is set.
+          </td>
+        </tr>
+
+        <tr>
+          <td><code>SC_CHARACTERSOURCE_IME_RESULT</code></td>
+          <td>2</td>
+          <td>IME (either inline or windowed mode) full composited string. Modern IME is able to composite English word or sentence,
+          when this value is set, current character may not a Chinese, Japanese or Korean character.
+          Currently, this is only set on Windows.</td>
+        </tr>
+
+      </tbody>
+    </table>
 
     <p><b id="SCN_SAVEPOINTREACHED">SCN_SAVEPOINTREACHED</b><br />
      <b id="SCN_SAVEPOINTLEFT">SCN_SAVEPOINTLEFT</b><br />
-- 
cgit v1.2.3