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