Don't give incorrect example in wxTextEntry::GetInsertionPoint() docs.

Using the text control position as index in GetValue() is wrong in general,
show the correct way of doing this.

Closes #14372.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@71647 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/wx/textentry.h b/interface/wx/textentry.h
index d31506f1c0c0245fe69caefb202ff5767cf0cdbe..0a5a5e22307f5c381b5ec177a236f8054ced2eae 100644 (file)
--- a/interface/wx/textentry.h
+++ b/interface/wx/textentry.h
@@ -211,19 +211,28 @@ public:
 
         This is defined as the zero based index of the character position to
         the right of the insertion point. For example, if the insertion point
-        is at the end of the single-line text control, it is equal to both
-        GetLastPosition() and @c "GetValue().Length()" (but notice that the latter
-        equality is not necessarily true for multiline edit controls which may
-        use multiple new line characters).
+        is at the end of the single-line text control, it is equal to
+        GetLastPosition().
 
-        The following code snippet safely returns the character at the insertion
-        point or the zero character if the point is at the end of the control.
+        Notice that insertion position is, in general, different from the index
+        of the character the cursor position at in the string returned by
+        GetValue(). While this is always the case for the single line controls,
+        multi-line controls can use two characters @c "\\r\\n" as line
+        separator (this is notably the case under MSW) meaning that indices in
+        the control and its string value are offset by 1 for every line.
+
+        Hence to correctly get the character at the current cursor position,
+        taking into account that there can be none if the cursor is at the end
+        of the string, you could do the following:
 
         @code
-        char GetCurrentChar(wxTextCtrl *tc) {
-            if (tc->GetInsertionPoint() == tc->GetLastPosition())
-            return '\0';
-            return tc->GetValue[tc->GetInsertionPoint()];
+        wxString GetCurrentChar(wxTextCtrl *tc)
+        {
+            long pos = tc->GetInsertionPoint();
+            if ( pos == tc->GetLastPosition() )
+                return wxString();
+
+            return tc->GetRange(pos, pos + 1);
         }
         @endcode
     */