From fbec75d080528decc6f8dccc1e9407268a3d15d3 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Tue, 22 Apr 2008 06:01:48 +0000 Subject: [PATCH] More initial reviews of [u*-v*] interface headers. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53303 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/uri.h | 322 ++++++++++++++++++++----------------------- interface/url.h | 106 +++++++------- interface/utils.h | 92 +++++++++---- interface/valgen.h | 87 ++++++++---- interface/validate.h | 50 +++---- interface/valtext.h | 178 +++++++----------------- 6 files changed, 404 insertions(+), 431 deletions(-) diff --git a/interface/uri.h b/interface/uri.h index 2f49d02018..4c36e39445 100644 --- a/interface/uri.h +++ b/interface/uri.h @@ -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 + . - 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. + + 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 - wxURI supports copy construction and standard assignment - operators. wxURI can also be inherited from to provide - furthur functionality. + @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: - //@{ /** - Copies this URI from another URI. + Creates an empty URI. + */ + wxURI(); + /** + Constructor for quick creation. @param uri - URI (Uniform Resource Identifier) to initialize with + URI (Uniform Resource Identifier) to initialize with. */ - wxURI(); wxURI(const wxChar* uri); + /** + Copies this URI from another URI. + + @param uri + URI (Uniform Resource Identifier) to initialize with. + */ 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. - /** - 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 + @c "http://mysite.com/mypath#" */ - 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://:@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" */ - 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:" + + @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?" */ - 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 "://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:///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://:@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://@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() - - GetUserInfo() + 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. - 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 - - @param uricomp, otherwise it returns @false. + Compares this URI to another URI, and returns @true if this URI equals + @a uricomp, otherwise it returns @false. - uricomp - URI to compare to + @param uricomp + URI to compare to. */ void operator ==(const wxURI& uricomp); }; diff --git a/interface/url.h b/interface/url.h index 2c159c8004..dbfd083567 100644 --- a/interface/url.h +++ b/interface/url.h @@ -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 ":". @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); }; diff --git a/interface/utils.h b/interface/utils.h index d5334c64c0..357d282232 100644 --- a/interface/utils.h +++ b/interface/utils.h @@ -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 @, 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; }; diff --git a/interface/valgen.h b/interface/valgen.h index afe90ffab7..00ebc56fd4 100644 --- a/interface/valgen.h +++ b/interface/valgen.h @@ -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. - - 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". + 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. + + 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. + */ + 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). + 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(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. diff --git a/interface/validate.h b/interface/validate.h index b4f1a07831..272db6b433 100644 --- a/interface/validate.h +++ b/interface/validate.h @@ -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; + diff --git a/interface/valtext.h b/interface/valtext.h index 29e9e283d2..27e9ba0c76 100644 --- a/interface/valtext.h +++ b/interface/valtext.h @@ -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. + Default constructor. + */ + wxTextValidator(const wxTextValidator& validator); + /** + 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(). + 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). + 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(long style = wxFILTER_NONE, - wxString* valPtr = NULL); - //@} + 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); }; -- 2.47.2