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.
  19     wxFILTER_ASCII,
  20
  21     /// Non-alpha characters are filtered out.
  22     wxFILTER_ALPHA,
  23
  24     /// Non-alphanumeric characters are filtered out.
  25     wxFILTER_ALPHANUMERIC,
  26
  27     /// Non-numeric characters are filtered out.
  28     wxFILTER_NUMERIC,
  29
  30     /// Use an include list. The validator checks if the user input is on
  31     /// the list, complaining if not. See wxTextValidator::SetIncludes().
  32     wxFILTER_INCLUDE_LIST,
  33
  34     /// Use an exclude list. The validator checks if the user input is on
  35     /// the list, complaining if it is. See wxTextValidator::SetExcludes().
  36     wxFILTER_EXCLUDE_LIST,
  37
  38     /// Use an include list. The validator checks if each input character is
  39     /// in the list (one character per list element), complaining if not.
  40     /// See wxTextValidator::SetIncludes().
  41     wxFILTER_INCLUDE_CHAR_LIST,
  42
  43     /// Use an include list. The validator checks if each input character is
  44     /// in the list (one character per list element), complaining if it is.
  45     /// See wxTextValidator::SetExcludes().
  46     wxFILTER_EXCLUDE_CHAR_LIST
  47 };
  48
  49 /**
  50     @class wxTextValidator
  51
  52     wxTextValidator validates text controls, providing a variety of filtering
  53     behaviours.
  54
  55     For more information, please see @ref overview_validator.
  56
  57     @library{wxcore}
  58     @category{validator}
  59
  60     @see @ref overview_validator, wxValidator, wxGenericValidator
  61 */
  62 class wxTextValidator : public wxValidator
  63 {
  64 public:
  65     /**
  66         Default constructor.
  67     */
  68     wxTextValidator(const wxTextValidator& validator);
  69
  70     /**
  71         Constructor taking a style and optional pointer to a wxString variable.
  72
  73         @param style
  74             One of the ::wxTextValidatorStyle styles.
  75         @param valPtr
  76             A pointer to a wxString variable that contains the value. This
  77             variable should have a lifetime equal to or longer than the
  78             validator lifetime (which is usually determined by the lifetime of
  79             the window).
  80     */
  81     wxTextValidator(wxTextValidatorStyle style = wxFILTER_NONE, wxString* valPtr = NULL);
  82
  83     /**
  84         Clones the text validator using the copy constructor.
  85     */
  86     virtual wxObject* Clone() const;
  87
  88     /**
  89         Returns a reference to the exclude list (the list of invalid values).
  90     */
  91     wxArrayString& GetExcludes();
  92
  93     /**
  94         Returns a reference to the include list (the list of valid values).
  95     */
  96     wxArrayString& GetIncludes();
  97
  98     /**
  99         Returns the validator style.
 100     */
 101     wxTextValidatorStyle GetStyle() const;
 102
 103     /**
 104         Receives character input from the window and filters it according to
 105         the current validator style.
 106     */
 107     void OnChar(wxKeyEvent& event);
 108
 109     /**
 110         Sets the exclude list (invalid values for the user input).
 111     */
 112     void SetExcludes(const wxArrayString& stringList);
 113
 114     /**
 115         Sets the include list (valid values for the user input).
 116     */
 117     void SetIncludes(const wxArrayString& stringList);
 118
 119     /**
 120         Sets the validator style.
 121     */
 122     void SetStyle(wxTextValidatorStyle style);
 123
 124     /**
 125         Transfers the value in the text control to the string.
 126     */
 127     virtual bool TransferFromWindow();
 128
 129     /**
 130         Transfers the string value to the text control.
 131     */
 132     virtual bool TransferToWindow();
 133
 134     /**
 135         Validates the window contents against the include or exclude lists,
 136         depending on the validator style.
 137     */
 138     virtual bool Validate(wxWindow* parent);
 139 };
 140