Applied Patch #1502804: wx*PickerCtrl documentation fixes

[wxWidgets.git] / docs / latex / wx / uri.tex

diff --git a/docs/latex/wx/uri.tex b/docs/latex/wx/uri.tex
index 80377111bc514c325f18336bb010c7c75b825ba1..b81c247ac0bf1a11f975bf28d58aef0626b2fe98 100644 (file)
--- a/docs/latex/wx/uri.tex
+++ b/docs/latex/wx/uri.tex
@@ -15,37 +15,14 @@ wxURI is used to extract information from
 a URI (Uniform Resource Identifier).
 
 For information about URIs, see 
 a URI (Uniform Resource Identifier).
 
 For information about URIs, see 

-\urlref{RFC 2396}{http://www.ietf.org/rfc/rfc2396.txt} or 
-\urlref{RFC 2396.bis (Updated draft of RFC 2396)}{http://www.gbiv.com/protocols/uri/rev-2002/rfc2396bis.html}.
+\urlref{RFC 3986}{http://www.ietf.org/rfc/rfc3986.txt}.

 
 In short, a URL \em{is} a URI.  In other
 
 In short, a URL \em{is} a URI.  In other

-words, URL is a subset of a URI - most 
+words, URL is a subset of a URI - all 

 acceptable URLs are also acceptable URIs.
 
 acceptable URLs are also acceptable URIs.
 

-wxURI can be used to validate URIs:
-\begin{verbatim}
-URI myuri;
-
-//will not print "Bad URI" because this is a valid URI
-if(!myuri.Create(("ftp://mysiteftp.com/mydir")))
-       wxPrintf("Bad URI");
-
-URI mybaduri;
-
-//will print "Bad URI" because ::x:: is not a valid URI
-if(!mybaduri.Create(("::x::")))
-       wxPrintf("Bad URI");
-\end{verbatim}
-
-wxURI also has some uses that may not be apparent at first, 
-such as skipping past a URI in a string:
-\begin{verbatim}
-URI myuri;
-wxString mystring = wxT("http://mysite.com A Good Website");
-
-//mystring will contain " A Good Website" after URI::Create()
-mystring = myuri.Extract(mystring);
-\end{verbatim}
+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
 
 wxURI supports copy construction and standard assignment
 operators.  wxURI can also be inherited from to provide


@@ -53,21 +30,21 @@ furthur functionality.
 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 

-No base class
+\helpref{wxObject}{wxobject}

 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 

-<uri.h>
+<wx/uri.h>

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{Obtaining individual components}
+\membersection{Obtaining individual components}\label{obtainingwxuricomponents}

 
 To obtain individual components you can use 
 
 To obtain individual components you can use 

-one of the following methods:
+one of the following methods

 
 \helpref{GetScheme}{wxurigetscheme}\\
 
 \helpref{GetScheme}{wxurigetscheme}\\

-\helpref{GetUser}{wxurigetuser}\\
+\helpref{GetUserInfo}{wxurigetuserinfo}\\

 \helpref{GetServer}{wxurigetserver}\\
 \helpref{GetPort}{wxurigetserver}\\
 \helpref{GetPath}{wxurigetpath}\\
 \helpref{GetServer}{wxurigetserver}\\
 \helpref{GetPort}{wxurigetserver}\\
 \helpref{GetPath}{wxurigetpath}\\


@@ -75,10 +52,14 @@ one of the following methods:
 \helpref{GetFragment}{wxurigetfragment}
 
 However, you should check HasXXX before
 \helpref{GetFragment}{wxurigetfragment}
 
 However, you should check HasXXX before

-calling a get method:
- 
+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.\\
+\\ 

 \helpref{HasScheme}{wxurihasscheme}\\
 \helpref{HasScheme}{wxurihasscheme}\\

-\helpref{HasUser}{wxurihasuser}\\
+\helpref{HasUserInfo}{wxurihasuserinfo}\\

 \helpref{HasServer}{wxurihasserver}\\
 \helpref{HasPort}{wxurihasserver}\\
 \helpref{HasPath}{wxurihaspath}\\
 \helpref{HasServer}{wxurihasserver}\\
 \helpref{HasPort}{wxurihasserver}\\
 \helpref{HasPath}{wxurihaspath}\\


@@ -94,53 +75,64 @@ if(myuri.HasScheme())
    protocol = myuri.GetScheme();
 \end{verbatim}
 
    protocol = myuri.GetScheme();
 \end{verbatim}
 

-Also, you can get the numeric value of the URI's port
-component by calling \helpref{GetPortValue}{wxurigetportvalue},
-and the host type of the server component by calling 
-\helpref{GetHostType}{wxurigethosttype}
+\membersection{Deviations from the RFC}\label{deviationsfromrfc}
+
+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.

 
 \membersection{wxURI::wxURI}\label{wxuriwxuri}
 
 \func{}{wxURI}{\void}
 
 
 \membersection{wxURI::wxURI}\label{wxuriwxuri}
 
 \func{}{wxURI}{\void}
 

-Creates an empty URI.  In order for the URI to be
-useful, Create needs to be called eventually.
-
-\membersection{wxURI::\destruct{wxURI}}\label{wxuridtor}
+Creates an empty URI.

 
 \func{}{wxURI}{\param{const wxChar* }{uri}}
 
 
 \func{}{wxURI}{\param{const wxChar* }{uri}}
 

-Constructor for quick creation
+Constructor for quick creation.

 
 \docparam{uri}{string to initialize with}
 
 
 \docparam{uri}{string to initialize with}
 

-
-\func{}{wxURI}{\param{const wxURI& }{uri}}
+\func{}{wxURI}{\param{const wxURI\& }{uri}}

 
 Copies this URI from another URI.
 
 \docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
 
 
 
 Copies this URI from another URI.
 
 \docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
 
 

-\membersection{wxURI::Create}\label{wxuricreate}
+\membersection{wxURI::BuildURI}\label{wxuribuilduri}

 
 

-\func{const wxChar*}{Create}{\param{const wxChar* }{uri}}
+\constfunc{wxString}{BuildURI}{\void}

 
 

-Creates this URI from a string, and parses \arg{uri} for validity.
-Returns the position where parsing stopped in string, 
-or false if \arg{uri} is not a valid URI.
+Builds the URI from its individual components and adds proper separators.

 
 

-\docparam{uri}{string to initialize from}
+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.

 
 

-\membersection{wxURI::Get}\label{wxuriget}

 
 

-\constfunc{wxString}{Get}{\void}
+\membersection{wxURI::BuildUnescapedURI}\label{wxuribuildunescapeduri}

 
 

-Obtains the full URI.
+\constfunc{wxString}{BuildUnescapedURI}{\void}
+
+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
+\helpref{BuildUnescapedURI}{wxuribuildunescapeduri} performs some optimizations over the plain method.
+
+
+\membersection{wxURI::Create}\label{wxuricreate}
+
+\func{const wxChar*}{Create}{\param{const wxString&}{uri}}
+
+Creates this URI from the string \arg{uri}.
+
+Returns the position at which parsing stopped (there 
+is no such thing as an "invalid" wxURI).
+
+\docparam{uri}{string to initialize from}

 
 

-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.

 
 \membersection{wxURI::GetFragment}\label{wxurigetfragment}
 
 
 \membersection{wxURI::GetFragment}\label{wxurigetfragment}
 


@@ -169,6 +161,18 @@ wxURI::HostType:
 \twocolitem{{\bf wxURI\_IPVFUTURE}}{Server is an IP address, but not versions 4 or 6}
 \end{twocollist}
 
 \twocolitem{{\bf wxURI\_IPVFUTURE}}{Server is an IP address, but not versions 4 or 6}
 \end{twocollist}
 

+
+\membersection{wxURI::GetPassword}\label{wxurigetpassword}
+
+\constfunc{const wxString&}{GetPassword}{\void}
+
+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.
+
+\tt{http://<user>:<password>@mysite.com/mypath}
+
+

 \membersection{wxURI::GetPath}\label{wxurigetpath}
 
 \constfunc{const wxString&}{GetPath}{\void}
 \membersection{wxURI::GetPath}\label{wxurigetpath}
 
 \constfunc{const wxString&}{GetPath}{\void}


@@ -242,101 +246,96 @@ server component.
 
 \constfunc{const wxString&}{GetUser}{\void}
 
 
 \constfunc{const wxString&}{GetUser}{\void}
 

-Returns the User component of the URI.
+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.
+
+\tt{http://<user>:<password>@mysite.com/mypath}
+
+
+\membersection{wxURI::GetUserInfo}\label{wxurigetuserinfo}
+
+\constfunc{const wxString&}{GetUserInfo}{\void}
+
+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 a '@' character.
 

-\tt{http://<user>@mysite.com/mypath}
+\tt{http://<userinfo>@mysite.com/mypath}
+

 
 \membersection{wxURI::HasFragment}\label{wxurihasfragment}
 
 \constfunc{bool}{HasFragment}{\void}
 
 
 \membersection{wxURI::HasFragment}\label{wxurihasfragment}
 
 \constfunc{bool}{HasFragment}{\void}
 

-Returns true if the Fragment component of the URI exists.
+Returns \true if the Fragment component of the URI exists.
+

 
 \membersection{wxURI::HasPath}\label{wxurihaspath}
 
 \constfunc{bool}{HasPath}{\void}
 
 
 \membersection{wxURI::HasPath}\label{wxurihaspath}
 
 \constfunc{bool}{HasPath}{\void}
 

-Returns true if the Path component of the URI exists.
+Returns \true if the Path component of the URI exists.
+

 
 \membersection{wxURI::HasPort}\label{wxurihasport}
 
 \constfunc{bool}{HasPort}{\void}
 
 
 \membersection{wxURI::HasPort}\label{wxurihasport}
 
 \constfunc{bool}{HasPort}{\void}
 

-Returns true if the Port component of the URI exists.
+Returns \true if the Port component of the URI exists.

 
 
 \membersection{wxURI::HasQuery}\label{wxurihasquery}
 
 \constfunc{bool}{HasQuery}{\void}
 
 
 
 \membersection{wxURI::HasQuery}\label{wxurihasquery}
 
 \constfunc{bool}{HasQuery}{\void}
 

-Returns true if the Query component of the URI exists.
+Returns \true if the Query component of the URI exists.

 
 
 \membersection{wxURI::HasScheme}\label{wxurihasscheme}
 
 \constfunc{bool}{HasScheme}{\void}
 
 
 
 \membersection{wxURI::HasScheme}\label{wxurihasscheme}
 
 \constfunc{bool}{HasScheme}{\void}
 

-Returns true if the Scheme component of the URI exists.
+Returns \true if the Scheme component of the URI exists.

 
 
 \membersection{wxURI::HasServer}\label{wxurihasserver}
 
 \constfunc{bool}{HasServer}{\void}
 
 
 
 \membersection{wxURI::HasServer}\label{wxurihasserver}
 
 \constfunc{bool}{HasServer}{\void}
 

-Returns true if the Server component of the URI exists.
+Returns \true if the Server component of the URI exists.

 
 
 
 

-\membersection{wxURI::HasUser}\label{wxurihasuser}
+\membersection{wxURI::HasUser}\label{wxurihasuserinfo}

 
 \constfunc{bool}{HasUser}{\void}
 
 
 \constfunc{bool}{HasUser}{\void}
 

-Returns true if the User component of the URI exists.
-
-
-\membersection{wxURI::IsOk}\label{wxuriisok}
-
-\constfunc{bool}{IsOk}{\void}
-
-Returns true if this is a valid URI. 
+Returns \true if the User component of the URI exists.

 
 
 \membersection{wxURI::IsReference}\label{wxuriisreference}
 
 \constfunc{bool}{IsReference}{\void}
 
 
 
 \membersection{wxURI::IsReference}\label{wxuriisreference}
 
 \constfunc{bool}{IsReference}{\void}
 

-Returns true if a valid [absolute] URI, otherwise this URI
+Returns \true if a valid [absolute] URI, otherwise this URI

 is a URI reference and not a full URI, and IsReference
 is a URI reference and not a full URI, and IsReference

-returns false.
+returns \false.

 
 
 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
 
 
 
 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
 

-\func{void}{operator ==}{\param{const wxURI& }{uricomp}}
+\func{void}{operator ==}{\param{const wxURI\& }{uricomp}}

 
 

-Compares this URI to another URI, and returns true if 
-this URI equals uricomp, otherwise it returns false.
+Compares this URI to another URI, and returns \true if 
+this URI equals \arg{uricomp}, otherwise it returns \false.

 
 \docparam{uricomp}{URI to compare to}
 
 
 
 \docparam{uricomp}{URI to compare to}
 
 

-\membersection{wxURI::Extract}\label{wxuriextract}
-
-\func{static const wxChar*}{Extract}{\param{const wxChar*}{uri}}
-
-Used to determine where a URI ends in a string.
-
-Returns the position at which parsing stopped
-(will return NULL on malformed URIs).
-
-\docparam{uri}{String to create from}
-
-

 \membersection{wxURI::Resolve}\label{wxuriresolve}
 
 \membersection{wxURI::Resolve}\label{wxuriresolve}
 

-\func{void}{Resolve}{\param{const wxURI\& }{base}, \param{const bool\& }{bStrict = true}}
+\func{void}{Resolve}{\param{const wxURI\& }{base}, \param{int }{flags = \texttt{wxURI\_STRICT}}}

 
 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
 
 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


@@ -351,6 +350,22 @@ of the base's is merged with this URI's path, resulting in the URI
 "http://mysite.com/john/mydir".
 
 \docparam{base}{Base URI to inherit from.  Must be a full URI and not a reference}
 "http://mysite.com/john/mydir".
 
 \docparam{base}{Base URI to inherit from.  Must be a full URI and not a reference}

-\docparam{bStrict}{If false, some compatability layers are enabled to allow 
-                   loopholes from RFCs prior to 2396}
+\docparam{flags}{Currently either \texttt{wxURI\_STRICT} or $0$, in non-strict
+mode some compatibility layers are enabled to allow loopholes from RFCs prior
+to 2396}
+
+\membersection{wxURI::Unescape}\label{wxuriunescape}
+
+\func{wxString}{Unescape}{\param{const wxString\& }{uri}}
+
+Translates all escape sequences (% hex hex) of \arg{uri} into
+normal characters and returns the result.
+
+This is the preferred over deprecated wxURL::ConvertFromURI.
+
+If you want to unescape an entire wxURI, use \helpref{BuildUnescapedURI}{wxuribuildunescapeduri} instead,
+as it performs some optimizations over this method.
+
+\docparam{uri}{string with escaped characters to convert}
+