Add a clarification about "characters" to QTextCursor docs

The function name QTextCursor::positionInBlock() may give users the
idea that it can be displayed to the user as the visual position of
the cursor in the current block. This becomes confusing with some
writing systems, since e.g. a surrogate pair will count as two
characters while only representing a single visual grapheme.

Since it is an side effect of the encoding that will be unexpected to
many, and since it also touches on some linguistic complexities, we
add a note to the documentation to make users aware of the
consideration needed.

Task-number: QTBUG-74725
Change-Id: Iba28ba8a6ad07ee38dbb7e6a5a4b68c93d4da76a
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
Reviewed-by: Konstantin Ritt <ritt.ks@gmail.com>
Reviewed-by: René J.V. Bertin <rjvbertin@gmail.com>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

1 files changed, 23 insertions, 0 deletions

diff --git a/src/gui/text/qtextcursor.cpp b/src/gui/text/qtextcursor.cpp
index 7719a2e6da..c88497840f 100644
--- a/src/gui/text/qtextcursor.cpp
+++ b/src/gui/text/qtextcursor.cpp
@@ -1145,6 +1145,15 @@ bool QTextCursor::isNull() const
     \a pos using a \c MoveMode specified by \a m. The cursor is positioned
     between characters.
 
+    \note The "characters" in this case refer to the string of QChar
+    objects, i.e. 16-bit Unicode characters, and \a pos is considered
+    an index into this string. This does not necessarily correspond to
+    individual graphemes in the writing system, as a single grapheme may
+    be represented by multiple Unicode characters, such as in the case
+    of surrogate pairs, linguistic ligatures or diacritics. For a more
+    generic approach to navigating the document, use movePosition(),
+    which will respect the actual grapheme boundaries in the text.
+
     \sa position(), movePosition(), anchor()
 */
 void QTextCursor::setPosition(int pos, MoveMode m)
@@ -1176,6 +1185,13 @@ void QTextCursor::setPosition(int pos, MoveMode m)
     Returns the absolute position of the cursor within the document.
     The cursor is positioned between characters.
 
+    \note The "characters" in this case refer to the string of QChar
+    objects, i.e. 16-bit Unicode characters, and the position is considered
+    an index into this string. This does not necessarily correspond to
+    individual graphemes in the writing system, as a single grapheme may
+    be represented by multiple Unicode characters, such as in the case
+    of surrogate pairs, linguistic ligatures or diacritics.
+
     \sa setPosition(), movePosition(), anchor(), positionInBlock()
 */
 int QTextCursor::position() const
@@ -1192,6 +1208,13 @@ int QTextCursor::position() const
 
     This is equivalent to \c{ position() - block().position()}.
 
+    \note The "characters" in this case refer to the string of QChar
+    objects, i.e. 16-bit Unicode characters, and the position is considered
+    an index into this string. This does not necessarily correspond to
+    individual graphemes in the writing system, as a single grapheme may
+    be represented by multiple Unicode characters, such as in the case
+    of surrogate pairs, linguistic ligatures or diacritics.
+
     \sa position()
 */
 int QTextCursor::positionInBlock() const