Add support for dynamic auto-completion in wxTextEntry.

Add wxTextCompleter class which allows to return the possible completions
dynamically and wxTextCompleter::AutoComplete() overload using it. So far this
is only implemented for wxMSW.

Also fix calling wxTextEntry::AutoComplete(wxArrayString) multiple times under
MSW, this didn't correctly update the list of shown completions before.

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

interface/wx/textcompleter.h

@@ -0,0 +1,85 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        wx/textcompleter.h
+// Purpose:     interface of wxTextCompleter
+// Author:      Vadim Zeitlin
+// Created:     2011-04-13
+// RCS-ID:      $Id$
+// Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwindows.org>
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+    @class wxTextCompleter
+
+    Base class for custom text completer objects.
+
+    Custom completer objects used with wxTextEntry::AutoComplete() must derive
+    from this class and implement its pure virtual method returning the
+    completions. You would typically use a custom completer when the total
+    number of completions is too big for performance to be acceptable if all of
+    them need to be returned at once but if they can be generated
+    hierarchically, i.e. only the first component initially, then the second
+    one after the user finished entering the first one and so on.
+
+    Here is a simple example of a custom completer that completes the names of
+    some chess pieces. Of course, as the total list here has only four items it
+    would have been much simpler to just specify the array containing all the
+    completions in this example but the same approach could be used when the
+    total number of completions is much higher provided the number of
+    possibilities for each word is still relatively small:
+    @code
+    class MyTextCompleter : public wxTextCompleter
+    {
+    public:
+        virtual void GetCompletions(const wxString& prefix, wxArrayString& res)
+        {
+            const wxString firstWord = prefix.BeforeFirst(' ');
+            if ( firstWord == "white" )
+            {
+                res.push_back("white pawn");
+                res.push_back("white rook");
+            }
+            else if ( firstWord == "black" )
+            {
+                res.push_back("black king");
+                res.push_back("black queen");
+            }
+            else
+            {
+                res.push_back("white");
+                res.push_back("black");
+            }
+        }
+    };
+    ...
+    wxTextCtrl *text = ...;
+    text->AutoComplete(new MyTextCompleter);
+    @endcode
+
+    @library{wxcore}
+
+    @since 2.9.2
+*/
+class wxTextCompleter
+{
+public:
+    /**
+        Pure virtual method returning all possible completions for the given
+        prefix.
+
+        The custom completer should examine the provided prefix and return all
+        the possible completions for it in the output array @a res.
+
+        Please notice that the returned values should start with the prefix,
+        otherwise they will be simply ignored, making adding them to the array
+        in the first place useless.
+
+        @param prefix
+            The possibly empty prefix that the user had already entered.
+        @param res
+            Initially empty array that should be filled with all possible
+            completions (possibly none if there are no valid possibilities
+            starting with the given prefix).
+     */
+    virtual void GetCompletions(const wxString& prefix, wxArrayString& res) = 0;
+};

interface/wx/textentry.h

@@ -60,6 +60,40 @@ public:
     */
     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 port.
+
+        @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.