X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/22d6efa851642c6a69174278fc50f712f41e2271..a977709b11432e05af48e205cc02c0a0ad4ecf16:/docs/latex/wx/htparser.tex diff --git a/docs/latex/wx/htparser.tex b/docs/latex/wx/htparser.tex index 7d486f7170..91dd28305d 100644 --- a/docs/latex/wx/htparser.tex +++ b/docs/latex/wx/htparser.tex @@ -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}, @@ -40,51 +44,53 @@ wxObject 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 } tag handler requests wxFSFile with the -image data.) +This may (and may not) be overwriten in derived class. -\membersection{wxHtmlParser::GetFS}\label{wxhtmlparsergetfs} +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.) -\constfunc{wxFileSystem*}{GetFS}{\void} +Default (wxHtmlParser) behaviour is this: +First it finds a handler capable of handling this tag and then it calls +handler's HandleTag method. -Returns pointer to the file system. Because each tag handler has -reference to it's parent parser it can easily request the file by -calling +\membersection{wxHtmlParser::AddTagHandler}\label{wxhtmlparseraddtaghandler} -\begin{verbatim} -wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg"); -\end{verbatim} +\func{virtual void}{AddTagHandler}{\param{wxHtmlTagHandler }{*handler}} -\membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse} +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. -\func{wxObject*}{Parse}{\param{const wxString\& }{source}} +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). -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) +All handlers are deleted on object deletion. -The method does these things: +\membersection{wxHtmlParser::AddText}\label{wxhtmlparseraddword} -\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{virtual void}{AddWord}{\param{const char* }{txt}} -You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly. +Must be overwriten in derived class. -\membersection{wxHtmlParser::InitParser}\label{wxhtmlparserinitparser} +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{virtual void}{InitParser}{\param{const wxString\& }{source}} +\membersection{wxHtmlParser::DoParsing}\label{wxhtmlparserdoparsing} -Setups the parser for parsing the {\it source} string. (Should be overriden -in derived class) +\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} @@ -92,14 +98,17 @@ in derived class) This must be called after DoParsing(). -\membersection{wxHtmlParser::DoParsing}\label{wxhtmlparserdoparsing} +\membersection{wxHtmlParser::GetFS}\label{wxhtmlparsergetfs} -\func{void}{DoParsing}{\param{int }{begin\_pos}, \param{int }{end\_pos}} +\constfunc{wxFileSystem*}{GetFS}{\void} -\func{void}{DoParsing}{\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 -Parses the m\_Source from begin\_pos to end\_pos-1. -(in noparams version it parses whole m\_Source) +\begin{verbatim} +wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg"); +\end{verbatim} \membersection{wxHtmlParser::GetProduct}\label{wxhtmlparsergetproduct} @@ -111,74 +120,139 @@ representation in derived parser (but it must be derived from wxObject!). See wxHtmlWinParser for details. -\membersection{wxHtmlParser::AddTagHandler}\label{wxhtmlparseraddtaghandler} +\membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource} -\func{virtual void}{AddTagHandler}{\param{wxHtmlTagHandler }{*handler}} +\func{wxString*}{GetSource}{\void} -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. +Returns pointer to the source being parsed. -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::InitParser}\label{wxhtmlparserinitparser} -\membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource} +\func{virtual void}{InitParser}{\param{const wxString\& }{source}} -\func{wxString*}{GetSource}{\void} +Setups the parser for parsing the {\it source} string. (Should be overridden +in derived class) -Returns pointer to the source being parsed. +\membersection{wxHtmlParser::OpenURL}\label{wxhtmlparseropenurl} -\membersection{wxHtmlParser::GetTempData}\label{wxhtmlparsergettempdata} +\func{virtual wxFSFile*}{OpenURL}{\param{wxHtmlURLType }{type}, \param{const wxString\& }{url}} -\func{virtual wxList*}{GetTempData}{\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 overriden implementation +of {\it OpenURL} in derived class. -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{Parameters} -\begin{verbatim} -delete (MyParser -> GetTempData()); -\end{verbatim} +\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} -to free the memory (this method always sets the list to delete its contents). +\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} -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. +Imagine you want to parse following pseudo-html structure: -GetTempData() solves the problem. +\begin{verbatim} + + + + + + + + +\end{verbatim} -\membersection{wxHtmlParser::AddText}\label{wxhtmlparseraddword} +It is obvious that you cannot use only one tag handler for tag. +Instead you must use context-sensitive handlers for inside +and inside . -\func{virtual void}{AddWord}{\param{const char* }{txt}} +This is the preferred solution: -Must be overwriten in derived class. +\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} -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::PopTagHandler}\label{wxhtmlparserpoptaghandler} -\func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}} +\func{void}{PopTagHandler}{\void} -This may (and may not) be overwriten in derived class. +Restores parser's state before last call to +\helpref{PushTagHandler}{wxhtmlparserpushtaghandler}. -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::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 } tag handler requests wxFSFile with the +image data.)