interface/wx/valtext.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        valtext.h
   3 // Purpose:     interface of wxTextValidator
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     Styles used by wxTextValidator.
  12 */
  13 enum wxTextValidatorStyle
  14 {
  15     /// No filtering takes place.
  16     wxFILTER_NONE,
  17
  18     /// Non-ASCII characters are filtered out. See wxString::IsAscii.
  19     wxFILTER_ASCII,
  20
  21     /// Non-alpha characters are filtered out.
  22     /// Uses the wxWidgets wrapper for the standard CRT function @c isalpha
  23     /// (which is locale-dependent) on all characters of the string.
  24     wxFILTER_ALPHA,
  25
  26     /// Non-alphanumeric characters are filtered out.
  27     /// Uses the wxWidgets wrapper for the standard CRT function @c isalnum
  28     /// (which is locale-dependent) on all characters of the string.
  29     wxFILTER_ALPHANUMERIC,
  30
  31     /// Non-numeric characters are filtered out.
  32     /// Uses the wxWidgets wrapper for the standard CRT function @c isdigit
  33     /// (which is locale-dependent) on all characters of the string.
  34     wxFILTER_SIMPLE_NUMBER,
  35
  36     /// Non-numeric characters are filtered out.
  37     /// Works like @c wxFILTER_SIMPLE_NUMBER but allows also decimal points,
  38     /// minus/plus signs and the 'e' or 'E' character to input exponents.
  39     /// Note that this is not the same behaviour of wxString::IsNumber().
  40     wxFILTER_NUMERIC,
  41
  42     /// Use an include list. The validator checks if the user input is on
  43     /// the list, complaining if not. See wxTextValidator::SetIncludes().
  44     wxFILTER_INCLUDE_LIST,
  45
  46     /// Use an exclude list. The validator checks if the user input is on
  47     /// the list, complaining if it is. See wxTextValidator::SetExcludes().
  48     wxFILTER_EXCLUDE_LIST,
  49
  50     /// Use an include list. The validator checks if each input character is
  51     /// in the list (one character per list element), complaining if not.
  52     /// See wxTextValidator::SetCharIncludes().
  53     wxFILTER_INCLUDE_CHAR_LIST,
  54
  55     /// Use an exclude list. The validator checks if each input character is
  56     /// in the list (one character per list element), complaining if it is.
  57     /// See wxTextValidator::SetCharExcludes().
  58     wxFILTER_EXCLUDE_CHAR_LIST
  59 };
  60
  61 /**
  62     @class wxTextValidator
  63
  64     wxTextValidator validates text controls, providing a variety of filtering
  65     behaviours.
  66
  67     For more information, please see @ref overview_validator.
  68
  69     @library{wxcore}
  70     @category{validator}
  71
  72     @see @ref overview_validator, wxValidator, wxGenericValidator
  73 */
  74 class wxTextValidator : public wxValidator
  75 {
  76 public:
  77     /**
  78         Default constructor.
  79     */
  80     wxTextValidator(const wxTextValidator& validator);
  81
  82     /**
  83         Constructor taking a style and optional pointer to a wxString variable.
  84
  85         @param style
  86             One of the ::wxTextValidatorStyle styles.
  87         @param valPtr
  88             A pointer to a wxString variable that contains the value. This
  89             variable should have a lifetime equal to or longer than the
  90             validator lifetime (which is usually determined by the lifetime of
  91             the window).
  92     */
  93     wxTextValidator(wxTextValidatorStyle style = wxFILTER_NONE, wxString* valPtr = NULL);
  94
  95     /**
  96         Clones the text validator using the copy constructor.
  97     */
  98     virtual wxObject* Clone() const;
  99
 100     /**
 101         Returns a reference to the exclude list (the list of invalid values).
 102     */
 103     wxArrayString& GetExcludes();
 104
 105     /**
 106         Returns a reference to the include list (the list of valid values).
 107     */
 108     wxArrayString& GetIncludes();
 109
 110     /**
 111         Returns the validator style.
 112     */
 113     wxTextValidatorStyle GetStyle() const;
 114
 115     /**
 116         Receives character input from the window and filters it according to
 117         the current validator style.
 118     */
 119     void OnChar(wxKeyEvent& event);
 120
 121     /**
 122         Sets the exclude list (invalid values for the user input).
 123     */
 124     void SetExcludes(const wxArrayString& stringList);
 125
 126     /**
 127         Breaks the given @a chars strings in single characters and sets the
 128         internal wxArrayString used to store the "excluded" characters
 129         (see SetExcludes()).
 130
 131         This function is mostly useful when @c wxFILTER_EXCLUDE_CHAR_LIST was used.
 132     */
 133     void SetCharExcludes(const wxString& chars);
 134
 135     /**
 136         Sets the include list (valid values for the user input).
 137     */
 138     void SetIncludes(const wxArrayString& stringList);
 139
 140     /**
 141         Breaks the given @a chars strings in single characters and sets the
 142         internal wxArrayString used to store the "included" characters
 143         (see SetIncludes()).
 144
 145         This function is mostly useful when @c wxFILTER_INCLUDE_CHAR_LIST was used.
 146     */
 147     void SetCharIncludes(const wxString& chars);
 148
 149     /**
 150         Sets the validator style.
 151     */
 152     void SetStyle(wxTextValidatorStyle style);
 153
 154     /**
 155         Transfers the value in the text control to the string.
 156     */
 157     virtual bool TransferFromWindow();
 158
 159     /**
 160         Transfers the string value to the text control.
 161     */
 162     virtual bool TransferToWindow();
 163
 164     /**
 165         Validates the window contents against the include or exclude lists,
 166         depending on the validator style.
 167     */
 168     virtual bool Validate(wxWindow* parent);
 169 };
 170