From a65800cc687a603f72385580332ad74e5e2ff565 Mon Sep 17 00:00:00 2001 From: Eskil Abrahamsen Blomfeldt Date: Mon, 1 Apr 2019 08:02:10 +0200 Subject: Add a clarification about "characters" to QTextCursor docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Konstantin Ritt Reviewed-by: René J.V. Bertin Reviewed-by: Venugopal Shivashankar --- src/gui/text/qtextcursor.cpp | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'src/gui/text/qtextcursor.cpp') 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 -- cgit v1.2.3