/////////////////////////////////////////////////////////////////////////////
// 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.

    When inheriting from this class you need to implement its two pure virtual
    methods. This allows to return the results incrementally and may or not be
    convenient depending on where do they come from. If you prefer to return
    all the completions at once, you should inherit from wxTextCompleterSimple
    instead.

    @since 2.9.2
 */
class wxTextCompleter
{
public:
    /**
        Function called to start iteration over the completions for the given
        prefix.

        This function could start a database query, for example, if the results
        are read from a database.

        Notice that under some platforms (currently MSW only) it is called from
        another thread context and so the appropriate synchronization mechanism
        should be used to access any data also used by the main UI thread.

        @param prefix
            The prefix for which completions are to be generated.
        @return
            @true to continue with calling GetNext() or @false to indicate that
            there are no matches and GetNext() shouldn't be called at all.
     */
    virtual bool Start(const wxString& prefix) = 0;

    /**
        Called to retrieve the next completion.

        All completions returned by this function should start with the prefix
        passed to the last call to Start().

        Notice that, as Start(), this method is called from a worker thread
        context under MSW.

        @return
            The next completion or an empty string to indicate that there are
            no more of them.
     */
    virtual wxString GetNext() = 0;
};

/**
    A simpler base class for custom completer objects.

    This class may be simpler to use than the base wxTextCompleter as it allows
    to implement only a single virtual method instead of two of them (at the
    price of storing all completions in a temporary array).

    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 wxTextCompleterSimple
    {
    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 wxTextCompleterSimple : public 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.

        Notice that this function may be called from thread other than main one
        (this is currently always the case under MSW) so the appropriate
        synchronization mechanism should be used to protect the shared data.

        @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;
};