added functions to read/write several elements at once (patch 754986)

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

%
% automatically generated by HelpGen from
% htmlparser.tex at 14/Mar/99 20:13:37
%

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

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

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

\wxheading{Derived from}

wxObject

\wxheading{Include files}

<wx/html/htmlpars.h>

\wxheading{See also}

\helpref{Cells Overview}{cells},
\helpref{Tag Handlers Overview}{handlers},
\helpref{wxHtmlTag}{wxhtmltag}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxHtmlParser::wxHtmlParser}\label{wxhtmlparserwxhtmlparser}

\func{}{wxHtmlParser}{\void}

Constructor.

\membersection{wxHtmlParser::AddTag}\label{wxhtmlparseraddtag}

\func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}}

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 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
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}

\membersection{wxHtmlParser::GetProduct}\label{wxhtmlparsergetproduct}

\func{virtual wxObject*}{GetProduct}{\void}

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

See wxHtmlWinParser for details.

\membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource}

\func{wxString*}{GetSource}{\void}

Returns pointer to the source being parsed.


\membersection{wxHtmlParser::InitParser}\label{wxhtmlparserinitparser}

\func{virtual void}{InitParser}{\param{const wxString\& }{source}}

Setups the parser for parsing the {\it source} string. (Should be overridden
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}}

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)

The method does these things:

\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}

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}}

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

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