This class handles the {\bf generic} parsing of HTML document: it scans
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
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).
wxObject
+\wxheading{Include files}
+
+<wx/html/htmlpars.h>
+
\wxheading{See also}
\helpref{Cells Overview}{cells},
\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}
\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
\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}
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 overridden 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:
-\func{virtual void}{InitParser}{\param{const wxString\& }{source}}
+\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}}
-Setups the parser for parsing the {\it source} string. (Should be overriden
-in derived class)
+\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}
The method does these things:
-\begin{enumerate}
+\begin{enumerate}\itemsep=0pt
\item calls \helpref{InitParser(source)}{wxhtmlparserinitparser}
\item calls \helpref{DoParsing}{wxhtmlparserdoparsing}
\item calls \helpref{GetProduct}{wxhtmlparsergetproduct}
You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.
+\membersection{wxHtmlParser::PushTagHandler}\label{wxhtmlparserpushtaghandler}
+
+\func{void}{PushTagHandler}{\param{wxHtmlTagHandler* }{handler}, \param{wxString }{tags}}
+
+Forces the handler to handle additional tags
+(not returned by \helpref{GetSupportedTags}{wxhtmltaghandlergetsupportedtags}).
+The handler should already be added to this parser.
+
+\wxheading{Parameters}
+
+\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:
+
+\begin{verbatim}
+<myitems>
+ <param name="one" value="1">
+ <param name="two" value="2">
+</myitems>
+
+<execute>
+ <param program="text.exe">
+</execute>
+\end{verbatim}
+
+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 preferred solution:
+
+\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}
+
+
+\membersection{wxHtmlParser::PopTagHandler}\label{wxhtmlparserpoptaghandler}
+
+\func{void}{PopTagHandler}{\void}
+
+Restores parser's state before last call to
+\helpref{PushTagHandler}{wxhtmlparserpushtaghandler}.
+
+
\membersection{wxHtmlParser::SetFS}\label{wxhtmlparsersetfs}
\func{void}{SetFS}{\param{wxFileSystem }{*fs}}
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).
+
projects / wxWidgets.git / blobdiff