2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Name: valtext.h
|
2008-03-10 11:24:38 -04:00
|
|
|
// Purpose: interface of wxTextValidator
|
2008-03-08 08:52:38 -05:00
|
|
|
// Author: wxWidgets team
|
2010-07-13 09:29:13 -04:00
|
|
|
// Licence: wxWindows licence
|
2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
2009-01-09 07:43:20 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Styles used by wxTextValidator.
|
2009-02-03 16:21:47 -05:00
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
Notice that wxFILTER_EXCLUDE[_CHAR]_LIST pair can be used to document the
|
|
|
|
purpose of the validator only and are not enforced in the implementation of
|
|
|
|
the wxTextValidator. Therefore, calling the corresponding member functions:
|
|
|
|
wxTextValidator::{SetExcludes,SetCharExcludes}(), is enough to create the
|
|
|
|
desired validator.
|
2009-01-09 07:43:20 -05:00
|
|
|
*/
|
|
|
|
enum wxTextValidatorStyle
|
|
|
|
{
|
|
|
|
/// No filtering takes place.
|
|
|
|
wxFILTER_NONE,
|
|
|
|
|
2009-02-03 16:21:47 -05:00
|
|
|
/// Empty strings are filtered out.
|
|
|
|
/// If this style is not specified then empty strings are accepted
|
|
|
|
/// only if they pass the other checks (if you use more than one wxTextValidatorStyle).
|
|
|
|
wxFILTER_EMPTY,
|
|
|
|
|
2009-01-31 16:27:27 -05:00
|
|
|
/// Non-ASCII characters are filtered out. See wxString::IsAscii.
|
2009-01-09 07:43:20 -05:00
|
|
|
wxFILTER_ASCII,
|
|
|
|
|
|
|
|
/// Non-alpha characters are filtered out.
|
2009-01-31 16:27:27 -05:00
|
|
|
/// Uses the wxWidgets wrapper for the standard CRT function @c isalpha
|
|
|
|
/// (which is locale-dependent) on all characters of the string.
|
2009-01-09 07:43:20 -05:00
|
|
|
wxFILTER_ALPHA,
|
|
|
|
|
|
|
|
/// Non-alphanumeric characters are filtered out.
|
2009-01-31 16:27:27 -05:00
|
|
|
/// Uses the wxWidgets wrapper for the standard CRT function @c isalnum
|
|
|
|
/// (which is locale-dependent) on all characters of the string.
|
2018-12-31 18:55:14 -05:00
|
|
|
/// Equivalent to wxFILTER_ALPHA combined with wxFILTER_DIGITS or
|
|
|
|
/// wxFILTER_XDIGITS, or with both of them.
|
2009-01-09 07:43:20 -05:00
|
|
|
wxFILTER_ALPHANUMERIC,
|
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
/// Non-digit characters are filtered out.
|
2009-01-31 16:27:27 -05:00
|
|
|
/// Uses the wxWidgets wrapper for the standard CRT function @c isdigit
|
|
|
|
/// (which is locale-dependent) on all characters of the string.
|
2009-02-03 16:21:47 -05:00
|
|
|
wxFILTER_DIGITS,
|
2009-01-31 16:27:27 -05:00
|
|
|
|
|
|
|
/// Non-numeric characters are filtered out.
|
2010-10-24 19:03:43 -04:00
|
|
|
/// Works like @c wxFILTER_DIGITS but allows also decimal points,
|
2009-01-31 16:27:27 -05:00
|
|
|
/// minus/plus signs and the 'e' or 'E' character to input exponents.
|
|
|
|
/// Note that this is not the same behaviour of wxString::IsNumber().
|
2009-01-09 07:43:20 -05:00
|
|
|
wxFILTER_NUMERIC,
|
|
|
|
|
|
|
|
/// Use an include list. The validator checks if the user input is on
|
|
|
|
/// the list, complaining if not. See wxTextValidator::SetIncludes().
|
|
|
|
wxFILTER_INCLUDE_LIST,
|
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
/// Use an include char list.
|
|
|
|
/// Characters in the include char list will be allowed to be in the
|
|
|
|
/// user input. See wxTextValidator::SetCharIncludes().
|
|
|
|
/// If this style is set with one or more of the following styles:
|
|
|
|
/// wxFILTER_ASCII, wxFILTER_ALPHA, wxFILTER_ALPHANUMERIC, wxFILTER_DIGITS,
|
|
|
|
/// wxFILTER_XDIGITS, wxFILTER_NUMERIC it just extends the character class
|
|
|
|
/// denoted by the aforementioned styles with those specified in the include
|
|
|
|
/// char list. If set alone, then the charactes allowed to be in the user input
|
|
|
|
/// are restricted to those, and only those, present in the include char list.
|
2009-01-09 07:43:20 -05:00
|
|
|
wxFILTER_INCLUDE_CHAR_LIST,
|
|
|
|
|
2009-02-03 16:21:47 -05:00
|
|
|
/// Use an exclude list. The validator checks if the user input is on
|
|
|
|
/// the list, complaining if it is. See wxTextValidator::SetExcludes().
|
|
|
|
wxFILTER_EXCLUDE_LIST,
|
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
/// Use an exclude char list.
|
|
|
|
/// Characters in the exclude char list won't be allowed to be in the
|
|
|
|
/// user input. See wxTextValidator::SetCharExcludes().
|
|
|
|
wxFILTER_EXCLUDE_CHAR_LIST,
|
|
|
|
|
|
|
|
/// Non-hexadecimal characters are filtered out.
|
|
|
|
/// Uses the wxWidgets wrapper for the standard CRT function @c isxdigit
|
|
|
|
/// (which is locale-dependent) on all characters of the string.
|
|
|
|
wxFILTER_XDIGITS,
|
|
|
|
|
|
|
|
/// A convenience flag for use with the other flags.
|
|
|
|
/// The space character is more often used with alphanumeric characters
|
|
|
|
/// which makes setting a flag more easier than calling SetCharIncludes(" ")
|
|
|
|
/// for that matter.
|
|
|
|
wxFILTER_SPACE
|
2009-01-09 07:43:20 -05:00
|
|
|
};
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxTextValidator
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
wxTextValidator validates text controls, providing a variety of filtering
|
|
|
|
behaviours.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-22 02:01:48 -04:00
|
|
|
For more information, please see @ref overview_validator.
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxcore}
|
|
|
|
@category{validator}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2011-01-19 05:48:28 -05:00
|
|
|
@see @ref overview_validator, wxValidator, wxGenericValidator,
|
|
|
|
wxIntegerValidator, wxFloatingPointValidator
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
class wxTextValidator : public wxValidator
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
2018-12-31 18:55:14 -05:00
|
|
|
Copy constructor.
|
2008-04-22 02:01:48 -04:00
|
|
|
*/
|
|
|
|
wxTextValidator(const wxTextValidator& validator);
|
2009-01-09 07:43:20 -05:00
|
|
|
|
2008-04-22 02:01:48 -04:00
|
|
|
/**
|
|
|
|
Constructor taking a style and optional pointer to a wxString variable.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 09:43:31 -05:00
|
|
|
@param style
|
2009-02-03 16:21:47 -05:00
|
|
|
One or more of the ::wxTextValidatorStyle styles. See SetStyle().
|
2008-03-08 09:43:31 -05:00
|
|
|
@param valPtr
|
2008-04-22 02:01:48 -04:00
|
|
|
A pointer to a wxString variable that contains the value. This
|
|
|
|
variable should have a lifetime equal to or longer than the
|
|
|
|
validator lifetime (which is usually determined by the lifetime of
|
|
|
|
the window).
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2009-02-03 16:21:47 -05:00
|
|
|
wxTextValidator(long style = wxFILTER_NONE, wxString* valPtr = NULL);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Clones the text validator using the copy constructor.
|
|
|
|
*/
|
2008-10-28 11:36:26 -04:00
|
|
|
virtual wxObject* Clone() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2018-12-31 18:55:14 -05:00
|
|
|
Returns a copy of the exclude char list (the list of invalid characters).
|
|
|
|
|
|
|
|
@since 3.1.3
|
|
|
|
*/
|
|
|
|
wxString GetCharExcludes() const;
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns a copy of the include char list (the list of additional valid characters).
|
|
|
|
|
|
|
|
@since 3.1.3
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2018-12-31 18:55:14 -05:00
|
|
|
wxString GetCharIncludes() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2018-12-31 18:55:14 -05:00
|
|
|
Returns a const reference to the exclude list (the list of invalid values).
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2018-12-31 18:55:14 -05:00
|
|
|
const wxArrayString& GetExcludes() const;
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns a const reference to the include list (the list of valid values).
|
|
|
|
*/
|
|
|
|
const wxArrayString& GetIncludes() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the validator style.
|
2009-02-05 13:50:43 -05:00
|
|
|
|
|
|
|
@see HasFlag()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2009-02-03 16:21:47 -05:00
|
|
|
long GetStyle() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
2009-02-05 13:50:43 -05:00
|
|
|
/**
|
|
|
|
Returns @true if the given @a style bit is set in the current style.
|
|
|
|
*/
|
|
|
|
bool HasFlag(wxTextValidatorStyle style) const;
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
2008-04-22 02:01:48 -04:00
|
|
|
Receives character input from the window and filters it according to
|
|
|
|
the current validator style.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
void OnChar(wxKeyEvent& event);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the exclude list (invalid values for the user input).
|
2018-12-31 18:55:14 -05:00
|
|
|
|
|
|
|
@note Beware that exclusion takes priority over inclusion.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
void SetExcludes(const wxArrayString& stringList);
|
|
|
|
|
2009-01-31 17:41:51 -05:00
|
|
|
/**
|
2018-12-31 18:55:14 -05:00
|
|
|
Sets the exclude char list (invalid characters for the user input).
|
2009-01-31 17:41:51 -05:00
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
@note Beware that exclusion takes priority over inclusion.
|
|
|
|
@note This function may cancel the effect of @c wxFILTER_SPACE if the passed
|
|
|
|
in string @a chars contains the @b space character.
|
2009-01-31 17:41:51 -05:00
|
|
|
*/
|
|
|
|
void SetCharExcludes(const wxString& chars);
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
Sets the include list (valid values for the user input).
|
2018-12-31 18:55:14 -05:00
|
|
|
|
|
|
|
@see IsIncluded()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
void SetIncludes(const wxArrayString& stringList);
|
|
|
|
|
2009-01-31 17:41:51 -05:00
|
|
|
/**
|
2018-12-31 18:55:14 -05:00
|
|
|
Sets the include char list (additional valid values for the user input).
|
2009-01-31 17:41:51 -05:00
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
@note Any explicitly excluded characters will still be excluded even if
|
|
|
|
they're part of @a chars.
|
2009-01-31 17:41:51 -05:00
|
|
|
*/
|
|
|
|
void SetCharIncludes(const wxString& chars);
|
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
/**
|
|
|
|
Adds @a exclude to the list of excluded values.
|
|
|
|
|
|
|
|
@note Beware that exclusion takes priority over inclusion.
|
|
|
|
|
|
|
|
@since 3.1.3
|
|
|
|
*/
|
|
|
|
void AddExclude(const wxString& exclude);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Adds @a include to the list of included values.
|
|
|
|
|
|
|
|
@note Any explicitly excluded characters will still be excluded.
|
|
|
|
|
|
|
|
@since 3.1.3
|
|
|
|
*/
|
|
|
|
void AddInclude(const wxString& include);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Adds @a chars to the list of excluded characters.
|
|
|
|
|
|
|
|
@note Beware that exclusion takes priority over inclusion.
|
|
|
|
|
|
|
|
@since 3.1.3
|
|
|
|
*/
|
|
|
|
void AddCharExcludes(const wxString& chars);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Adds @a chars to the list of included characters.
|
|
|
|
|
|
|
|
@note Any explicitly excluded characters will still be excluded even if
|
|
|
|
they're part of @a chars.
|
|
|
|
|
|
|
|
@since 3.1.3
|
|
|
|
*/
|
|
|
|
void AddCharIncludes(const wxString& chars);
|
|
|
|
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
2009-02-03 16:21:47 -05:00
|
|
|
Sets the validator style which must be a combination of one or more
|
|
|
|
of the ::wxTextValidatorStyle values.
|
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
Note that not all possible combinations make sense! Also, some
|
|
|
|
combinations have shorter and more idiomatic alternative, e.g.
|
|
|
|
@c wxFILTER_ALPHANUMERIC can be used instead of
|
|
|
|
@c wxFILTER_ALPHA|wxFILTER_DIGITS.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2009-02-03 16:21:47 -05:00
|
|
|
void SetStyle(long style);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Transfers the value in the text control to the string.
|
|
|
|
*/
|
|
|
|
virtual bool TransferFromWindow();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Transfers the string value to the text control.
|
|
|
|
*/
|
|
|
|
virtual bool TransferToWindow();
|
|
|
|
|
|
|
|
/**
|
2008-04-22 02:01:48 -04:00
|
|
|
Validates the window contents against the include or exclude lists,
|
|
|
|
depending on the validator style.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
virtual bool Validate(wxWindow* parent);
|
2009-02-05 13:50:43 -05:00
|
|
|
|
2018-12-31 18:55:14 -05:00
|
|
|
/**
|
|
|
|
Returns the error message if the contents of @a val are invalid
|
|
|
|
or the empty string if @a val is valid.
|
|
|
|
*/
|
|
|
|
virtual wxString IsValid(const wxString& val) const;
|
|
|
|
|
2009-02-05 13:50:43 -05:00
|
|
|
protected:
|
|
|
|
|
|
|
|
/**
|
2018-12-31 18:55:14 -05:00
|
|
|
Returns @true if the char @a c is allowed to be in the user input string.
|
|
|
|
Additional characters, set by SetCharIncludes() or AddCharIncludes() are
|
|
|
|
also considered.
|
|
|
|
|
|
|
|
@since 3.1.3
|
2009-02-05 13:50:43 -05:00
|
|
|
*/
|
2018-12-31 18:55:14 -05:00
|
|
|
bool IsCharIncluded(const wxUniChar& c) const;
|
2009-02-05 13:50:43 -05:00
|
|
|
|
|
|
|
/**
|
2018-12-31 18:55:14 -05:00
|
|
|
Returns @true if the char @a c is not allowed to be in the user input string.
|
|
|
|
(characters set by SetCharExcludes() or AddCharExcludes()).
|
|
|
|
|
|
|
|
@since 3.1.3
|
2009-02-05 13:50:43 -05:00
|
|
|
*/
|
2018-12-31 18:55:14 -05:00
|
|
|
bool IsCharExcluded(const wxUniChar& c) const;
|
2009-02-05 13:50:43 -05:00
|
|
|
|
|
|
|
/**
|
2018-12-31 18:55:14 -05:00
|
|
|
Returns @true if the string @a str is one of the includes strings set by
|
|
|
|
SetIncludes() or AddInclude().
|
|
|
|
|
|
|
|
Notice that unless wxFILTER_INCLUDE_LIST is specified (in which case the
|
|
|
|
validator will complain if the user input is not on the list), the list
|
|
|
|
will be ignored and won't participate in the validation process.
|
|
|
|
|
|
|
|
@since 3.1.3
|
2009-02-05 13:50:43 -05:00
|
|
|
*/
|
2018-12-31 18:55:14 -05:00
|
|
|
bool IsIncluded(const wxString& str) const;
|
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the string @a str is one of the excludes strings set by
|
|
|
|
SetExcludes() or AddExclude().
|
|
|
|
|
|
|
|
@since 3.1.3
|
|
|
|
*/
|
|
|
|
bool IsExcluded(const wxString& str) const;
|
|
|
|
|
|
|
|
/// Returns false if the character @a c is invalid.
|
|
|
|
bool IsValidChar(const wxUniChar& c) const;
|
2008-03-08 08:52:38 -05:00
|
|
|
};
|
2008-03-10 11:24:38 -04:00
|
|
|
|