interface/wx/textcompleter.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/textcompleter.h
   3 // Purpose:     interface of wxTextCompleter
   4 // Author:      Vadim Zeitlin
   5 // Created:     2011-04-13
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwindows.org>
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     @class wxTextCompleter
  13
  14     Base class for custom text completer objects.
  15
  16     Custom completer objects used with wxTextEntry::AutoComplete() must derive
  17     from this class and implement its pure virtual method returning the
  18     completions. You would typically use a custom completer when the total
  19     number of completions is too big for performance to be acceptable if all of
  20     them need to be returned at once but if they can be generated
  21     hierarchically, i.e. only the first component initially, then the second
  22     one after the user finished entering the first one and so on.
  23
  24     When inheriting from this class you need to implement its two pure virtual
  25     methods. This allows to return the results incrementally and may or not be
  26     convenient depending on where do they come from. If you prefer to return
  27     all the completions at once, you should inherit from wxTextCompleterSimple
  28     instead.
  29
  30     @since 2.9.2
  31  */
  32 class wxTextCompleter
  33 {
  34 public:
  35     /**
  36         Function called to start iteration over the completions for the given
  37         prefix.
  38
  39         This function could start a database query, for example, if the results
  40         are read from a database.
  41
  42         Notice that under some platforms (currently MSW only) it is called from
  43         another thread context and so the appropriate synchronization mechanism
  44         should be used to access any data also used by the main UI thread.
  45
  46         @param prefix
  47             The prefix for which completions are to be generated.
  48         @return
  49             @true to continue with calling GetNext() or @false to indicate that
  50             there are no matches and GetNext() shouldn't be called at all.
  51      */
  52     virtual bool Start(const wxString& prefix) = 0;
  53
  54     /**
  55         Called to retrieve the next completion.
  56
  57         All completions returned by this function should start with the prefix
  58         passed to the last call to Start().
  59
  60         Notice that, as Start(), this method is called from a worker thread
  61         context under MSW.
  62
  63         @return
  64             The next completion or an empty string to indicate that there are
  65             no more of them.
  66      */
  67     virtual wxString GetNext() = 0;
  68 };
  69
  70 /**
  71     A simpler base class for custom completer objects.
  72
  73     This class may be simpler to use than the base wxTextCompleter as it allows
  74     to implement only a single virtual method instead of two of them (at the
  75     price of storing all completions in a temporary array).
  76
  77     Here is a simple example of a custom completer that completes the names of
  78     some chess pieces. Of course, as the total list here has only four items it
  79     would have been much simpler to just specify the array containing all the
  80     completions in this example but the same approach could be used when the
  81     total number of completions is much higher provided the number of
  82     possibilities for each word is still relatively small:
  83     @code
  84     class MyTextCompleter : public wxTextCompleterSimple
  85     {
  86     public:
  87         virtual void GetCompletions(const wxString& prefix, wxArrayString& res)
  88         {
  89             const wxString firstWord = prefix.BeforeFirst(' ');
  90             if ( firstWord == "white" )
  91             {
  92                 res.push_back("white pawn");
  93                 res.push_back("white rook");
  94             }
  95             else if ( firstWord == "black" )
  96             {
  97                 res.push_back("black king");
  98                 res.push_back("black queen");
  99             }
 100             else
 101             {
 102                 res.push_back("white");
 103                 res.push_back("black");
 104             }
 105         }
 106     };
 107     ...
 108     wxTextCtrl *text = ...;
 109     text->AutoComplete(new MyTextCompleter);
 110     @endcode
 111
 112     @library{wxcore}
 113
 114     @since 2.9.2
 115 */
 116 class wxTextCompleterSimple : public wxTextCompleter
 117 {
 118 public:
 119     /**
 120         Pure virtual method returning all possible completions for the given
 121         prefix.
 122
 123         The custom completer should examine the provided prefix and return all
 124         the possible completions for it in the output array @a res.
 125
 126         Please notice that the returned values should start with the prefix,
 127         otherwise they will be simply ignored, making adding them to the array
 128         in the first place useless.
 129
 130         Notice that this function may be called from thread other than main one
 131         (this is currently always the case under MSW) so the appropriate
 132         synchronization mechanism should be used to protect the shared data.
 133
 134         @param prefix
 135             The possibly empty prefix that the user had already entered.
 136         @param res
 137             Initially empty array that should be filled with all possible
 138             completions (possibly none if there are no valid possibilities
 139             starting with the given prefix).
 140      */
 141     virtual void GetCompletions(const wxString& prefix, wxArrayString& res) = 0;
 142 };