]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/html/htmlpars.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: html/htmlpars.h
3 // Purpose: interface of wxHtmlTagHandler
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxHtmlTagHandler
17 @see @ref overview_html_handlers, wxHtmlTag
19 class wxHtmlTagHandler
: public wxObject
28 Returns list of supported tags.
29 The list is in uppercase and tags are delimited by ','.
30 Example: @c "I,B,FONT,P"
32 virtual wxString
GetSupportedTags() = 0;
35 This is the core method of each handler. It is called each time
36 one of supported tags is detected. @a tag contains all necessary
37 info (see wxHtmlTag for details).
42 bool MyHandler::HandleTag(const wxHtmlTag& tag)
45 // change state of parser (e.g. set bold face)
48 // restore original state of parser
52 You shouldn't call ParseInner() if the tag is not paired with an ending one.
54 @return @true if ParseInner() was called, @false otherwise.
56 virtual bool HandleTag(const wxHtmlTag
& tag
) = 0;
59 This method calls parser's wxHtmlParser::DoParsing method
60 for the string between this tag and the paired ending tag:
62 ...<A HREF="x.htm">Hello, world!</A>...
65 In this example, a call to ParseInner() (with @a tag pointing to A tag)
66 will parse 'Hello, world!'.
68 void ParseInner(const wxHtmlTag
& tag
);
71 Assigns @a parser to this handler. Each @b instance of handler
72 is guaranteed to be called only from the parser.
74 virtual void SetParser(wxHtmlParser parser
);
78 This attribute is used to access parent parser. It is protected so that
79 it can't be accessed by user but can be accessed from derived classes.
81 wxHtmlParser
* m_Parser
;
89 Classes derived from this handle the @b generic parsing of HTML documents: it
90 scans the document and divide it into blocks of tags (where one block consists
91 of beginning and ending tag and of text between these two tags).
93 It is independent from wxHtmlWindow and can be used as stand-alone parser.
95 It uses system of tag handlers to parse the HTML document. Tag handlers
96 are not statically shared by all instances but are created for each
97 wxHtmlParser instance. The reason is that the handler may contain
98 document-specific temporary data used during parsing (e.g. complicated
99 structures like tables).
101 Typically the user calls only the wxHtmlParser::Parse method.
106 @see @ref overview_html_cells, @ref overview_html_handlers, wxHtmlTag
117 This may (and may not) be overwritten in derived class.
119 This method is called each time new tag is about to be added.
120 @a tag contains information about the tag. (See wxHtmlTag for details.)
122 Default (wxHtmlParser) behaviour is this: first it finds a handler capable
123 of handling this tag and then it calls handler's HandleTag() method.
125 virtual void AddTag(const wxHtmlTag
& tag
);
128 Adds handler to the internal list ( hash table) of handlers.
129 This method should not be called directly by user but rather by derived class'
132 This adds the handler to this @b instance of wxHtmlParser, not to
133 all objects of this class!
134 (Static front-end to AddTagHandler is provided by wxHtmlWinParser).
136 All handlers are deleted on object deletion.
138 virtual void AddTagHandler(wxHtmlTagHandler handler
);
141 Must be overwritten in derived class.
143 This method is called by DoParsing() each time a part of text is parsed.
144 @a txt is NOT only one word, it is substring of input.
145 It is not formatted or preprocessed (so white spaces are unmodified).
147 virtual void AddWord(const wxString
& txt
);
150 Parses the m_Source from @a begin_pos to @a end_pos - 1.
152 void DoParsing(int begin_pos
, int end_pos
);
155 Parses the whole m_Source.
160 This must be called after DoParsing().
162 virtual void DoneParser();
165 Returns pointer to the file system. Because each tag handler has
166 reference to it is parent parser it can easily request the file by
169 wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg");
172 wxFileSystem
* GetFS() const;
175 Returns product of parsing.
176 Returned value is result of parsing of the document.
178 The type of this result depends on internal representation in derived
179 parser (but it must be derived from wxObject!).
180 See wxHtmlWinParser for details.
182 virtual wxObject
* GetProduct() = 0;
185 Returns pointer to the source being parsed.
187 wxString
* GetSource();
190 Setups the parser for parsing the @a source string.
191 (Should be overridden in derived class)
193 virtual void InitParser(const wxString
& source
);
196 Opens given URL and returns @c wxFSFile object that can be used to read data
197 from it. This method may return @NULL in one of two cases: either the URL doesn't
198 point to any valid resource or the URL is blocked by overridden implementation
199 of @e OpenURL in derived class.
202 Indicates type of the resource. Is one of:
203 - wxHTML_URL_PAGE: Opening a HTML page.
204 - wxHTML_URL_IMAGE: Opening an image.
205 - wxHTML_URL_OTHER: Opening a resource that doesn't fall into
211 Always use this method in tag handlers instead of GetFS()->OpenFile()
212 because it can block the URL and is thus more secure.
213 Default behaviour is to call wxHtmlWindow::OnOpeningURL of the associated
214 wxHtmlWindow object (which may decide to block the URL or redirect it to
215 another one),if there's any, and always open the URL if the parser is not
216 used with wxHtmlWindow.
217 Returned wxFSFile object is not guaranteed to point to url, it might have
220 virtual wxFSFile
* OpenURL(wxHtmlURLType type
, const wxString
& url
) const;
223 Proceeds parsing of the document. This is end-user method. You can simply
224 call it when you need to obtain parsed output (which is parser-specific).
226 The method does these things:
227 -# calls InitParser(source)
229 -# calls GetProduct()
230 -# calls DoneParser()
231 -# returns value returned by GetProduct()
233 You shouldn't use InitParser(), DoParsing(), GetProduct() or DoneParser() directly.
235 wxObject
* Parse(const wxString
& source
);
238 Restores parser's state before last call to PushTagHandler().
240 void PopTagHandler();
243 Forces the handler to handle additional tags
244 (not returned by wxHtmlTagHandler::GetSupportedTags).
245 The handler should already be added to this parser.
250 List of tags (in same format as GetSupportedTags()'s return value).
251 The parser will redirect these tags to handler (until call to PopTagHandler()).
255 Imagine you want to parse following pseudo-html structure:
258 <param name="one" value="1">
259 <param name="two" value="2">
263 <param program="text.exe">
267 It is obvious that you cannot use only one tag handler for \<param\> tag.
268 Instead you must use context-sensitive handlers for \<param\> inside \<myitems\>
269 and \<param\> inside \<execute\>.
270 This is the preferred solution:
273 TAG_HANDLER_BEGIN(MYITEM, "MYITEMS")
274 TAG_HANDLER_PROC(tag)
278 m_Parser -> PushTagHandler(this, "PARAM");
280 m_Parser -> PopTagHandler();
284 TAG_HANDLER_END(MYITEM)
287 void PushTagHandler(wxHtmlTagHandler
* handler
,
288 const wxString
& tags
);
291 Sets the virtual file system that will be used to request additional files.
292 (For example @c IMG tag handler requests wxFSFile with the image data.)
294 void SetFS(wxFileSystem fs
);
297 Call this function to interrupt parsing from a tag handler.
298 No more tags will be parsed afterward. This function may only be called
299 from Parse() or any function called by it (i.e. from tag handlers).
301 virtual void StopParsing();