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