interface/valtext.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        valtext.h
   3 // Purpose:     documentation for wxTextValidator class
   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_validatoroverview "Validator
  17     overview".
  18
  19     @library{wxcore}
  20     @category{validator}
  21
  22     @seealso
  23     @ref overview_validatoroverview "Validator overview", wxValidator,
  24     wxGenericValidator
  25 */
  26 class wxTextValidator : public wxValidator
  27 {
  28 public:
  29     //@{
  30     /**
  31         Constructor, taking a style and optional pointer to a wxString variable.
  32
  33         @param style
  34         A bitlist of flags, which can be:
  35
  36
  37         wxFILTER_NONE
  38
  39
  40         No filtering takes place.
  41
  42         wxFILTER_ASCII
  43
  44
  45         Non-ASCII characters are filtered out.
  46
  47         wxFILTER_ALPHA
  48
  49
  50         Non-alpha characters are filtered out.
  51
  52         wxFILTER_ALPHANUMERIC
  53
  54
  55         Non-alphanumeric characters are filtered out.
  56
  57         wxFILTER_NUMERIC
  58
  59
  60         Non-numeric characters are filtered out.
  61
  62         wxFILTER_INCLUDE_LIST
  63
  64
  65         Use an include list. The validator
  66         checks if the user input is on the list, complaining if not. See
  67         SetIncludes().
  68
  69         wxFILTER_EXCLUDE_LIST
  70
  71
  72         Use an exclude list. The validator
  73         checks if the user input is on the list, complaining if it is. See
  74         SetExcludes().
  75
  76         wxFILTER_INCLUDE_CHAR_LIST
  77
  78
  79         Use an include list. The validator
  80         checks if each input character is in the list (one character per list element),
  81         complaining if not.
  82         See SetIncludes().
  83
  84         wxFILTER_EXCLUDE_CHAR_LIST
  85
  86
  87         Use an include list. The validator
  88         checks if each input character is in the list (one character per list element),
  89         complaining if it is.
  90         See SetExcludes().
  91
  92         @param valPtr
  93         A pointer to a wxString variable that contains the value. This variable
  94         should have a lifetime equal to or longer than the validator lifetime (which is
  95         usually
  96         determined by the lifetime of the window).
  97     */
  98     wxTextValidator(const wxTextValidator& validator);
  99     wxTextValidator(long style = wxFILTER_NONE,
 100                     wxString* valPtr = @NULL);
 101     //@}
 102
 103     /**
 104         Clones the text validator using the copy constructor.
 105     */
 106     virtual wxValidator* Clone();
 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();
 122
 123     /**
 124         Receives character input from the window and filters it according to the
 125         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         Sets the include list (valid values for the user input).
 136     */
 137     void SetIncludes(const wxArrayString& stringList);
 138
 139     /**
 140         Sets the validator style.
 141     */
 142     void SetStyle(long style);
 143
 144     /**
 145         Transfers the value in the text control to the string.
 146     */
 147     virtual bool TransferFromWindow();
 148
 149     /**
 150         Transfers the string value to the text control.
 151     */
 152     virtual bool TransferToWindow();
 153
 154     /**
 155         Validates the window contents against the include or exclude lists, depending
 156         on the validator style.
 157     */
 158     virtual bool Validate(wxWindow* parent);
 159 };