]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: html/htmlpars.h | |
e54c96f1 | 3 | // Purpose: interface of wxHtmlTagHandler |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxHtmlTagHandler | |
7c913512 | 11 | |
5bddd46d | 12 | @todo describe me |
7c913512 | 13 | |
23324ae1 FM |
14 | @library{wxhtml} |
15 | @category{html} | |
7c913512 | 16 | |
5bddd46d | 17 | @see @ref overview_html_handlers, wxHtmlTag |
23324ae1 FM |
18 | */ |
19 | class wxHtmlTagHandler : public wxObject | |
20 | { | |
21 | public: | |
22 | /** | |
23 | Constructor. | |
24 | */ | |
25 | wxHtmlTagHandler(); | |
26 | ||
27 | /** | |
5bddd46d FM |
28 | Returns list of supported tags. |
29 | The list is in uppercase and tags are delimited by ','. | |
30 | Example: @c "I,B,FONT,P" | |
23324ae1 | 31 | */ |
da1ed74c | 32 | virtual wxString GetSupportedTags() = 0; |
23324ae1 FM |
33 | |
34 | /** | |
35 | This is the core method of each handler. It is called each time | |
4cc4bfaf | 36 | one of supported tags is detected. @a tag contains all necessary |
23324ae1 | 37 | info (see wxHtmlTag for details). |
5bddd46d FM |
38 | |
39 | Example: | |
40 | ||
41 | @code | |
42 | bool MyHandler::HandleTag(const wxHtmlTag& tag) | |
43 | { | |
44 | ... | |
45 | // change state of parser (e.g. set bold face) | |
46 | ParseInner(tag); | |
47 | ... | |
48 | // restore original state of parser | |
49 | } | |
50 | @endcode | |
51 | ||
52 | You shouldn't call ParseInner() if the tag is not paired with an ending one. | |
53 | ||
54 | @return @true if ParseInner() was called, @false otherwise. | |
23324ae1 | 55 | */ |
da1ed74c | 56 | virtual bool HandleTag(const wxHtmlTag& tag) = 0; |
23324ae1 | 57 | |
5e6e278d FM |
58 | /** |
59 | Assigns @a parser to this handler. Each @b instance of handler | |
60 | is guaranteed to be called only from the parser. | |
61 | */ | |
62 | virtual void SetParser(wxHtmlParser* parser); | |
63 | ||
64 | protected: | |
65 | ||
23324ae1 FM |
66 | /** |
67 | This method calls parser's wxHtmlParser::DoParsing method | |
68 | for the string between this tag and the paired ending tag: | |
5bddd46d FM |
69 | @code |
70 | ...<A HREF="x.htm">Hello, world!</A>... | |
71 | @endcode | |
72 | ||
73 | In this example, a call to ParseInner() (with @a tag pointing to A tag) | |
23324ae1 FM |
74 | will parse 'Hello, world!'. |
75 | */ | |
76 | void ParseInner(const wxHtmlTag& tag); | |
77 | ||
23324ae1 | 78 | /** |
23324ae1 FM |
79 | This attribute is used to access parent parser. It is protected so that |
80 | it can't be accessed by user but can be accessed from derived classes. | |
81 | */ | |
5bddd46d | 82 | wxHtmlParser* m_Parser; |
23324ae1 FM |
83 | }; |
84 | ||
85 | ||
e54c96f1 | 86 | |
23324ae1 FM |
87 | /** |
88 | @class wxHtmlParser | |
7c913512 | 89 | |
23324ae1 | 90 | Classes derived from this handle the @b generic parsing of HTML documents: it |
5bddd46d FM |
91 | scans the document and divide it into blocks of tags (where one block consists |
92 | of beginning and ending tag and of text between these two tags). | |
7c913512 | 93 | |
5bddd46d | 94 | It is independent from wxHtmlWindow and can be used as stand-alone parser. |
7c913512 | 95 | |
23324ae1 FM |
96 | It uses system of tag handlers to parse the HTML document. Tag handlers |
97 | are not statically shared by all instances but are created for each | |
98 | wxHtmlParser instance. The reason is that the handler may contain | |
99 | document-specific temporary data used during parsing (e.g. complicated | |
100 | structures like tables). | |
7c913512 | 101 | |
23324ae1 | 102 | Typically the user calls only the wxHtmlParser::Parse method. |
7c913512 | 103 | |
23324ae1 FM |
104 | @library{wxhtml} |
105 | @category{html} | |
7c913512 | 106 | |
5bddd46d | 107 | @see @ref overview_html_cells, @ref overview_html_handlers, wxHtmlTag |
23324ae1 | 108 | */ |
7c913512 | 109 | class wxHtmlParser |
23324ae1 FM |
110 | { |
111 | public: | |
112 | /** | |
113 | Constructor. | |
114 | */ | |
115 | wxHtmlParser(); | |
116 | ||
23324ae1 | 117 | /** |
5bddd46d FM |
118 | Adds handler to the internal list ( hash table) of handlers. |
119 | This method should not be called directly by user but rather by derived class' | |
23324ae1 | 120 | constructor. |
5bddd46d | 121 | |
23324ae1 | 122 | This adds the handler to this @b instance of wxHtmlParser, not to |
5bddd46d FM |
123 | all objects of this class! |
124 | (Static front-end to AddTagHandler is provided by wxHtmlWinParser). | |
125 | ||
23324ae1 FM |
126 | All handlers are deleted on object deletion. |
127 | */ | |
5267aefd | 128 | virtual void AddTagHandler(wxHtmlTagHandler* handler); |
23324ae1 FM |
129 | |
130 | /** | |
131 | Must be overwritten in derived class. | |
5bddd46d FM |
132 | |
133 | This method is called by DoParsing() each time a part of text is parsed. | |
134 | @a txt is NOT only one word, it is substring of input. | |
135 | It is not formatted or preprocessed (so white spaces are unmodified). | |
23324ae1 FM |
136 | */ |
137 | virtual void AddWord(const wxString& txt); | |
138 | ||
23324ae1 | 139 | /** |
5bddd46d | 140 | Parses the m_Source from @a begin_pos to @a end_pos - 1. |
23324ae1 | 141 | */ |
a44f3b5a | 142 | void DoParsing(const const_iterator& begin_pos, const const_iterator& end_pos); |
5bddd46d FM |
143 | |
144 | /** | |
145 | Parses the whole m_Source. | |
146 | */ | |
7c913512 | 147 | void DoParsing(); |
23324ae1 FM |
148 | |
149 | /** | |
150 | This must be called after DoParsing(). | |
151 | */ | |
152 | virtual void DoneParser(); | |
153 | ||
154 | /** | |
155 | Returns pointer to the file system. Because each tag handler has | |
156 | reference to it is parent parser it can easily request the file by | |
5bddd46d FM |
157 | calling: |
158 | @code | |
159 | wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg"); | |
160 | @endcode | |
23324ae1 | 161 | */ |
328f5751 | 162 | wxFileSystem* GetFS() const; |
23324ae1 FM |
163 | |
164 | /** | |
5bddd46d FM |
165 | Returns product of parsing. |
166 | Returned value is result of parsing of the document. | |
167 | ||
168 | The type of this result depends on internal representation in derived | |
169 | parser (but it must be derived from wxObject!). | |
23324ae1 FM |
170 | See wxHtmlWinParser for details. |
171 | */ | |
da1ed74c | 172 | virtual wxObject* GetProduct() = 0; |
23324ae1 FM |
173 | |
174 | /** | |
175 | Returns pointer to the source being parsed. | |
176 | */ | |
5267aefd | 177 | const wxString* GetSource(); |
23324ae1 FM |
178 | |
179 | /** | |
5bddd46d FM |
180 | Setups the parser for parsing the @a source string. |
181 | (Should be overridden in derived class) | |
23324ae1 FM |
182 | */ |
183 | virtual void InitParser(const wxString& source); | |
184 | ||
185 | /** | |
186 | Opens given URL and returns @c wxFSFile object that can be used to read data | |
187 | from it. This method may return @NULL in one of two cases: either the URL doesn't | |
188 | point to any valid resource or the URL is blocked by overridden implementation | |
189 | of @e OpenURL in derived class. | |
5bddd46d | 190 | |
7c913512 | 191 | @param type |
4cc4bfaf | 192 | Indicates type of the resource. Is one of: |
5bddd46d FM |
193 | - wxHTML_URL_PAGE: Opening a HTML page. |
194 | - wxHTML_URL_IMAGE: Opening an image. | |
195 | - wxHTML_URL_OTHER: Opening a resource that doesn't fall into | |
196 | any other category. | |
7c913512 | 197 | @param url |
4cc4bfaf | 198 | URL being opened. |
5bddd46d FM |
199 | |
200 | @note | |
201 | Always use this method in tag handlers instead of GetFS()->OpenFile() | |
202 | because it can block the URL and is thus more secure. | |
203 | Default behaviour is to call wxHtmlWindow::OnOpeningURL of the associated | |
204 | wxHtmlWindow object (which may decide to block the URL or redirect it to | |
205 | another one),if there's any, and always open the URL if the parser is not | |
206 | used with wxHtmlWindow. | |
207 | Returned wxFSFile object is not guaranteed to point to url, it might have | |
208 | been redirected! | |
23324ae1 | 209 | */ |
fadc2df6 | 210 | virtual wxFSFile* OpenURL(wxHtmlURLType type, const wxString& url) const; |
23324ae1 FM |
211 | |
212 | /** | |
213 | Proceeds parsing of the document. This is end-user method. You can simply | |
5bddd46d FM |
214 | call it when you need to obtain parsed output (which is parser-specific). |
215 | ||
23324ae1 | 216 | The method does these things: |
5bddd46d FM |
217 | -# calls InitParser(source) |
218 | -# calls DoParsing() | |
219 | -# calls GetProduct() | |
220 | -# calls DoneParser() | |
221 | -# returns value returned by GetProduct() | |
222 | ||
223 | You shouldn't use InitParser(), DoParsing(), GetProduct() or DoneParser() directly. | |
23324ae1 FM |
224 | */ |
225 | wxObject* Parse(const wxString& source); | |
226 | ||
227 | /** | |
5bddd46d | 228 | Restores parser's state before last call to PushTagHandler(). |
23324ae1 FM |
229 | */ |
230 | void PopTagHandler(); | |
231 | ||
232 | /** | |
7c913512 FM |
233 | Forces the handler to handle additional tags |
234 | (not returned by wxHtmlTagHandler::GetSupportedTags). | |
23324ae1 | 235 | The handler should already be added to this parser. |
5bddd46d | 236 | |
7c913512 | 237 | @param handler |
4cc4bfaf | 238 | the handler |
7c913512 | 239 | @param tags |
5bddd46d FM |
240 | List of tags (in same format as GetSupportedTags()'s return value). |
241 | The parser will redirect these tags to handler (until call to PopTagHandler()). | |
242 | ||
243 | Example: | |
244 | ||
245 | Imagine you want to parse following pseudo-html structure: | |
246 | @code | |
247 | <myitems> | |
248 | <param name="one" value="1"> | |
249 | <param name="two" value="2"> | |
250 | </myitems> | |
251 | ||
252 | <execute> | |
253 | <param program="text.exe"> | |
254 | </execute> | |
255 | @endcode | |
256 | ||
257 | It is obvious that you cannot use only one tag handler for \<param\> tag. | |
258 | Instead you must use context-sensitive handlers for \<param\> inside \<myitems\> | |
259 | and \<param\> inside \<execute\>. | |
260 | This is the preferred solution: | |
261 | ||
262 | @code | |
263 | TAG_HANDLER_BEGIN(MYITEM, "MYITEMS") | |
264 | TAG_HANDLER_PROC(tag) | |
265 | { | |
266 | // ...something... | |
267 | ||
268 | m_Parser -> PushTagHandler(this, "PARAM"); | |
269 | ParseInner(tag); | |
270 | m_Parser -> PopTagHandler(); | |
271 | ||
272 | // ...something... | |
273 | } | |
274 | TAG_HANDLER_END(MYITEM) | |
275 | @endcode | |
23324ae1 FM |
276 | */ |
277 | void PushTagHandler(wxHtmlTagHandler* handler, | |
278 | const wxString& tags); | |
279 | ||
280 | /** | |
5bddd46d FM |
281 | Sets the virtual file system that will be used to request additional files. |
282 | (For example @c IMG tag handler requests wxFSFile with the image data.) | |
23324ae1 | 283 | */ |
5267aefd | 284 | void SetFS(wxFileSystem* fs); |
23324ae1 FM |
285 | |
286 | /** | |
5bddd46d FM |
287 | Call this function to interrupt parsing from a tag handler. |
288 | No more tags will be parsed afterward. This function may only be called | |
289 | from Parse() or any function called by it (i.e. from tag handlers). | |
23324ae1 | 290 | */ |
adaaa686 | 291 | virtual void StopParsing(); |
5e6e278d FM |
292 | |
293 | protected: | |
294 | ||
295 | /** | |
296 | This may (and may not) be overwritten in derived class. | |
297 | ||
298 | This method is called each time new tag is about to be added. | |
299 | @a tag contains information about the tag. (See wxHtmlTag for details.) | |
300 | ||
301 | Default (wxHtmlParser) behaviour is this: first it finds a handler capable | |
302 | of handling this tag and then it calls handler's HandleTag() method. | |
303 | */ | |
304 | virtual void AddTag(const wxHtmlTag& tag); | |
23324ae1 | 305 | }; |
e54c96f1 | 306 |