define _HPUX_SOURCE under HP-UX, otherwise many things are not defined in standard...

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

diff --git a/docs/latex/wx/htparser.tex b/docs/latex/wx/htparser.tex
index 93984433903ee65373c4f6777cbb663057acb83f..bc373af4be7d1fae66828dedf25457b5263ab87f 100644 (file)
--- a/docs/latex/wx/htparser.tex
+++ b/docs/latex/wx/htparser.tex
@@ -5,9 +5,9 @@
 
 \section{\class{wxHtmlParser}}\label{wxhtmlparser}
 
 
 \section{\class{wxHtmlParser}}\label{wxhtmlparser}
 

-This class handles the {\bf generic} parsing of HTML document: it scans
+Classes derived from this handle the {\bf generic} parsing of HTML documents: it scans

 the document and divide it into blocks of tags (where one block
 the document and divide it into blocks of tags (where one block

-consists of begining and ending tag and of text between these
+consists of beginning and ending tag and of text between these

 two tags).
 
 It is independent from wxHtmlWindow and can be used as stand-alone parser
 two tags).
 
 It is independent from wxHtmlWindow and can be used as stand-alone parser


@@ -15,7 +15,7 @@ It is independent from wxHtmlWindow and can be used as stand-alone parser
 see InetGet sample for example).
 
 It uses system of tag handlers to parse the HTML document. Tag handlers
 see InetGet sample for example).
 
 It uses system of tag handlers to parse the HTML document. Tag handlers

-are not staticaly shared by all instances but are created for each
+are not statically shared by all instances but are created for each

 wxHtmlParser instance. The reason is that the handler may contain
 document-specific temporary data used during parsing (e.g. complicated
 structures like tables).
 wxHtmlParser instance. The reason is that the handler may contain
 document-specific temporary data used during parsing (e.g. complicated
 structures like tables).


@@ -48,7 +48,7 @@ Constructor.
 
 \func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}}
 
 
 \func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}}
 

-This may (and may not) be overwriten in derived class.
+This may (and may not) be overwritten in derived class.

 
 This method is called each time new tag is about to be added. 
 {\it tag} contains information about the tag. (See \helpref{wxHtmlTag}{wxhtmltag}
 
 This method is called each time new tag is about to be added. 
 {\it tag} contains information about the tag. (See \helpref{wxHtmlTag}{wxhtmltag}


@@ -76,7 +76,7 @@ All handlers are deleted on object deletion.
 
 \func{virtual void}{AddWord}{\param{const char* }{txt}}
 
 
 \func{virtual void}{AddWord}{\param{const char* }{txt}}
 

-Must be overwriten in derived class.
+Must be overwritten in derived class.

 
 This method is called by \helpref{DoParsing}{wxhtmlparserdoparsing}
 each time a part of text is parsed. {\it txt} is NOT only one word, it is
 
 This method is called by \helpref{DoParsing}{wxhtmlparserdoparsing}
 each time a part of text is parsed. {\it txt} is NOT only one word, it is


@@ -103,7 +103,7 @@ This must be called after DoParsing().
 \constfunc{wxFileSystem*}{GetFS}{\void}
 
 Returns pointer to the file system. Because each tag handler has
 \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}
 calling
 
 \begin{verbatim}


@@ -131,9 +131,44 @@ Returns pointer to the source being parsed.
 
 \func{virtual void}{InitParser}{\param{const wxString\& }{source}}
 
 
 \func{virtual void}{InitParser}{\param{const wxString\& }{source}}
 

-Setups the parser for parsing the {\it source} string. (Should be overriden
+Setups the parser for parsing the {\it source} string. (Should be overridden

 in derived class)
 
 in derived class)
 

+\membersection{wxHtmlParser::OpenURL}\label{wxhtmlparseropenurl}
+
+\func{virtual wxFSFile*}{OpenURL}{\param{wxHtmlURLType }{type}, \param{const wxString\& }{url}}
+
+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 overridden implementation
+of {\it OpenURL} in derived class.
+
+\wxheading{Parameters}
+
+\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}}
+
+\docparam{url}{URL being opened.}
+
+\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}
 
 \func{wxObject*}{Parse}{\param{const wxString\& }{source}}
 \membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse}
 
 \func{wxObject*}{Parse}{\param{const wxString\& }{source}}


@@ -153,11 +188,9 @@ The method does these things:
 
 You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.
 
 
 You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.
 

-
-

 \membersection{wxHtmlParser::PushTagHandler}\label{wxhtmlparserpushtaghandler}
 
 \membersection{wxHtmlParser::PushTagHandler}\label{wxhtmlparserpushtaghandler}
 

-\func{void}{PushTagHandler}{\param{wxHtmlTagHandler* }{handler}, \param{wxString }{tags}}
+\func{void}{PushTagHandler}{\param{wxHtmlTagHandler* }{handler}, \param{const wxString\& }{tags}}

 
 Forces the handler to handle additional tags 
 (not returned by \helpref{GetSupportedTags}{wxhtmltaghandlergetsupportedtags}). 
 
 Forces the handler to handle additional tags 
 (not returned by \helpref{GetSupportedTags}{wxhtmltaghandlergetsupportedtags}). 


@@ -188,7 +221,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>.        
 
 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")
 
 \begin{verbatim}
 TAG_HANDLER_BEGIN(MYITEM, "MYITEMS")


@@ -222,3 +255,12 @@ Sets the virtual file system that will be used to request additional
 files. (For example {\tt <IMG>} tag handler requests wxFSFile with the
 image data.)
 
 files. (For example {\tt <IMG>} tag handler requests wxFSFile with the
 image data.)
 

+\membersection{wxHtmlParser::StopParsing}\label{wxhtmlparserstopparsing}
+
+\func{void}{StopParsing}{\void}
+
+Call this function to interrupt parsing from a tag handler. No more tags
+will be parsed afterward. This function may only be called from
+\helpref{wxHtmlParser::Parse}{wxhtmlparserparse} or any function called
+by it (i.e. from tag handlers).
+