compilation fix for wxUSE_STL==1 in DoGetSibling()

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

diff --git a/docs/latex/wx/htparser.tex b/docs/latex/wx/htparser.tex
index 7d486f7170e89aea6cb577936cd7097021f86952..5dceb68da80d8bbac18c19f9e70d08e2b95c786e 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).


@@ -26,6 +26,14 @@ Typically the user calls only the \helpref{Parse}{wxhtmlparserparse} method.
 
 wxObject
 
 
 wxObject
 

+\wxheading{Include files}
+
+<wx/html/htmlpars.h>
+
+\wxheading{Library}
+
+\helpref{wxHtml}{librarieslist}
+

 \wxheading{See also}
 
 \helpref{Cells Overview}{cells},
 \wxheading{See also}
 
 \helpref{Cells Overview}{cells},


@@ -40,145 +48,223 @@ wxObject
 
 Constructor.
 
 
 Constructor.
 

-\membersection{wxHtmlParser::SetFS}\label{wxhtmlparsersetfs}
+\membersection{wxHtmlParser::AddTag}\label{wxhtmlparseraddtag}

 
 

-\func{void}{SetFS}{\param{wxFileSystem }{*fs}}
+\func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}}

 
 

-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.)
+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}
+for details.)
+
+Default (wxHtmlParser) behaviour is this:
+First it finds a handler capable of handling this tag and then it calls
+handler's HandleTag method.
+
+\membersection{wxHtmlParser::AddTagHandler}\label{wxhtmlparseraddtaghandler}
+
+\func{virtual void}{AddTagHandler}{\param{wxHtmlTagHandler }{*handler}}
+
+Adds handler to the internal list (\& hash table) of handlers. This
+method should not be called directly by user but rather by derived class'
+constructor.
+
+This adds the handler to this {\bf instance} of wxHtmlParser, not to
+all objects of this class! (Static front-end to AddTagHandler is provided
+by wxHtmlWinParser).
+
+All handlers are deleted on object deletion.
+
+\membersection{wxHtmlParser::AddText}\label{wxhtmlparseraddword}
+
+\func{virtual void}{AddWord}{\param{const wxString\& }{txt}}
+
+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
+substring of input. It is not formatted or preprocessed (so white spaces are
+unmodified).
+
+\membersection{wxHtmlParser::DoParsing}\label{wxhtmlparserdoparsing}
+
+\func{void}{DoParsing}{\param{int }{begin\_pos}, \param{int }{end\_pos}}
+
+\func{void}{DoParsing}{\void}
+
+Parses the m\_Source from begin\_pos to end\_pos-1.
+(in noparams version it parses whole m\_Source)
+
+\membersection{wxHtmlParser::DoneParser}\label{wxhtmlparserdoneparser}
+
+\func{virtual void}{DoneParser}{\void}
+
+This must be called after DoParsing().

 
 \membersection{wxHtmlParser::GetFS}\label{wxhtmlparsergetfs}
 
 \constfunc{wxFileSystem*}{GetFS}{\void}
 
 Returns pointer to the file system. Because each tag handler has
 
 \membersection{wxHtmlParser::GetFS}\label{wxhtmlparsergetfs}
 
 \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}
 wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg");
 \end{verbatim}
 
 calling
 
 \begin{verbatim}
 wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg");
 \end{verbatim}
 

-\membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse}
+\membersection{wxHtmlParser::GetProduct}\label{wxhtmlparsergetproduct}

 
 

-\func{wxObject*}{Parse}{\param{const wxString\& }{source}}
+\func{virtual wxObject*}{GetProduct}{\void}

 
 

-Proceeds parsing of the document. This is end-user method. You can simply
-call it when you need to obtain parsed output (which is parser-specific)
+Returns product of parsing. Returned value is result of parsing
+of the document. The type of this result depends on internal
+representation in derived parser (but it must be derived from wxObject!).

 
 

-The method does these things:
+See wxHtmlWinParser for details.

 
 

-\begin{enumerate}
-\item calls \helpref{InitParser(source)}{wxhtmlparserinitparser}
-\item calls \helpref{DoParsing}{wxhtmlparserdoparsing}
-\item calls \helpref{GetProduct}{wxhtmlparsergetproduct}
-\item calls \helpref{DoneParser}{wxhtmlparserdoneparser}
-\item returns value returned by GetProduct
-\end{enumerate}
+\membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource}
+
+\func{wxString*}{GetSource}{\void}
+
+Returns pointer to the source being parsed.

 
 

-You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.

 
 \membersection{wxHtmlParser::InitParser}\label{wxhtmlparserinitparser}
 
 \func{virtual void}{InitParser}{\param{const wxString\& }{source}}
 
 
 \membersection{wxHtmlParser::InitParser}\label{wxhtmlparserinitparser}
 
 \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::DoneParser}\label{wxhtmlparserdoneparser}
+\membersection{wxHtmlParser::OpenURL}\label{wxhtmlparseropenurl}

 
 

-\func{virtual void}{DoneParser}{\void}
+\func{virtual wxFSFile*}{OpenURL}{\param{wxHtmlURLType }{type}, \param{const wxString\& }{url}}

 
 

-This must be called after DoParsing().
+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.

 
 

-\membersection{wxHtmlParser::DoParsing}\label{wxhtmlparserdoparsing}
+\wxheading{Parameters}

 
 

-\func{void}{DoParsing}{\param{int }{begin\_pos}, \param{int }{end\_pos}}
+\docparam{type}{Indicates type of the resource. Is one of:

 
 

-\func{void}{DoParsing}{\void}
+\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}}

 
 

-Parses the m\_Source from begin\_pos to end\_pos-1.
-(in noparams version it parses whole m\_Source)
+\docparam{url}{URL being opened.}

 
 

-\membersection{wxHtmlParser::GetProduct}\label{wxhtmlparsergetproduct}
+\wxheading{Notes}

 
 

-\func{virtual wxObject*}{GetProduct}{\void}
+Always use this method in tag handlers instead of {\tt GetFS()->OpenFile()} 
+because it can block the URL and is thus more secure.

 
 

-Returns product of parsing. Returned value is result of parsing
-of the document. The type of this result depends on internal
-representation in derived parser (but it must be derived from wxObject!).
+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.

 
 

-See wxHtmlWinParser for details.
+Returned {\tt wxFSFile} object is not guaranteed to point to {\it url}, it might
+have been redirected!

 
 

-\membersection{wxHtmlParser::AddTagHandler}\label{wxhtmlparseraddtaghandler}
+\membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse}

 
 

-\func{virtual void}{AddTagHandler}{\param{wxHtmlTagHandler }{*handler}}
+\func{wxObject*}{Parse}{\param{const wxString\& }{source}}

 
 

-Adds handler to the internal list (\& hash table) of handlers. This
-method should not be called directly by user but rather by derived class'
-constructor.
+Proceeds parsing of the document. This is end-user method. You can simply
+call it when you need to obtain parsed output (which is parser-specific)

 
 

-This adds the handler to this {\bf instance} of wxHtmlParser, not to
-all objects of this class! (Static front-end to AddTagHandler is provided
-by wxHtmlWinParser).
+The method does these things:

 
 

-All handlers are deleted on object deletion.
+\begin{enumerate}\itemsep=0pt
+\item calls \helpref{InitParser(source)}{wxhtmlparserinitparser}
+\item calls \helpref{DoParsing}{wxhtmlparserdoparsing}
+\item calls \helpref{GetProduct}{wxhtmlparsergetproduct}
+\item calls \helpref{DoneParser}{wxhtmlparserdoneparser}
+\item returns value returned by GetProduct
+\end{enumerate}

 
 

-\membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource}
+You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.

 
 

-\func{wxString*}{GetSource}{\void}
+\membersection{wxHtmlParser::PushTagHandler}\label{wxhtmlparserpushtaghandler}

 
 

-Returns pointer to the source being parsed.
+\func{void}{PushTagHandler}{\param{wxHtmlTagHandler* }{handler}, \param{const wxString\& }{tags}}
+
+Forces the handler to handle additional tags 
+(not returned by \helpref{GetSupportedTags}{wxhtmltaghandlergetsupportedtags}). 
+The handler should already be added to this parser.

 
 

-\membersection{wxHtmlParser::GetTempData}\label{wxhtmlparsergettempdata}
+\wxheading{Parameters}

 
 

-\func{virtual wxList*}{GetTempData}{\void}
+\docparam{handler}{the handler}
+\docparam{tags}{List of tags (in same format as GetSupportedTags's return value). The parser
+will redirect these tags to {\it handler} (until call to \helpref{PopTagHandler}{wxhtmlparserpoptaghandler}). }

 
 

-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
+\wxheading{Example}
+
+Imagine you want to parse following pseudo-html structure:

 
 \begin{verbatim}
 
 \begin{verbatim}

-delete (MyParser -> GetTempData());
+<myitems>
+    <param name="one" value="1">
+    <param name="two" value="2">
+</myitems>
+
+<execute>
+    <param program="text.exe">
+</execute>

 \end{verbatim}
 
 \end{verbatim}
 

-to free the memory (this method always sets the list to delete its contents).
+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>.        

 
 

-\wxheading{Example}
+This is the preferred solution:

 
 

-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.
+\begin{verbatim}
+TAG_HANDLER_BEGIN(MYITEM, "MYITEMS")
+    TAG_HANDLER_PROC(tag)
+    {
+        // ...something...
+
+        m_Parser -> PushTagHandler(this, "PARAM");
+        ParseInner(tag);
+        m_Parser -> PopTagHandler();
+
+        // ...something...
+     }
+TAG_HANDLER_END(MYITEM)
+\end{verbatim}

 
 

-GetTempData() solves the problem.

 
 

-\membersection{wxHtmlParser::AddText}\label{wxhtmlparseraddword}
+\membersection{wxHtmlParser::PopTagHandler}\label{wxhtmlparserpoptaghandler}

 
 

-\func{virtual void}{AddWord}{\param{const char* }{txt}}
+\func{void}{PopTagHandler}{\void}

 
 

-Must be overwriten in derived class.
+Restores parser's state before last call to 
+\helpref{PushTagHandler}{wxhtmlparserpushtaghandler}.

 
 

-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
-substring of input. It is not formatted or preprocessed (so white spaces are
-unmodified).

 
 

-\membersection{wxHtmlParser::AddTag}\label{wxhtmlparseraddtag}
+\membersection{wxHtmlParser::SetFS}\label{wxhtmlparsersetfs}

 
 

-\func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}}
+\func{void}{SetFS}{\param{wxFileSystem }{*fs}}

 
 

-This may (and may not) be overwriten in derived class.
+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.)

 
 

-This method is called each time new tag is about to be added. 
-{\it tag} contains information about the tag. (See \helpref{wxHtmlTag}{wxhtmltag}
-for details.)
+\membersection{wxHtmlParser::StopParsing}\label{wxhtmlparserstopparsing}

 
 

-Default (wxHtmlParser) behaviour is this:
-First it finds a handler capable of handling this tag and then it calls
-handler's HandleTag method.
+\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).