Some work on GTK focus handling and events.

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

diff --git a/docs/latex/wx/htparser.tex b/docs/latex/wx/htparser.tex
index c682e2be75a71598383f44e4b5279b8dedb77c47..91dd28305dfb29eec5b508cb9a84fec879c0ef4d 100644 (file)
--- a/docs/latex/wx/htparser.tex
+++ b/docs/latex/wx/htparser.tex
@@ -26,6 +26,10 @@ Typically the user calls only the \helpref{Parse}{wxhtmlparserparse} method.
 
 wxObject
 
+\wxheading{Include files}
+
+<wx/html/htmlpars.h>
+
 \wxheading{See also}
 
 \helpref{Cells Overview}{cells},
@@ -99,7 +103,7 @@ This must be called after DoParsing().
 \constfunc{wxFileSystem*}{GetFS}{\void}
 
 Returns pointer to the file system. Because each tag handler has
-reference to it's parent parser it can easily request the file by
+reference to it is parent parser it can easily request the file by
 calling
 
 \begin{verbatim}
@@ -122,38 +126,47 @@ See wxHtmlWinParser for details.
 
 Returns pointer to the source being parsed.
 
-\membersection{wxHtmlParser::GetTempData}\label{wxhtmlparsergettempdata}
 
-\func{virtual wxList*}{GetTempData}{\void}
+\membersection{wxHtmlParser::InitParser}\label{wxhtmlparserinitparser}
 
-This method returns list of wxObjects that represents
-all data allocated by the parser. These can't be freed
-by the destructor because they must be valid as long as
-GetProduct's return value is valid - the caller must
-explicitly call
+\func{virtual void}{InitParser}{\param{const wxString\& }{source}}
 
-\begin{verbatim}
-delete (MyParser -> GetTempData());
-\end{verbatim}
+Setups the parser for parsing the {\it source} string. (Should be overridden
+in derived class)
 
-to free the memory (this method always sets the list to delete its contents).
+\membersection{wxHtmlParser::OpenURL}\label{wxhtmlparseropenurl}
 
-\wxheading{Example}
+\func{virtual wxFSFile*}{OpenURL}{\param{wxHtmlURLType }{type}, \param{const wxString\& }{url}}
 
-Why is this neccessary? Imagine wxHtmlWinParser: when handling
-a FONT tag it creates some fonts. These fonts are then used by wxHtmlWindow
-to display the text. But the wxHtmWinParser object is needed only when parsing
-the document - it may be deleted then. But fonts CAN'T be deleted - they
-must exist as long as the window is displaying text.
+Opens given URL and returns {\tt wxFSFile} object that can be used to read data
+from it. This method may return NULL in one of two cases: either the URL doesn't
+point to any valid resource or the URL is blocked by overriden implementation
+of {\it OpenURL} in derived class.
 
-GetTempData() solves the problem.
+\wxheading{Parameters}
 
-\membersection{wxHtmlParser::InitParser}\label{wxhtmlparserinitparser}
+\docparam{type}{Indicates type of the resource. Is one of
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf wxHTML\_URL\_PAGE}}{Opening a HTML page.}
+\twocolitem{{\bf wxHTML\_URL\_IMAGE}}{Opening an image.}
+\twocolitem{{\bf wxHTML\_URL\_OTHER}}{Opening a resource that doesn't fall into
+any other category.}
+\end{twocollist}}
 
-\func{virtual void}{InitParser}{\param{const wxString\& }{source}}
+\docparam{url}{URL being opened.}
 
-Setups the parser for parsing the {\it source} string. (Should be overriden
-in derived class)
+\wxheading{Notes}
+
+Always use this method in tag handlers instead of {\tt GetFS()->OpenFile()} 
+because it can block the URL and is thus more secure.
+
+Default behaviour is to call \helpref{wxHtmlWindow::OnOpeningURL}{wxhtmlwindowonopeningurl}
+of the associated wxHtmlWindow object (which may decide to block the URL or
+redirect it to another one),if there's any, and always open the URL if the 
+parser is not used with wxHtmlWindow.
+
+Returned {\tt wxFSFile} object is not guaranteed to point to {\it url}, it might
+have been redirected!
 
 \membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse}
 
@@ -209,7 +222,7 @@ It is obvious that you cannot use only one tag handler for <param> tag.
 Instead you must use context-sensitive handlers for <param> inside <myitems>
 and <param> inside <execute>.        
 
-This is the prefered solution:
+This is the preferred solution:
 
 \begin{verbatim}
 TAG_HANDLER_BEGIN(MYITEM, "MYITEMS")