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 a403848a389c364a1a97be0882c63dd12baee0a0..bc373af4be7d1fae66828dedf25457b5263ab87f 100644 (file)
--- a/docs/latex/wx/htparser.tex
+++ b/docs/latex/wx/htparser.tex
@@ -3,30 +3,33 @@
 % htmlparser.tex at 14/Mar/99 20:13:37
 %
 
 % htmlparser.tex at 14/Mar/99 20:13:37
 %
 

-

 \section{\class{wxHtmlParser}}\label{wxhtmlparser}
 
 \section{\class{wxHtmlParser}}\label{wxhtmlparser}
 

-This class handles {\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
-2 tags).
+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
 (Julian Smart's idea of speech-only HTML viewer or wget-like utility -
 see InetGet sample for example).
 
 It uses system of tag handlers to parse the HTML document. Tag handlers
 
 It is independent from wxHtmlWindow and can be used as stand-alone parser
 (Julian Smart's idea of speech-only HTML viewer or wget-like utility -
 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
 wxHtmlParser instance. The reason is that the handler may contain
 document-specific temporary data used during parsing (e.g. complicated

-structures like tables)
+structures like tables).

 
 

-Typically the user calls only \helpref{Parse}{wxhtmlparserparse} method.
+Typically the user calls only the \helpref{Parse}{wxhtmlparserparse} method.

 
 \wxheading{Derived from}
 
 wxObject
 
 
 \wxheading{Derived from}
 
 wxObject
 

+\wxheading{Include files}
+
+<wx/html/htmlpars.h>
+

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


@@ -35,157 +38,229 @@ wxObject
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-

 \membersection{wxHtmlParser::wxHtmlParser}\label{wxhtmlparserwxhtmlparser}
 
 \func{}{wxHtmlParser}{\void}
 
 Constructor.
 
 \membersection{wxHtmlParser::wxHtmlParser}\label{wxhtmlparserwxhtmlparser}
 
 \func{}{wxHtmlParser}{\void}
 
 Constructor.
 

+\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 overwritten 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.)
+
+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 char* }{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::GetProduct}\label{wxhtmlparsergetproduct}

 
 

-\membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse}
+\func{virtual wxObject*}{GetProduct}{\void}

 
 

-\func{wxObject*}{Parse}{\param{const wxString\& }{source}}
+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!).

 
 

-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)
+See wxHtmlWinParser for details.

 
 

-The method does these things:
+\membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource}

 
 

-\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}
+\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::OpenURL}\label{wxhtmlparseropenurl}

 
 

-\membersection{wxHtmlParser::DoneParser}\label{wxhtmlparserdoneparser}
+\func{virtual wxFSFile*}{OpenURL}{\param{wxHtmlURLType }{type}, \param{const wxString\& }{url}}

 
 

-\func{virtual void}{DoneParser}{\void}
+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.

 
 

-This must be called after DoParsing().
+\wxheading{Parameters}

 
 

+\docparam{type}{Indicates type of the resource. Is one of:

 
 

-\membersection{wxHtmlParser::DoParsing}\label{wxhtmlparserdoparsing}
+\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{void}{DoParsing}{\param{int }{begin\_pos}, \param{int }{end\_pos}}
+\docparam{url}{URL being opened.}

 
 

-\func{void}{DoParsing}{\void}
+\wxheading{Notes}

 
 

-Parses the m\_Source from begin\_pos to end\_pos-1.
-(in noparams version it parses whole m\_Source)
+Always use this method in tag handlers instead of {\tt GetFS()->OpenFile()} 
+because it can block the URL and is thus more secure.

 
 

-\membersection{wxHtmlParser::GetProduct}\label{wxhtmlparsergetproduct}
+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.

 
 

-\func{virtual wxObject*}{GetProduct}{\void}
+Returned {\tt wxFSFile} object is not guaranteed to point to {\it url}, it might
+have been redirected!

 
 

-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!).
+\membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse}

 
 

-See wxHtmlWinParser for details.
+\func{wxObject*}{Parse}{\param{const wxString\& }{source}}

 
 

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

 
 

-\membersection{wxHtmlParser::AddTagHandler}\label{wxhtmlparseraddtaghandler}
+The method does these things:

 
 

-\func{virtual void}{AddTagHandler}{\param{wxHtmlTagHandler }{*handler}}
+\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}

 
 

-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.
+You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.

 
 

-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)
+\membersection{wxHtmlParser::PushTagHandler}\label{wxhtmlparserpushtaghandler}

 
 

-All handlers are deleted on object deletion.
+\func{void}{PushTagHandler}{\param{wxHtmlTagHandler* }{handler}, \param{const wxString\& }{tags}}

 
 

-\membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource}
+Forces the handler to handle additional tags 
+(not returned by \helpref{GetSupportedTags}{wxhtmltaghandlergetsupportedtags}). 
+The handler should already be added to this parser.

 
 

-\func{wxString*}{GetSource}{\void}
+\wxheading{Parameters}

 
 

-Returns pointer to the source being parsed.
+\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}). }
+
+\wxheading{Example}

 
 

+Imagine you want to parse following pseudo-html structure:

 
 

-\membersection{wxHtmlParser::GetTempData}\label{wxhtmlparsergettempdata}
+\begin{verbatim}
+<myitems>
+    <param name="one" value="1">
+    <param name="two" value="2">
+</myitems>
+
+<execute>
+    <param program="text.exe">
+</execute>
+\end{verbatim}

 
 

-\func{virtual wxList*}{GetTempData}{\void}
+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 method returns list of wxObjects that represents
-all data allocated by the parser. These can't be freeded
-by destructor because they must be valid as long as
-GetProduct's return value is valid - the caller must
-explicitly call
+This is the preferred solution:

 
 \begin{verbatim}
 
 \begin{verbatim}

-delete (MyParser -> GetTempData());
+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}
 
 \end{verbatim}
 

-to free the memory (this method always sets the list to delete its contents)
-
-\wxheading{Example}

 
 

-Why is this neccessary? Imagine wxHtmlWinParser : when handling
-FONT tag it creates some fonts. These fonts are then used by wxHtmlWindow
-to display the text. But 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.
+\membersection{wxHtmlParser::PopTagHandler}\label{wxhtmlparserpoptaghandler}

 
 

-GetTempData() solves the problem.
+\func{void}{PopTagHandler}{\void}

 
 

-\membersection{wxHtmlParser::AddText}\label{wxhtmlparseraddword}
+Restores parser's state before last call to 
+\helpref{PushTagHandler}{wxhtmlparserpushtaghandler}.

 
 

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

 
 

-Must be overwriten in derived class.
+\membersection{wxHtmlParser::SetFS}\label{wxhtmlparsersetfs}

 
 

-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)
+\func{void}{SetFS}{\param{wxFileSystem }{*fs}}

 
 

-\membersection{wxHtmlParser::AddTag}\label{wxhtmlparseraddtag}
+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.)

 
 

-\func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}}
+\membersection{wxHtmlParser::StopParsing}\label{wxhtmlparserstopparsing}

 
 

-This may (and may not) be overwriten in derived class.
+\func{void}{StopParsing}{\void}

 
 

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

 
 

-Default (wxHtmlParser) behaviour is this :
-First it finds a handler capable of handling this tag and then it calls
-handler's HandleTag method.