interface/valtext.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        valtext.h
   3 // Purpose:     documentation for wxTextValidator class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTextValidator
  11     @wxheader{valtext.h}
  12
  13     wxTextValidator validates text controls, providing a variety of filtering
  14     behaviours.
  15
  16     For more information, please see @ref overview_validatoroverview "Validator
  17     overview".
  18
  19     @library{wxcore}
  20     @category{validator}
  21
  22     @seealso
  23     @ref overview_validatoroverview "Validator overview", wxValidator,
  24     wxGenericValidator
  25 */
  26 class wxTextValidator : public wxValidator
  27 {
  28 public:
  29     //@{
  30     /**
  31         Constructor, taking a style and optional pointer to a wxString variable.
  32
  33         @param style
  34             A bitlist of flags, which can be:
  35
  36
  37
  38
  39
  40
  41
  42             wxFILTER_NONE
  43
  44
  45
  46
  47             No filtering takes place.
  48
  49
  50
  51
  52
  53             wxFILTER_ASCII
  54
  55
  56
  57
  58             Non-ASCII characters are filtered out.
  59
  60
  61
  62
  63
  64             wxFILTER_ALPHA
  65
  66
  67
  68
  69             Non-alpha characters are filtered out.
  70
  71
  72
  73
  74
  75             wxFILTER_ALPHANUMERIC
  76
  77
  78
  79
  80             Non-alphanumeric characters are filtered out.
  81
  82
  83
  84
  85
  86             wxFILTER_NUMERIC
  87
  88
  89
  90
  91             Non-numeric characters are filtered out.
  92
  93
  94
  95
  96
  97             wxFILTER_INCLUDE_LIST
  98
  99
 100
 101
 102             Use an include list. The validator
 103             checks if the user input is on the list, complaining if not. See
 104             SetIncludes().
 105
 106
 107
 108
 109
 110             wxFILTER_EXCLUDE_LIST
 111
 112
 113
 114
 115             Use an exclude list. The validator
 116             checks if the user input is on the list, complaining if it is. See
 117             SetExcludes().
 118
 119
 120
 121
 122
 123             wxFILTER_INCLUDE_CHAR_LIST
 124
 125
 126
 127
 128             Use an include list. The validator
 129             checks if each input character is in the list (one character per list
 130         element), complaining if not.
 131             See SetIncludes().
 132
 133
 134
 135
 136
 137             wxFILTER_EXCLUDE_CHAR_LIST
 138
 139
 140
 141
 142             Use an include list. The validator
 143             checks if each input character is in the list (one character per list
 144         element), complaining if it is.
 145             See SetExcludes().
 146         @param valPtr
 147             A pointer to a wxString variable that contains the value. This variable
 148             should have a lifetime equal to or longer than the validator lifetime
 149         (which is usually
 150             determined by the lifetime of the window).
 151     */
 152     wxTextValidator(const wxTextValidator& validator);
 153     wxTextValidator(long style = wxFILTER_NONE,
 154                     wxString* valPtr = NULL);
 155     //@}
 156
 157     /**
 158         Clones the text validator using the copy constructor.
 159     */
 160     virtual wxValidator* Clone();
 161
 162     /**
 163         Returns a reference to the exclude list (the list of invalid values).
 164     */
 165     wxArrayString GetExcludes();
 166
 167     /**
 168         Returns a reference to the include list (the list of valid values).
 169     */
 170     wxArrayString GetIncludes();
 171
 172     /**
 173         Returns the validator style.
 174     */
 175     long GetStyle();
 176
 177     /**
 178         Receives character input from the window and filters it according to the
 179         current validator style.
 180     */
 181     void OnChar(wxKeyEvent& event);
 182
 183     /**
 184         Sets the exclude list (invalid values for the user input).
 185     */
 186     void SetExcludes(const wxArrayString& stringList);
 187
 188     /**
 189         Sets the include list (valid values for the user input).
 190     */
 191     void SetIncludes(const wxArrayString& stringList);
 192
 193     /**
 194         Sets the validator style.
 195     */
 196     void SetStyle(long style);
 197
 198     /**
 199         Transfers the value in the text control to the string.
 200     */
 201     virtual bool TransferFromWindow();
 202
 203     /**
 204         Transfers the string value to the text control.
 205     */
 206     virtual bool TransferToWindow();
 207
 208     /**
 209         Validates the window contents against the include or exclude lists, depending
 210         on the validator style.
 211     */
 212     virtual bool Validate(wxWindow* parent);
 213 };