Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More initial reviews of [u*-v*] interface headers.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53303 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-04-22 06:01:48 +00:00
parent 0c1fe6e947
commit fbec75d080
6 changed files with 406 additions and 433 deletions
Download Patch File Download Diff File Expand all files Collapse all files

324
interface/uri.h
View File

@@ -6,26 +6,55 @@
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
Host type of URI returned from wxURI::GetHostType().
*/
enum wxURIHostType
{
wxURI_REGNAME, ///< Host is a normal register name (@c "www.mysite.com").
wxURI_IPV4ADDRESS, ///< Host is a version 4 ip address (@c "192.168.1.100").
wxURI_IPV6ADDRESS, ///< Host is a version 6 ip address (@c "[aa:aa:aa:aa::aa:aa]:5050").
wxURI_IPVFUTURE ///< Host is a future ip address, wxURI is unsure what kind.
};
/**
@class wxURI
@wxheader{uri.h}
wxURI is used to extract information from
a URI (Uniform Resource Identifier).
wxURI is used to extract information from a URI (Uniform Resource
Identifier).
For information about URIs, see
RFC 3986.
For information about URIs, see RFC 3986
<http://www.ietf.org/rfc/rfc3986.txt>.
In short, a URL is a URI. In other
words, URL is a subset of a URI - all
In short, a URL is a URI. In other words, URL is a subset of a URI - all
acceptable URLs are also acceptable URIs.
wxURI automatically escapes invalid characters in a string,
so there is no chance of wxURI "failing" on construction/creation.
wxURI automatically escapes invalid characters in a string, so there is no
chance of wxURI "failing" on construction/creation.
wxURI supports copy construction and standard assignment
operators. wxURI can also be inherited from to provide
furthur functionality.
wxURI supports copy construction and standard assignment operators. wxURI
can also be inherited from to provide furthur functionality.
To obtain individual components you can use one of the GetXXX() methods.
However, you should check HasXXX() before calling a get method, which
determines whether or not the component referred to by the method is
defined according to RFC 2396. Consider an undefined component equivalent
to a @NULL C string.
Example:
@code
//protocol will hold the http protocol (i.e. "http")
wxString protocol;
wxURI myuri("http://mysite.com");
if( myuri.HasScheme() )
protocol = myuri.GetScheme();
@endcode
@note On URIs with a "file" scheme wxURI does not parse the userinfo,
server, or port portion. This is to keep compatability with
wxFileSystem, the old wxURL, and older url specifications.
@library{wxbase}
@category{data}
@@ -35,157 +64,153 @@
class wxURI : public wxObject
{
public:
//@{
/**
Creates an empty URI.
*/
wxURI();
/**
Constructor for quick creation.
@param uri
URI (Uniform Resource Identifier) to initialize with.
*/
wxURI(const wxChar* uri);
/**
Copies this URI from another URI.
@param uri
URI (Uniform Resource Identifier) to initialize with
URI (Uniform Resource Identifier) to initialize with.
*/
wxURI();
wxURI(const wxChar* uri);
wxURI(const wxURI& uri);
//@}
/**
Builds the URI from its individual components and adds proper separators.
If the URI is not a reference or is not resolved,
the URI that is returned from Get is the same one
passed to Create.
Builds the URI from its individual components and adds proper
separators.
If the URI is not a reference or is not resolved, the URI that is
returned is the same one passed to the constructor or Create().
*/
wxString BuildURI() const;
/**
Builds the URI from its individual components, adds proper separators, and
returns escape sequences to normal characters.
Note that it is preferred to call this over Unescape(BuildURI()) since
BuildUnescapedURI() performs some optimizations over the plain method.
Builds the URI from its individual components, adds proper separators,
and returns escape sequences to normal characters.
@note It is preferred to call this over Unescape(BuildURI()) since
BuildUnescapedURI() performs some optimizations over the plain
method.
*/
wxString BuildUnescapedURI() const;
/**
Creates this URI from the string
Creates this URI from the @a uri string.
@param uri.
Returns the position at which parsing stopped (there is no such thing
as an "invalid" wxURI).
Returns the position at which parsing stopped (there
is no such thing as an "invalid" wxURI).
uri
string to initialize from
@param uri
String to initialize from.
*/
const wxChar* Create(const wxString uri);
/**
Note that on URIs with a "file" scheme wxURI does not
parse the userinfo, server, or port portion. This is to keep
compatability with wxFileSystem, the old wxURL, and older url specifications.
*/
/**
Obtains the fragment of this URI.
The fragment of a URI is the last value of the URI,
and is the value after a " character after the path
of the URI.
@c http://mysite.com/mypath#fragment
The fragment of a URI is the last value of the URI, and is the value
after a "#" character after the path of the URI.
@c "http://mysite.com/mypath#<fragment>"
*/
const wxString GetFragment() const;
const wxString& GetFragment() const;
/**
Obtains the host type of this URI, which is of type
HostType():
@b wxURI_REGNAME
Server is a host name, or the Server component itself is undefined.
@b wxURI_IPV4ADDRESS
Server is a IP version 4 address (XXX.XXX.XXX.XXX)
@b wxURI_IPV6ADDRESS
Server is a IP version 6 address ((XXX:)XXX::(XXX)XXX:XXX
@b wxURI_IPVFUTURE
Server is an IP address, but not versions 4 or 6
Obtains the host type of this URI, which is one of wxURIHostType.
*/
const HostType GetHostType() const;
const wxURIHostType& GetHostType() const;
/**
Returns the password part of the userinfo component of
this URI. Note that this is explicitly depreciated by
RFC 1396 and should generally be avoided if possible.
@c http://user:password@mysite.com/mypath
Returns the password part of the userinfo component of this URI. Note
that this is explicitly depreciated by RFC 1396 and should generally be
avoided if possible.
@c "http://<user>:<password>@mysite.com/mypath"
*/
const wxString GetPassword() const;
const wxString& GetPassword() const;
/**
Returns the (normalized) path of the URI.
The path component of a URI comes
directly after the scheme component
if followed by zero or one slashes ('/'),
or after the server/port component.
Absolute paths include the leading '/'
character.
@c http://mysite.compath
The path component of a URI comes directly after the scheme component
if followed by zero or one slashes ('/'), or after the server/port
component.
Absolute paths include the leading '/' character.
@c "http://mysite.com<path>"
*/
const wxString GetPath() const;
const wxString& GetPath() const;
/**
Returns a string representation of the URI's port.
The Port of a URI is a value after the server, and
must come after a colon (:).
@c http://mysite.com:port
Note that you can easily get the numeric value of the port
by using wxAtoi or wxString::Format.
The Port of a URI is a value after the server, and must come after a
colon (:).
@c "http://mysite.com:<port>"
@note You can easily get the numeric value of the port by using
wxAtoi() or wxString::Format().
*/
const wxString GetPort() const;
const wxString& GetPort() const;
/**
Returns the Query component of the URI.
The query component is what is commonly passed to a
cgi application, and must come after the path component,
and after a '?' character.
@c http://mysite.com/mypath?query
The query component is what is commonly passed to a cgi application,
and must come after the path component, and after a '?' character.
@c "http://mysite.com/mypath?<query>"
*/
const wxString GetQuery() const;
const wxString& GetQuery() const;
/**
Returns the Scheme component of the URI.
The first part of the uri.
@c scheme://mysite.com
The first part of the URI.
@c "<scheme>://mysite.com"
*/
const wxString GetScheme() const;
const wxString& GetScheme() const;
/**
Returns the Server component of the URI.
The server of the uri can be a server name or
a type of ip address. See
GetHostType() for the
possible values for the host type of the
server component.
@c http://server/mypath
The server of the URI can be a server name or a type of IP address. See
GetHostType() for the possible values for the host type of the server
component.
@c "http://<server>/mypath"
*/
const wxString GetServer() const;
const wxString& GetServer() const;
/**
Returns the username part of the userinfo component of
this URI. Note that this is explicitly depreciated by
RFC 1396 and should generally be avoided if possible.
@c http://user:password@mysite.com/mypath
Returns the username part of the userinfo component of this URI. Note
that this is explicitly depreciated by RFC 1396 and should generally be
avoided if possible.
@c "http://<user>:<password>@mysite.com/mypath"
*/
const wxString GetUser() const;
const wxString& GetUser() const;
/**
Returns the UserInfo component of the URI.
The component of a URI before the server component
that is postfixed by a '@' character.
@c http://userinfo@mysite.com/mypath
The component of a URI before the server component that is postfixed by
a '@' character.
@c "http://<userinfo>@mysite.com/mypath"
*/
const wxString GetUserInfo() const;
const wxString& GetUserInfo() const;
/**
Returns @true if the Fragment component of the URI exists.
@@ -223,92 +248,51 @@ public:
bool HasUser() const;
/**
Returns @true if a valid [absolute] URI, otherwise this URI
is a URI reference and not a full URI, and IsReference
returns @false.
Returns @true if a valid [absolute] URI, otherwise this URI is a URI
reference and not a full URI, and this function returns @false.
*/
bool IsReference() const;
/**
To obtain individual components you can use
one of the following methods
GetScheme()
Inherits this URI from a base URI - components that do not exist in
this URI are copied from the base, and if this URI's path is not an
absolute path (prefixed by a '/'), then this URI's path is merged with
the base's path.
GetUserInfo()
GetServer()
GetPort()
GetPath()
GetQuery()
GetFragment()
However, you should check HasXXX before
calling a get method, which determines whether or not the component referred
to by the method is defined according to RFC 2396.
Consider an undefined component equivalent to a
@NULL C string.
HasScheme()
HasUserInfo()
HasServer()
@ref hasserver() HasPort
HasPath()
HasQuery()
HasFragment()
Example:
*/
/**
Inherits this URI from a base URI - components that do not
exist in this URI are copied from the base, and if this URI's
path is not an absolute path (prefixed by a '/'), then this URI's
path is merged with the base's path.
For instance, resolving "../mydir" from "http://mysite.com/john/doe"
results in the scheme (http) and server (mysite.com) being copied into
this URI, since they do not exist. In addition, since the path
of this URI is not absolute (does not begin with '/'), the path
of the base's is merged with this URI's path, resulting in the URI
results in the scheme (http) and server ("mysite.com") being copied
into this URI, since they do not exist. In addition, since the path of
this URI is not absolute (does not begin with '/'), the path of the
base's is merged with this URI's path, resulting in the URI
"http://mysite.com/john/mydir".
@param base
Base URI to inherit from. Must be a full URI and not a reference
Base URI to inherit from. Must be a full URI and not a reference.
@param flags
Currently either wxURI_STRICT or 0, in non-strict
mode some compatibility layers are enabled to allow loopholes from RFCs
prior
to 2396
Currently either wxURI_STRICT or 0, in non-strict mode some
compatibility layers are enabled to allow loopholes from RFCs prior
to 2396.
*/
void Resolve(const wxURI& base, int flags = wxURI_STRICT);
/**
Translates all escape sequences (normal characters and returns the result.
This is the preferred over deprecated wxURL::ConvertFromURI.
If you want to unescape an entire wxURI, use BuildUnescapedURI() instead,
as it performs some optimizations over this method.
Translates all escape sequences (normal characters and returns the
result.
If you want to unescape an entire wxURI, use BuildUnescapedURI()
instead, as it performs some optimizations over this method.
@param uri
string with escaped characters to convert
String with escaped characters to convert.
*/
wxString Unescape(const wxString& uri);
/**
Compares this URI to another URI, and returns @true if
this URI equals
Compares this URI to another URI, and returns @true if this URI equals
@a uricomp, otherwise it returns @false.
@param uricomp, otherwise it returns @false.
uricomp
URI to compare to
@param uricomp
URI to compare to.
*/
void operator ==(const wxURI& uricomp);
};

106
interface/url.h
View File

@@ -6,17 +6,29 @@
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
Error types returned from wxURL::GetError().
*/
typedef enum {
wxURL_NOERR = 0, ///< No error.
wxURL_SNTXERR, ///< Syntax error in the URL string.
wxURL_NOPROTO, ///< Found no protocol which can get this URL.
wxURL_NOHOST, ///< A host name is required for this protocol.
wxURL_NOPATH, ///< A path is required for this protocol.
wxURL_CONNERR, ///< Connection error.
wxURL_PROTOERR ///< An error occurred during negotiation.
} wxURLError;
/**
@class wxURL
@wxheader{url.h}
wxURL is a specialization of wxURI for parsing URLs.
Please look at wxURI documentation for more info about the functions
you can use to retrieve the various parts of the URL (scheme, server, port,
etc).
wxURL is a specialization of wxURI for parsing URLs. Please look at wxURI
documentation for more info about the functions you can use to retrieve the
various parts of the URL (scheme, server, port, etc).
Supports standard assignment operators, copy constructors,
and comparison operators.
Supports standard assignment operators, copy constructors, and comparison
operators.
@library{wxnet}
@category{net}
@@ -27,13 +39,14 @@ class wxURL : public wxURI
{
public:
/**
Constructs a URL object from the string. The URL must be valid according
to RFC 1738. In particular, file URLs must be of the format
@c file://hostname/path/to/file otherwise GetError()
will return a value different from @c wxURL_NOERR.
It is valid to leave out the hostname but slashes must remain in place -
i.e. a file URL without a hostname must contain three consecutive slashes
(e.g. @c file:///somepath/myfile).
Constructs a URL object from the string. The URL must be valid
according to RFC 1738. In particular, file URLs must be of the format
@c "file://hostname/path/to/file", otherwise GetError() will return a
value different from ::wxURL_NOERR.
It is valid to leave out the hostname but slashes must remain in place,
in other words, a file URL without a hostname must contain three
consecutive slashes (e.g. @c "file:///somepath/myfile").
@param url
Url string to parse.
@@ -46,47 +59,32 @@ public:
~wxURL();
/**
Returns the last error. This error refers to the URL parsing or to the protocol.
It can be one of these errors:
@b wxURL_NOERR
No error.
@b wxURL_SNTXERR
Syntax error in the URL string.
@b wxURL_NOPROTO
Found no protocol which can get this URL.
@b wxURL_NOHOST
A host name is required for this protocol.
@b wxURL_NOPATH
A path is required for this protocol.
@b wxURL_CONNERR
Connection error.
@b wxURL_PROTOERR
An error occurred during negotiation.
Returns the last error. This error refers to the URL parsing or to the
protocol. It can be one of ::wxURLError.
*/
wxURLError GetError() const;
/**
Creates a new input stream on the specified URL. You can use all but seek
functionality of wxStream. Seek isn't available on all streams. For example,
HTTP or FTP streams don't deal with it.
Note that this method is somewhat deprecated, all future wxWidgets applications
should really use wxFileSystem instead.
Creates a new input stream on the specified URL. You can use all but
seek functionality of wxStream. Seek isn't available on all streams.
For example, HTTP or FTP streams don't deal with it.
Note that this method is somewhat deprecated, all future wxWidgets
applications should use wxFileSystem instead.
Example:
@code
wxURL url("http://a.host/a.dir/a.file");
if (url.GetError() == wxURL_NOERR)
{
wxInputStream *in_stream;
in_stream = url.GetInputStream();
// Then, you can use all IO calls of in_stream (See wxStream)
}
@endcode
@returns Returns the initialized stream. You will have to delete it
yourself.
@@ -101,16 +99,16 @@ public:
/**
Returns @true if this object is correctly initialized, i.e. if
GetError() returns @c wxURL_NOERR.
GetError() returns ::wxURL_NOERR.
*/
bool IsOk() const;
/**
Sets the default proxy server to use to get the URL. The string specifies
the proxy like this: hostname:port number.
Sets the default proxy server to use to get the URL. The string
specifies the proxy like this: @c "<hostname>:<port number>".
@param url_proxy
Specifies the proxy to use
Specifies the proxy to use.
@see SetProxy()
*/
@@ -124,8 +122,8 @@ public:
void SetProxy(const wxString& url_proxy);
/**
Initializes this object with the given URL and returns @c wxURL_NOERR
if it's valid (see GetError() for more info).
Initializes this object with the given URL and returns ::wxURL_NOERR if
it's valid (see GetError() for more info).
*/
wxURLError SetURL(const wxString& url);
};

92
interface/utils.h
View File

@@ -1,6 +1,6 @@
/////////////////////////////////////////////////////////////////////////////
// Name: utils.h
// Purpose: interface of wxWindowDisabler
// Purpose: interface of various utility classes and functions
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@@ -10,14 +10,15 @@
@class wxWindowDisabler
@wxheader{utils.h}
This class disables all windows of the application (may be with the exception
of one of them) in its constructor and enables them back in its destructor.
This class disables all windows of the application (may be with the
exception of one of them) in its constructor and enables them back in its
destructor.
This is useful when you want to indicate to the user that the application
is currently busy and cannot respond to user input.
@library{wxcore}
@category{FIXME}
@category{misc}
@see wxBusyCursor
*/
@@ -35,13 +36,13 @@ public:
wxWindowDisabler(bool disable = true);
/**
Disables all top level windows of the applications with the exception of
@a winToSkip if it is not @NULL.
Disables all top level windows of the applications with the exception
of @a winToSkip if it is not @NULL.
*/
wxWindowDisabler(wxWindow* winToSkip);
/**
Reenables back the windows disabled by the constructor.
Reenables the windows disabled by the constructor.
*/
~wxWindowDisabler();
};
@@ -52,24 +53,24 @@ public:
@class wxBusyCursor
@wxheader{utils.h}
This class makes it easy to tell your user that the program is temporarily busy.
Just create a wxBusyCursor object on the stack, and within the current scope,
the hourglass will be shown.
This class makes it easy to tell your user that the program is temporarily
busy. Just create a wxBusyCursor object on the stack, and within the
current scope, the hourglass will be shown.
For example:
@code
wxBusyCursor wait;
for (int i = 0; i 100000; i++)
for (int i = 0; i < 100000; i++)
DoACalculation();
@endcode
It works by calling wxBeginBusyCursor() in the constructor,
and wxEndBusyCursor() in the destructor.
It works by calling wxBeginBusyCursor() in the constructor, and
wxEndBusyCursor() in the destructor.
@library{wxcore}
@category{FIXME}
@category{misc}
@see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
*/
@@ -88,6 +89,7 @@ public:
};
/**
@class wxMouseState
@wxheader{utils.h}
@@ -97,38 +99,74 @@ public:
The methods of this class generally mirror the corresponding methods of
wxMouseEvent.
This class is implemented entirely in @<wx/utils.h@>, meaning no extra
library needs to be linked to use this class.
@category{misc}
@see wxGetMouseState()
*/
class wxMouseState
{
public:
/// Returns X coordinate of the physical mouse event position.
/**
Default constructor.
*/
wxMouseState();
/**
Returns X coordinate of the physical mouse event position.
*/
wxCoord GetX() const;
/// Returns Y coordinate of the physical mouse event position.
/**
Returns Y coordinate of the physical mouse event position.
*/
wxCoord GetY() const;
/// Returns the physical mouse position.
/**
Returns the physical mouse position.
*/
wxPoint GetPosition() const;
/// Returns @true if the left mouse button changed to down.
/**
Returns @true if the left mouse button changed to down.
*/
bool LeftDown() const;
/// Returns @true if the middle mouse button changed to down.
/**
Returns @true if the middle mouse button changed to down.
*/
bool MiddleDown() const;
/// Returns @true if the right mouse button changed to down.
/**
Returns @true if the right mouse button changed to down.
*/
bool RightDown() const;
/// Returns @true if the first extra button mouse button changed to down.
/**
Returns @true if the first extra button mouse button changed to down.
*/
bool Aux1Down() const;
/// Returns @true if the second extra button mouse button changed to down.
/**
Returns @true if the second extra button mouse button changed to down.
*/
bool Aux2Down() const;
/// Returns @true if the control key is down.
/**
Returns @true if the control key is down.
*/
bool ControlDown() const;
/// Returns @true if the shift key is down.
/**
Returns @true if the shift key is down.
*/
bool ShiftDown() const;
/// Returns @true if the alt key is down.
/**
Returns @true if the alt key is down.
*/
bool AltDown() const;
/// Returns @true if the meta key is down.
/**
Returns @true if the meta key is down.
*/
bool MetaDown() const;
/// Same as MetaDown() under Mac systems, ControlDown() for the others.
/**
Same as MetaDown() under Mac systems, ControlDown() for the others.
*/
bool CmdDown() const;
};

85
interface/valgen.h
View File

@@ -10,51 +10,88 @@
@class wxGenericValidator
@wxheader{valgen.h}
wxGenericValidator performs data transfer (but not validation or filtering) for
the following
basic controls: wxButton, wxCheckBox, wxListBox, wxStaticText, wxRadioButton,
wxRadioBox,
wxChoice, wxComboBox, wxGauge, wxSlider, wxScrollBar, wxSpinButton, wxTextCtrl,
wxCheckListBox.
wxGenericValidator performs data transfer (but not validation or filtering)
for the following basic controls: wxButton, wxCheckBox, wxListBox,
wxStaticText, wxRadioButton, wxRadioBox, wxChoice, wxComboBox, wxGauge,
wxSlider, wxScrollBar, wxSpinButton, wxTextCtrl, wxCheckListBox.
It checks the type of the window and uses an appropriate type for that window.
For example,
wxButton and wxTextCtrl transfer data to and from a wxString variable;
wxListBox uses a
wxArrayInt; wxCheckBox uses a bool.
It checks the type of the window and uses an appropriate type for that
window. For example, wxButton and wxTextCtrl transfer data to and from a
wxString variable; wxListBox uses a wxArrayInt; wxCheckBox uses a bool.
For more information, please see @ref overview_validatoroverview "Validator
overview".
For more information, please see @ref overview_validator.
@library{wxcore}
@category{validator}
@see @ref overview_validatoroverview "Validator overview", wxValidator,
wxTextValidator
@see @ref overview_validator, wxValidator, wxTextValidator
*/
class wxGenericValidator : public wxValidator
{
public:
//@{
/**
Constructor taking a wxDateTime pointer. This will be
used for wxDatePickerCtrl.
Copy constructor.
@param validator
Validator to copy.
@param valPtr
A pointer to a 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).
*/
wxGenericValidator(const wxGenericValidator& validator);
/**
Constructor taking a bool pointer. This will be used for wxCheckBox,
wxRadioButton, wxToggleButton and wxBitmapToggleButton.
@param valPtr
A pointer to a 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).
*/
wxGenericValidator(bool* valPtr);
/**
Constructor taking a wxString pointer. This will be used for wxButton,
wxComboBox, wxStaticText, wxTextCtrl.
@param valPtr
A pointer to a 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).
*/
wxGenericValidator(wxString* valPtr);
/**
Constructor taking an integer pointer. This will be used for wxChoice,
wxGauge, wxScrollBar, wxRadioBox, wxSlider, wxSpinButton and
wxSpinCtrl.
@param valPtr
A pointer to a 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).
*/
wxGenericValidator(int* valPtr);
/**
Constructor taking a wxArrayInt pointer. This will be used for
wxListBox, wxCheckListBox.
@param valPtr
A pointer to a 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).
*/
wxGenericValidator(wxArrayInt* valPtr);
/**
Constructor taking a wxDateTime pointer. This will be used for
wxDatePickerCtrl.
@param valPtr
A pointer to a 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).
*/
wxGenericValidator(wxDateTime* valPtr);
//@}
/**
Destructor.

50
interface/validate.h
View File

@@ -10,26 +10,27 @@
@class wxValidator
@wxheader{validate.h}
wxValidator is the base class for a family of validator classes that mediate
between a class of control, and application data.
wxValidator is the base class for a family of validator classes that
mediate between a class of control, and application data.
A validator has three major roles:
@li to transfer data from a C++ variable or own storage to and from a control;
@li to validate data in a control, and show an appropriate error message;
@li to filter events (such as keystrokes), thereby changing the behaviour of the
associated control.
-# To transfer data from a C++ variable or own storage to and from a
control.
-# To validate data in a control, and show an appropriate error message.
-# To filter events (such as keystrokes), thereby changing the behaviour
of the associated control.
Validators can be plugged into controls dynamically.
To specify a default, 'null' validator, use the symbol ::wxDefaultValidator.
To specify a default, "null" validator, use ::wxDefaultValidator.
For more information, please see @ref overview_validator.
@beginWxPythonOnly
If you wish to create a validator class in wxPython you should
derive the class from @c wxPyValidator in order to get Python-aware
capabilities for the various virtual methods.
If you wish to create a validator class in wxPython you should derive the
class from @c wxPyValidator in order to get Python-aware capabilities for
the various virtual methods.
@endWxPythonOnly
@library{wxcore}
@@ -54,15 +55,15 @@ public:
~wxValidator();
/**
All validator classes must implement the Clone() function, which returns
an identical copy of itself.
All validator classes must implement the Clone() function, which
returns an identical copy of itself.
This is because validators are passed to control constructors as references
which must be copied. Unlike objects such as pens and brushes, it does not
make sense to have a reference counting scheme to do this cloning, because
all validators should have separate data.
This is because validators are passed to control constructors as
references which must be copied. Unlike objects such as pens and
brushes, it does not make sense to have a reference counting scheme to
do this cloning because all validators should have separate data.
@returns this base function returns @NULL.
@returns This base function returns @NULL.
*/
virtual wxObject* Clone() const;
@@ -83,8 +84,8 @@ public:
void SetWindow(wxWindow* window);
/**
This overridable function is called when the value in the window must be
transferred to the validator.
This overridable function is called when the value in the window must
be transferred to the validator.
@return @false if there is a problem.
*/
@@ -99,16 +100,17 @@ public:
virtual bool TransferToWindow();
/**
This overridable function is called when the value in the associated window
must be validated.
This overridable function is called when the value in the associated
window must be validated.
@return @false if the value in the window is not valid; you may pop up an error
dialog.
@return @false if the value in the window is not valid; you may pop up
an error dialog.
*/
virtual bool Validate(wxWindow* parent);
};
/**
An empty wxValidator instance.
An empty, "null" wxValidator instance.
*/
wxValidator wxDefaultValidator;

182
interface/valtext.h
View File

@@ -13,145 +13,59 @@
wxTextValidator validates text controls, providing a variety of filtering
behaviours.
For more information, please see @ref overview_validatoroverview "Validator
overview".
For more information, please see @ref overview_validator.
@beginStyleTable
@style{wxFILTER_NONE}
No filtering takes place.
@style{wxFILTER_ASCII}
Non-ASCII characters are filtered out.
@style{wxFILTER_ALPHA}
Non-alpha characters are filtered out.
@style{wxFILTER_ALPHANUMERIC}
Non-alphanumeric characters are filtered out.
@style{wxFILTER_NUMERIC}
Non-numeric characters are filtered out.
@style{wxFILTER_INCLUDE_LIST}
Use an include list. The validator checks if the user input is on
the list, complaining if not. See SetIncludes().
@style{wxFILTER_EXCLUDE_LIST}
Use an exclude list. The validator checks if the user input is on
the list, complaining if it is. See SetExcludes().
@style{wxFILTER_INCLUDE_CHAR_LIST}
Use an include list. The validator checks if each input character is
in the list (one character per list element), complaining if not.
See SetIncludes().
@style{wxFILTER_EXCLUDE_CHAR_LIST}
Use an include list. The validator checks if each input character is
in the list (one character per list element), complaining if it is.
See SetExcludes().
@endStyleTable
@library{wxcore}
@category{validator}
@see @ref overview_validatoroverview "Validator overview", wxValidator,
wxGenericValidator
@see @ref overview_validator, wxValidator, wxGenericValidator
*/
class wxTextValidator : public wxValidator
{
public:
//@{
/**
Constructor, taking a style and optional pointer to a wxString variable.
@param style
A bitlist of flags, which can be:
wxFILTER_NONE
No filtering takes place.
wxFILTER_ASCII
Non-ASCII characters are filtered out.
wxFILTER_ALPHA
Non-alpha characters are filtered out.
wxFILTER_ALPHANUMERIC
Non-alphanumeric characters are filtered out.
wxFILTER_NUMERIC
Non-numeric characters are filtered out.
wxFILTER_INCLUDE_LIST
Use an include list. The validator
checks if the user input is on the list, complaining if not. See
SetIncludes().
wxFILTER_EXCLUDE_LIST
Use an exclude list. The validator
checks if the user input is on the list, complaining if it is. See
SetExcludes().
wxFILTER_INCLUDE_CHAR_LIST
Use an include list. The validator
checks if each input character is in the list (one character per list
element), complaining if not.
See SetIncludes().
wxFILTER_EXCLUDE_CHAR_LIST
Use an include list. The validator
checks if each input character is in the list (one character per list
element), complaining if it is.
See SetExcludes().
@param valPtr
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).
Default constructor.
*/
wxTextValidator(const wxTextValidator& validator);
wxTextValidator(long style = wxFILTER_NONE,
wxString* valPtr = NULL);
//@}
/**
Constructor taking a style and optional pointer to a wxString variable.
@param style
A bitlist of flags documented in the class description.
@param valPtr
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).
*/
wxTextValidator(long style = wxFILTER_NONE, wxString* valPtr = NULL);
/**
Clones the text validator using the copy constructor.
@@ -161,12 +75,12 @@ public:
/**
Returns a reference to the exclude list (the list of invalid values).
*/
wxArrayString GetExcludes() const;
wxArrayString& GetExcludes() const;
/**
Returns a reference to the include list (the list of valid values).
*/
wxArrayString GetIncludes() const;
wxArrayString& GetIncludes() const;
/**
Returns the validator style.
@@ -174,8 +88,8 @@ public:
long GetStyle() const;
/**
Receives character input from the window and filters it according to the
current validator style.
Receives character input from the window and filters it according to
the current validator style.
*/
void OnChar(wxKeyEvent& event);
@@ -205,8 +119,8 @@ public:
virtual bool TransferToWindow();
/**
Validates the window contents against the include or exclude lists, depending
on the validator style.
Validates the window contents against the include or exclude lists,
depending on the validator style.
*/
virtual bool Validate(wxWindow* parent);
};