GetSelection --> GetStringSelection

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

diff --git a/docs/latex/wx/htparser.tex b/docs/latex/wx/htparser.tex
index a403848a389c364a1a97be0882c63dd12baee0a0..b9d848e6093c221c79740a0590ce58f9fa200358 100644 (file)
--- a/docs/latex/wx/htparser.tex
+++ b/docs/latex/wx/htparser.tex
@@ -3,13 +3,12 @@
 % 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
+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
 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).
+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 -
 
 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 -


@@ -19,14 +18,18 @@ 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
 wxHtmlParser instance. The reason is that the handler may contain
 document-specific temporary data used during parsing (e.g. complicated
 are not staticaly 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)
+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,61 +38,59 @@ 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}{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 <IMG>} 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}}

 
 

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

 
 

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

 
 

-\func{wxObject*}{Parse}{\param{const wxString\& }{source}}
+All handlers are deleted on object deletion.

 
 

-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::AddText}\label{wxhtmlparseraddword}

 
 

-The method does these things:
+\func{virtual void}{AddWord}{\param{const char* }{txt}}

 
 

-\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}
+Must be overwriten in derived class.

 
 

-You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.
+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::InitParser}\label{wxhtmlparserinitparser}
+\membersection{wxHtmlParser::DoParsing}\label{wxhtmlparserdoparsing}

 
 

-\func{virtual void}{InitParser}{\param{const wxString\& }{source}}
+\func{void}{DoParsing}{\param{int }{begin\_pos}, \param{int }{end\_pos}}

 
 

-Setups the parser for parsing the {\it source} string. (Should be overriden
-in derived class)
+\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}
 
 
 \membersection{wxHtmlParser::DoneParser}\label{wxhtmlparserdoneparser}
 


@@ -97,15 +98,17 @@ in derived class)
 
 This must be called after DoParsing().
 
 
 This must be called after DoParsing().
 

+\membersection{wxHtmlParser::GetFS}\label{wxhtmlparsergetfs}

 
 

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


@@ -117,75 +120,105 @@ representation in derived parser (but it must be derived from wxObject!).
 
 See wxHtmlWinParser for details.
 
 
 See wxHtmlWinParser for details.
 

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

 
 

-\membersection{wxHtmlParser::AddTagHandler}\label{wxhtmlparseraddtaghandler}
+\func{wxString*}{GetSource}{\void}

 
 

-\func{virtual void}{AddTagHandler}{\param{wxHtmlTagHandler }{*handler}}
+Returns pointer to the source being parsed.

 
 

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

 
 

-All handlers are deleted on object deletion.
+\func{virtual void}{InitParser}{\param{const wxString\& }{source}}

 
 

-\membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource}
+Setups the parser for parsing the {\it source} string. (Should be overridden
+in derived class)

 
 

-\func{wxString*}{GetSource}{\void}
+\membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse}

 
 

-Returns pointer to the source being parsed.
+\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::GetTempData}\label{wxhtmlparsergettempdata}

 
 

-\func{virtual wxList*}{GetTempData}{\void}

 
 

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

 
 

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

 
 

-to free the memory (this method always sets the list to delete its contents)
+\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}
 
 
 \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.
+Imagine you want to parse following pseudo-html structure:

 
 

-GetTempData() solves the problem.
+\begin{verbatim}
+<myitems>
+    <param name="one" value="1">
+    <param name="two" value="2">
+</myitems>
+
+<execute>
+    <param program="text.exe">
+</execute>
+\end{verbatim}

 
 

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

 
 

-\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 <IMG>} tag handler requests wxFSFile with the
+image data.)
+