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