X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/526954c5968baa29218c994ec48e476ae2bd4b9f..1ec4e9c2b72a01a7ba7da569e0f8d04a81aaba10:/interface/wx/textentry.h

diff --git a/interface/wx/textentry.h b/interface/wx/textentry.h
index a7110f592a..89fdaf5541 100644
--- 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
 
@@ -46,8 +53,8 @@ public:
         Call this function to enable auto-completion of the text typed in a
         single-line text control using the given @a choices.
 
-        Notice that currently this function is only implemented in wxGTK2 and
-        wxMSW ports and does nothing under the other platforms.
+        Notice that currently this function is only implemented in wxGTK2,
+        wxMSW and wxOSX/Cocoa ports and does nothing under the other platforms.
 
         @since 2.9.0
 
@@ -58,13 +65,47 @@ public:
 
         @see AutoCompleteFileNames()
     */
-    virtual bool AutoComplete(const wxArrayString& choices);
+    bool AutoComplete(const wxArrayString& choices);
+
+    /**
+        Enable auto-completion using the provided completer object.
+
+        This method should be used instead of AutoComplete() overload taking
+        the array of possible completions if the total number of strings is too
+        big as it allows to return the completions dynamically, depending on
+        the text already entered by user and so is more efficient.
+
+        The specified @a completer object will be used to retrieve the list of
+        possible completions for the already entered text and will be deleted
+        by wxTextEntry itself when it's not needed any longer.
+
+        Notice that you need to include @c wx/textcompleter.h in order to
+        define your class inheriting from wxTextCompleter.
+
+        Currently this method is only implemented in wxMSW and wxOSX/Cocoa.
+
+        @since 2.9.2
+
+        @param completer
+            The object to be used for generating completions if non-@NULL. If
+            it is @NULL, auto-completion is disabled. The wxTextEntry object
+            takes ownership of this pointer and will delete it in any case
+            (i.e. even if this method returns @false).
+
+        @return
+            @true if the auto-completion was enabled or @false if the operation
+            failed, typically because auto-completion is not supported by the
+            current platform.
+
+        @see wxTextCompleter
+     */
+    bool AutoComplete(wxTextCompleter *completer);
 
     /**
         Call this function to enable auto-completion of the text typed in a
         single-line text control using all valid file system paths.
 
-        Notice that currently this function is only implemented in wxGTK2 port
+        Notice that currently this function is only implemented in wxMSW port
         and does nothing under the other platforms.
 
         @since 2.9.0
@@ -76,7 +117,28 @@ public:
 
         @see AutoComplete()
     */
-    virtual bool AutoCompleteFileNames();
+    bool AutoCompleteFileNames();
+
+    /**
+        Call this function to enable auto-completion of the text using the file
+        system directories.
+
+        Unlike AutoCompleteFileNames() which completes both file names and
+        directories, this function only completes the directory names.
+
+        Notice that currently this function is only implemented in wxMSW port
+        and does nothing under the other platforms.
+
+        @since 2.9.3
+
+        @return
+            @true if the auto-completion was enabled or @false if the operation
+            failed, typically because auto-completion is not supported by the
+            current platform.
+
+        @see AutoComplete()
+     */
+    bool AutoCompleteDirectories();
 
     /**
         Returns @true if the selection can be copied to the clipboard.
@@ -149,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().
+
+        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.
 
-        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.
+        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
     */
@@ -358,6 +429,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.
 
@@ -375,9 +453,23 @@ public:
         Notice that hints are known as <em>cue banners</em> under MSW or
         <em>placeholder strings</em> under OS X.
 
+        @remarks For the platforms without native hints support (and currently
+            only the MSW port does have it and even there it is only used under
+            Windows Vista and later only), the implementation has several known
+            limitations. Notably, the hint display will not be properly updated
+            if you change wxTextEntry contents programmatically when the hint
+            is displayed using methods other than SetValue() or ChangeValue()
+            or others which use them internally (e.g. Clear()). In other words,
+            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 void SetHint(const wxString& hint);
+    virtual bool SetHint(const wxString& hint);
 
     /**
         Returns the current hint string.