X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0eb8c9383b5a12a7ccc99b5546323ef5015d31da..81c882b613b5d99ddb1e5ab69fcd7ebccc287025:/docs/latex/wx/htparser.tex diff --git a/docs/latex/wx/htparser.tex b/docs/latex/wx/htparser.tex index c682e2be75..91b94ea4dc 100644 --- a/docs/latex/wx/htparser.tex +++ b/docs/latex/wx/htparser.tex @@ -5,9 +5,9 @@ \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 -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 @@ -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 -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). @@ -26,6 +26,10 @@ Typically the user calls only the \helpref{Parse}{wxhtmlparserparse} method. wxObject +\wxheading{Include files} + + + \wxheading{See also} \helpref{Cells Overview}{cells}, @@ -44,7 +48,7 @@ Constructor. \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} @@ -70,9 +74,9 @@ All handlers are deleted on object deletion. \membersection{wxHtmlParser::AddText}\label{wxhtmlparseraddword} -\func{virtual void}{AddWord}{\param{const char* }{txt}} +\func{virtual void}{AddWord}{\param{const wxString\& }{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 @@ -99,7 +103,7 @@ This must be called after DoParsing(). \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} @@ -122,38 +126,48 @@ See wxHtmlWinParser for details. 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} @@ -174,11 +188,9 @@ The method does these things: You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly. - - \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}). @@ -209,7 +221,7 @@ It is obvious that you cannot use only one tag handler for tag. Instead you must use context-sensitive handlers for inside and inside . -This is the prefered solution: +This is the preferred solution: \begin{verbatim} TAG_HANDLER_BEGIN(MYITEM, "MYITEMS") @@ -243,3 +255,12 @@ Sets the virtual file system that will be used to request additional files. (For example {\tt } 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). +