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 // 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 @class wxURI
@wxheader{uri.h} @wxheader{uri.h}
wxURI is used to extract information from wxURI is used to extract information from a URI (Uniform Resource
a URI (Uniform Resource Identifier). Identifier).
For information about URIs, see For information about URIs, see RFC 3986
RFC 3986. <http://www.ietf.org/rfc/rfc3986.txt>.
In short, a URL is a URI. In other In short, a URL is a URI. In other words, URL is a subset of a URI - all
words, URL is a subset of a URI - all
acceptable URLs are also acceptable URIs. acceptable URLs are also acceptable URIs.
wxURI automatically escapes invalid characters in a string, wxURI automatically escapes invalid characters in a string, so there is no
so there is no chance of wxURI "failing" on construction/creation. chance of wxURI "failing" on construction/creation.
wxURI supports copy construction and standard assignment wxURI supports copy construction and standard assignment operators. wxURI
operators. wxURI can also be inherited from to provide can also be inherited from to provide furthur functionality.
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} @library{wxbase}
@category{data} @category{data}
@@ -35,157 +64,153 @@
class wxURI : public wxObject class wxURI : public wxObject
{ {
public: 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. Copies this URI from another URI.
@param 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); wxURI(const wxURI& uri);
//@}
/** /**
Builds the URI from its individual components and adds proper separators. Builds the URI from its individual components and adds proper
If the URI is not a reference or is not resolved, separators.
the URI that is returned from Get is the same one
passed to Create. 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; wxString BuildURI() const;
/** /**
Builds the URI from its individual components, adds proper separators, and Builds the URI from its individual components, adds proper separators,
returns escape sequences to normal characters. 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. @note It is preferred to call this over Unescape(BuildURI()) since
BuildUnescapedURI() performs some optimizations over the plain
method.
*/ */
wxString BuildUnescapedURI() const; 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 @param uri
is no such thing as an "invalid" wxURI). String to initialize from.
uri
string to initialize from
*/ */
const wxChar* Create(const wxString uri); 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. 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 The fragment of a URI is the last value of the URI, and is the value
of the URI. after a "#" character after the path of the URI.
@c http://mysite.com/mypath#fragment
@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 Obtains the host type of this URI, which is one of wxURIHostType.
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
*/ */
const HostType GetHostType() const; const wxURIHostType& GetHostType() const;
/** /**
Returns the password part of the userinfo component of Returns the password part of the userinfo component of this URI. Note
this URI. Note that this is explicitly depreciated by that this is explicitly depreciated by RFC 1396 and should generally be
RFC 1396 and should generally be avoided if possible. avoided if possible.
@c http://user:password@mysite.com/mypath
@c "http://<user>:<password>@mysite.com/mypath"
*/ */
const wxString GetPassword() const; const wxString& GetPassword() const;
/** /**
Returns the (normalized) path of the URI. Returns the (normalized) path of the URI.
The path component of a URI comes
directly after the scheme component The path component of a URI comes directly after the scheme component
if followed by zero or one slashes ('/'), if followed by zero or one slashes ('/'), or after the server/port
or after the server/port component. component.
Absolute paths include the leading '/'
character. Absolute paths include the leading '/' character.
@c http://mysite.compath
@c "http://mysite.com<path>"
*/ */
const wxString GetPath() const; const wxString& GetPath() const;
/** /**
Returns a string representation of the URI's port. 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 (:). The Port of a URI is a value after the server, and must come after a
@c http://mysite.com:port colon (:).
Note that you can easily get the numeric value of the port
by using wxAtoi or wxString::Format. @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. 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, The query component is what is commonly passed to a cgi application,
and after a '?' character. and must come after the path component, and after a '?' character.
@c http://mysite.com/mypath?query
@c "http://mysite.com/mypath?<query>"
*/ */
const wxString GetQuery() const; const wxString& GetQuery() const;
/** /**
Returns the Scheme component of the URI. 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. Returns the Server component of the URI.
The server of the uri can be a server name or
a type of ip address. See The server of the URI can be a server name or a type of IP address. See
GetHostType() for the GetHostType() for the possible values for the host type of the server
possible values for the host type of the component.
server component.
@c http://server/mypath @c "http://<server>/mypath"
*/ */
const wxString GetServer() const; const wxString& GetServer() const;
/** /**
Returns the username part of the userinfo component of Returns the username part of the userinfo component of this URI. Note
this URI. Note that this is explicitly depreciated by that this is explicitly depreciated by RFC 1396 and should generally be
RFC 1396 and should generally be avoided if possible. avoided if possible.
@c http://user:password@mysite.com/mypath
@c "http://<user>:<password>@mysite.com/mypath"
*/ */
const wxString GetUser() const; const wxString& GetUser() const;
/** /**
Returns the UserInfo component of the URI. Returns the UserInfo component of the URI.
The component of a URI before the server component
that is postfixed by a '@' character. The component of a URI before the server component that is postfixed by
@c http://userinfo@mysite.com/mypath 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. Returns @true if the Fragment component of the URI exists.
@@ -223,92 +248,51 @@ public:
bool HasUser() const; bool HasUser() const;
/** /**
Returns @true if a valid [absolute] URI, otherwise this URI Returns @true if a valid [absolute] URI, otherwise this URI is a URI
is a URI reference and not a full URI, and IsReference reference and not a full URI, and this function returns @false.
returns @false.
*/ */
bool IsReference() const; bool IsReference() const;
/** /**
To obtain individual components you can use Inherits this URI from a base URI - components that do not exist in
one of the following methods this URI are copied from the base, and if this URI's path is not an
GetScheme() 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" For instance, resolving "../mydir" from "http://mysite.com/john/doe"
results in the scheme (http) and server (mysite.com) being copied into results in the scheme (http) and server ("mysite.com") being copied
this URI, since they do not exist. In addition, since the path into this URI, since they do not exist. In addition, since the path of
of this URI is not absolute (does not begin with '/'), the path this URI is not absolute (does not begin with '/'), the path of the
of the base's is merged with this URI's path, resulting in the URI base's is merged with this URI's path, resulting in the URI
"http://mysite.com/john/mydir". "http://mysite.com/john/mydir".
@param base @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 @param flags
Currently either wxURI_STRICT or 0, in non-strict Currently either wxURI_STRICT or 0, in non-strict mode some
mode some compatibility layers are enabled to allow loopholes from RFCs compatibility layers are enabled to allow loopholes from RFCs prior
prior to 2396.
to 2396
*/ */
void Resolve(const wxURI& base, int flags = wxURI_STRICT); void Resolve(const wxURI& base, int flags = wxURI_STRICT);
/** /**
Translates all escape sequences (normal characters and returns the result. Translates all escape sequences (normal characters and returns the
This is the preferred over deprecated wxURL::ConvertFromURI. result.
If you want to unescape an entire wxURI, use BuildUnescapedURI() instead,
as it performs some optimizations over this method. If you want to unescape an entire wxURI, use BuildUnescapedURI()
instead, as it performs some optimizations over this method.
@param uri @param uri
string with escaped characters to convert String with escaped characters to convert.
*/ */
wxString Unescape(const wxString& uri); wxString Unescape(const wxString& uri);
/** /**
Compares this URI to another URI, and returns @true if Compares this URI to another URI, and returns @true if this URI equals
this URI equals @a uricomp, otherwise it returns @false.
@param uricomp, otherwise it returns @false. @param uricomp
URI to compare to.
uricomp
URI to compare to
*/ */
void operator ==(const wxURI& uricomp); void operator ==(const wxURI& uricomp);
}; };

106
interface/url.h
View File

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

92
interface/utils.h
View File

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

85
interface/valgen.h
View File

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

50
interface/validate.h
View File

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

182
interface/valtext.h
View File

@@ -13,145 +13,59 @@
wxTextValidator validates text controls, providing a variety of filtering wxTextValidator validates text controls, providing a variety of filtering
behaviours. behaviours.
For more information, please see @ref overview_validatoroverview "Validator For more information, please see @ref overview_validator.
overview".
@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} @library{wxcore}
@category{validator} @category{validator}
@see @ref overview_validatoroverview "Validator overview", wxValidator, @see @ref overview_validator, wxValidator, wxGenericValidator
wxGenericValidator
*/ */
class wxTextValidator : public wxValidator class wxTextValidator : public wxValidator
{ {
public: public:
//@{
/** /**
Constructor, taking a style and optional pointer to a wxString variable. Default constructor.
@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).
*/ */
wxTextValidator(const wxTextValidator& validator); 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. 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). 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). Returns a reference to the include list (the list of valid values).
*/ */
wxArrayString GetIncludes() const; wxArrayString& GetIncludes() const;
/** /**
Returns the validator style. Returns the validator style.
@@ -174,8 +88,8 @@ public:
long GetStyle() const; long GetStyle() const;
/** /**
Receives character input from the window and filters it according to the Receives character input from the window and filters it according to
current validator style. the current validator style.
*/ */
void OnChar(wxKeyEvent& event); void OnChar(wxKeyEvent& event);
@@ -205,8 +119,8 @@ public:
virtual bool TransferToWindow(); virtual bool TransferToWindow();
/** /**
Validates the window contents against the include or exclude lists, depending Validates the window contents against the include or exclude lists,
on the validator style. depending on the validator style.
*/ */
virtual bool Validate(wxWindow* parent); virtual bool Validate(wxWindow* parent);
}; };