Fix wxWebView documentation warnings.

[wxWidgets.git] / interface / wx / textentry.h

diff --git a/interface/wx/textentry.h b/interface/wx/textentry.h
index 330b00efa1d30b257cd8799c38497a7fbc55d29c..193e47ef5100d0b0c83a70c29c16a3eb14e52985 100644 (file)
--- a/interface/wx/textentry.h
+++ b/interface/wx/textentry.h
@@ -8,6 +8,13 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+
+/**
+    wxTextPos is a position in the text
+*/
+typedef long wxTextPos;
+
+
 /**
     @class wxTextEntry
 
@@ -173,7 +180,7 @@ public:
         The insertion point is set to the start of the control (i.e. position
         0) by this function.
 
-        This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
+        This functions does not generate the @c wxEVT_TEXT
         event but otherwise is identical to SetValue().
 
         See @ref overview_events_prog for more information.
@@ -189,7 +196,7 @@ public:
     /**
         Clears the text in the control.
 
-        Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
+        Note that this function will generate a @c wxEVT_TEXT
         event, i.e. its effect is identical to calling @c SetValue("").
     */
     virtual void Clear();
@@ -199,24 +206,38 @@ public:
     */
     virtual void Copy();
 
+    /**
+        Copies the selected text to the clipboard and removes it from the control.
+    */
+    virtual void Cut();
+
     /**
         Returns the insertion point, or cursor, position.
 
         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
     */
@@ -380,7 +401,7 @@ public:
         and the user may enter as much text as the underlying native text control widget
         supports (typically at least 32Kb).
         If the user tries to enter more characters into the text control when it
-        already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
+        already is filled up to the maximal length, a @c wxEVT_TEXT_MAXLEN
         event is sent to notify the program about it (giving it the possibility
         to show an explanatory message, for example) and the extra input is discarded.
 
@@ -413,6 +434,13 @@ public:
     */
     virtual void SelectAll();
 
+    /**
+        Deselects selected text in the control.
+
+        @since 2.9.5
+    */
+    virtual void SelectNone();
+
     /**
         Sets a hint shown in an empty unfocused text control.
 
@@ -440,6 +468,10 @@ public:
             currently you should avoid calling methods such as WriteText() or
             Replace() when using hints and the text control is empty.
 
+        @remarks Hints can only be used for single line text controls,
+            native multi-line text controls don't support hints under any
+            platform and hence wxWidgets doesn't provide them neither.
+
         @since 2.9.0
      */
     virtual bool SetHint(const wxString& hint);
@@ -492,7 +524,7 @@ public:
         0) by this function.
 
         Note that, unlike most other functions changing the controls values,
-        this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid
+        this function generates a @c wxEVT_TEXT event. To avoid
         this you can use ChangeValue() instead.
 
         @param value