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     Here is a simple example of a custom completer that completes the names of
  25     some chess pieces. Of course, as the total list here has only four items it
  26     would have been much simpler to just specify the array containing all the
  27     completions in this example but the same approach could be used when the
  28     total number of completions is much higher provided the number of
  29     possibilities for each word is still relatively small:
  30     @code
  31     class MyTextCompleter : public wxTextCompleter
  32     {
  33     public:
  34         virtual void GetCompletions(const wxString& prefix, wxArrayString& res)
  35         {
  36             const wxString firstWord = prefix.BeforeFirst(' ');
  37             if ( firstWord == "white" )
  38             {
  39                 res.push_back("white pawn");
  40                 res.push_back("white rook");
  41             }
  42             else if ( firstWord == "black" )
  43             {
  44                 res.push_back("black king");
  45                 res.push_back("black queen");
  46             }
  47             else
  48             {
  49                 res.push_back("white");
  50                 res.push_back("black");
  51             }
  52         }
  53     };
  54     ...
  55     wxTextCtrl *text = ...;
  56     text->AutoComplete(new MyTextCompleter);
  57     @endcode
  58
  59     @library{wxcore}
  60
  61     @since 2.9.2
  62 */
  63 class wxTextCompleter
  64 {
  65 public:
  66     /**
  67         Pure virtual method returning all possible completions for the given
  68         prefix.
  69
  70         The custom completer should examine the provided prefix and return all
  71         the possible completions for it in the output array @a res.
  72
  73         Please notice that the returned values should start with the prefix,
  74         otherwise they will be simply ignored, making adding them to the array
  75         in the first place useless.
  76
  77         Notice that this function may be called from thread other than main one
  78         (this is currently always the case under MSW) so care should be taken
  79         if it needs to access any shared data.
  80
  81         @param prefix
  82             The possibly empty prefix that the user had already entered.
  83         @param res
  84             Initially empty array that should be filled with all possible
  85             completions (possibly none if there are no valid possibilities
  86             starting with the given prefix).
  87      */
  88     virtual void GetCompletions(const wxString& prefix, wxArrayString& res) = 0;
  89 };