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