]>
Commit | Line | Data |
---|---|---|
704a4b75 VS |
1 | % |
2 | % automatically generated by HelpGen from | |
3 | % htmlparser.tex at 14/Mar/99 20:13:37 | |
4 | % | |
5 | ||
704a4b75 VS |
6 | \section{\class{wxHtmlParser}}\label{wxhtmlparser} |
7 | ||
22d6efa8 | 8 | This class handles the {\bf generic} parsing of HTML document: it scans |
704a4b75 VS |
9 | the document and divide it into blocks of tags (where one block |
10 | consists of begining and ending tag and of text between these | |
22d6efa8 | 11 | two tags). |
704a4b75 VS |
12 | |
13 | It is independent from wxHtmlWindow and can be used as stand-alone parser | |
14 | (Julian Smart's idea of speech-only HTML viewer or wget-like utility - | |
3660fc40 | 15 | see InetGet sample for example). |
704a4b75 VS |
16 | |
17 | It uses system of tag handlers to parse the HTML document. Tag handlers | |
3660fc40 | 18 | are not staticaly shared by all instances but are created for each |
704a4b75 VS |
19 | wxHtmlParser instance. The reason is that the handler may contain |
20 | document-specific temporary data used during parsing (e.g. complicated | |
22d6efa8 | 21 | structures like tables). |
704a4b75 | 22 | |
22d6efa8 | 23 | Typically the user calls only the \helpref{Parse}{wxhtmlparserparse} method. |
704a4b75 VS |
24 | |
25 | \wxheading{Derived from} | |
26 | ||
27 | wxObject | |
28 | ||
9704b250 VS |
29 | \wxheading{Include files} |
30 | ||
31 | <wx/html/htmlpars.h> | |
32 | ||
704a4b75 VS |
33 | \wxheading{See also} |
34 | ||
35 | \helpref{Cells Overview}{cells}, | |
36 | \helpref{Tag Handlers Overview}{handlers}, | |
37 | \helpref{wxHtmlTag}{wxhtmltag} | |
38 | ||
39 | \latexignore{\rtfignore{\wxheading{Members}}} | |
40 | ||
704a4b75 VS |
41 | \membersection{wxHtmlParser::wxHtmlParser}\label{wxhtmlparserwxhtmlparser} |
42 | ||
43 | \func{}{wxHtmlParser}{\void} | |
44 | ||
3660fc40 | 45 | Constructor. |
704a4b75 | 46 | |
559fe022 | 47 | \membersection{wxHtmlParser::AddTag}\label{wxhtmlparseraddtag} |
704a4b75 | 48 | |
559fe022 | 49 | \func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}} |
704a4b75 | 50 | |
559fe022 | 51 | This may (and may not) be overwriten in derived class. |
704a4b75 | 52 | |
559fe022 VS |
53 | This method is called each time new tag is about to be added. |
54 | {\it tag} contains information about the tag. (See \helpref{wxHtmlTag}{wxhtmltag} | |
55 | for details.) | |
704a4b75 | 56 | |
559fe022 VS |
57 | Default (wxHtmlParser) behaviour is this: |
58 | First it finds a handler capable of handling this tag and then it calls | |
59 | handler's HandleTag method. | |
704a4b75 | 60 | |
559fe022 | 61 | \membersection{wxHtmlParser::AddTagHandler}\label{wxhtmlparseraddtaghandler} |
704a4b75 | 62 | |
559fe022 | 63 | \func{virtual void}{AddTagHandler}{\param{wxHtmlTagHandler }{*handler}} |
704a4b75 | 64 | |
559fe022 VS |
65 | Adds handler to the internal list (\& hash table) of handlers. This |
66 | method should not be called directly by user but rather by derived class' | |
67 | constructor. | |
704a4b75 | 68 | |
559fe022 VS |
69 | This adds the handler to this {\bf instance} of wxHtmlParser, not to |
70 | all objects of this class! (Static front-end to AddTagHandler is provided | |
71 | by wxHtmlWinParser). | |
704a4b75 | 72 | |
559fe022 | 73 | All handlers are deleted on object deletion. |
704a4b75 | 74 | |
559fe022 | 75 | \membersection{wxHtmlParser::AddText}\label{wxhtmlparseraddword} |
704a4b75 | 76 | |
559fe022 | 77 | \func{virtual void}{AddWord}{\param{const char* }{txt}} |
704a4b75 | 78 | |
559fe022 | 79 | Must be overwriten in derived class. |
704a4b75 | 80 | |
559fe022 VS |
81 | This method is called by \helpref{DoParsing}{wxhtmlparserdoparsing} |
82 | each time a part of text is parsed. {\it txt} is NOT only one word, it is | |
83 | substring of input. It is not formatted or preprocessed (so white spaces are | |
84 | unmodified). | |
704a4b75 | 85 | |
559fe022 | 86 | \membersection{wxHtmlParser::DoParsing}\label{wxhtmlparserdoparsing} |
704a4b75 | 87 | |
559fe022 VS |
88 | \func{void}{DoParsing}{\param{int }{begin\_pos}, \param{int }{end\_pos}} |
89 | ||
90 | \func{void}{DoParsing}{\void} | |
91 | ||
92 | Parses the m\_Source from begin\_pos to end\_pos-1. | |
93 | (in noparams version it parses whole m\_Source) | |
704a4b75 | 94 | |
704a4b75 VS |
95 | \membersection{wxHtmlParser::DoneParser}\label{wxhtmlparserdoneparser} |
96 | ||
97 | \func{virtual void}{DoneParser}{\void} | |
98 | ||
99 | This must be called after DoParsing(). | |
100 | ||
559fe022 | 101 | \membersection{wxHtmlParser::GetFS}\label{wxhtmlparsergetfs} |
704a4b75 | 102 | |
559fe022 | 103 | \constfunc{wxFileSystem*}{GetFS}{\void} |
704a4b75 | 104 | |
559fe022 VS |
105 | Returns pointer to the file system. Because each tag handler has |
106 | reference to it's parent parser it can easily request the file by | |
107 | calling | |
704a4b75 | 108 | |
559fe022 VS |
109 | \begin{verbatim} |
110 | wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg"); | |
111 | \end{verbatim} | |
704a4b75 VS |
112 | |
113 | \membersection{wxHtmlParser::GetProduct}\label{wxhtmlparsergetproduct} | |
114 | ||
115 | \func{virtual wxObject*}{GetProduct}{\void} | |
116 | ||
3660fc40 RD |
117 | Returns product of parsing. Returned value is result of parsing |
118 | of the document. The type of this result depends on internal | |
704a4b75 VS |
119 | representation in derived parser (but it must be derived from wxObject!). |
120 | ||
121 | See wxHtmlWinParser for details. | |
122 | ||
704a4b75 VS |
123 | \membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource} |
124 | ||
125 | \func{wxString*}{GetSource}{\void} | |
126 | ||
127 | Returns pointer to the source being parsed. | |
128 | ||
704a4b75 | 129 | |
559fe022 | 130 | \membersection{wxHtmlParser::InitParser}\label{wxhtmlparserinitparser} |
704a4b75 | 131 | |
559fe022 | 132 | \func{virtual void}{InitParser}{\param{const wxString\& }{source}} |
704a4b75 | 133 | |
559fe022 VS |
134 | Setups the parser for parsing the {\it source} string. (Should be overriden |
135 | in derived class) | |
704a4b75 | 136 | |
559fe022 | 137 | \membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse} |
704a4b75 | 138 | |
559fe022 | 139 | \func{wxObject*}{Parse}{\param{const wxString\& }{source}} |
704a4b75 | 140 | |
559fe022 VS |
141 | Proceeds parsing of the document. This is end-user method. You can simply |
142 | call it when you need to obtain parsed output (which is parser-specific) | |
704a4b75 | 143 | |
559fe022 | 144 | The method does these things: |
704a4b75 | 145 | |
448af9a4 | 146 | \begin{enumerate}\itemsep=0pt |
559fe022 VS |
147 | \item calls \helpref{InitParser(source)}{wxhtmlparserinitparser} |
148 | \item calls \helpref{DoParsing}{wxhtmlparserdoparsing} | |
149 | \item calls \helpref{GetProduct}{wxhtmlparsergetproduct} | |
150 | \item calls \helpref{DoneParser}{wxhtmlparserdoneparser} | |
151 | \item returns value returned by GetProduct | |
152 | \end{enumerate} | |
704a4b75 | 153 | |
559fe022 VS |
154 | You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly. |
155 | ||
0eb8c938 VS |
156 | |
157 | ||
158 | \membersection{wxHtmlParser::PushTagHandler}\label{wxhtmlparserpushtaghandler} | |
159 | ||
160 | \func{void}{PushTagHandler}{\param{wxHtmlTagHandler* }{handler}, \param{wxString }{tags}} | |
161 | ||
162 | Forces the handler to handle additional tags | |
163 | (not returned by \helpref{GetSupportedTags}{wxhtmltaghandlergetsupportedtags}). | |
164 | The handler should already be added to this parser. | |
165 | ||
166 | \wxheading{Parameters} | |
167 | ||
168 | \docparam{handler}{the handler} | |
169 | \docparam{tags}{List of tags (in same format as GetSupportedTags's return value). The parser | |
170 | will redirect these tags to {\it handler} (until call to \helpref{PopTagHandler}{wxhtmlparserpoptaghandler}). } | |
171 | ||
172 | \wxheading{Example} | |
173 | ||
174 | Imagine you want to parse following pseudo-html structure: | |
175 | ||
176 | \begin{verbatim} | |
177 | <myitems> | |
178 | <param name="one" value="1"> | |
179 | <param name="two" value="2"> | |
180 | </myitems> | |
181 | ||
182 | <execute> | |
183 | <param program="text.exe"> | |
184 | </execute> | |
185 | \end{verbatim} | |
186 | ||
187 | It is obvious that you cannot use only one tag handler for <param> tag. | |
188 | Instead you must use context-sensitive handlers for <param> inside <myitems> | |
189 | and <param> inside <execute>. | |
190 | ||
191 | This is the prefered solution: | |
192 | ||
193 | \begin{verbatim} | |
194 | TAG_HANDLER_BEGIN(MYITEM, "MYITEMS") | |
195 | TAG_HANDLER_PROC(tag) | |
196 | { | |
197 | // ...something... | |
198 | ||
199 | m_Parser -> PushTagHandler(this, "PARAM"); | |
200 | ParseInner(tag); | |
201 | m_Parser -> PopTagHandler(); | |
202 | ||
203 | // ...something... | |
204 | } | |
205 | TAG_HANDLER_END(MYITEM) | |
206 | \end{verbatim} | |
207 | ||
208 | ||
209 | \membersection{wxHtmlParser::PopTagHandler}\label{wxhtmlparserpoptaghandler} | |
210 | ||
211 | \func{void}{PopTagHandler}{\void} | |
212 | ||
213 | Restores parser's state before last call to | |
214 | \helpref{PushTagHandler}{wxhtmlparserpushtaghandler}. | |
215 | ||
216 | ||
559fe022 VS |
217 | \membersection{wxHtmlParser::SetFS}\label{wxhtmlparsersetfs} |
218 | ||
219 | \func{void}{SetFS}{\param{wxFileSystem }{*fs}} | |
220 | ||
221 | Sets the virtual file system that will be used to request additional | |
222 | files. (For example {\tt <IMG>} tag handler requests wxFSFile with the | |
223 | image data.) | |
22d6efa8 | 224 |