]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/htparser.tex
*** empty log message ***
[wxWidgets.git] / docs / latex / wx / htparser.tex
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::SetFS}\label{wxhtmlparsersetfs}
44
45 \func{void}{SetFS}{\param{wxFileSystem }{*fs}}
46
47 Sets the virtual file system that will be used to request additional
48 files. (For example {\tt <IMG>} tag handler requests wxFSFile with the
49 image data.)
50
51 \membersection{wxHtmlParser::GetFS}\label{wxhtmlparsergetfs}
52
53 \constfunc{wxFileSystem*}{GetFS}{\void}
54
55 Returns pointer to the file system. Because each tag handler has
56 reference to it's parent parser it can easily request the file by
57 calling
58
59 \begin{verbatim}
60 wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg");
61 \end{verbatim}
62
63 \membersection{wxHtmlParser::Parse}\label{wxhtmlparserparse}
64
65 \func{wxObject*}{Parse}{\param{const wxString\& }{source}}
66
67 Proceeds parsing of the document. This is end-user method. You can simply
68 call it when you need to obtain parsed output (which is parser-specific)
69
70 The method does these things:
71
72 \begin{enumerate}
73 \item calls \helpref{InitParser(source)}{wxhtmlparserinitparser}
74 \item calls \helpref{DoParsing}{wxhtmlparserdoparsing}
75 \item calls \helpref{GetProduct}{wxhtmlparsergetproduct}
76 \item calls \helpref{DoneParser}{wxhtmlparserdoneparser}
77 \item returns value returned by GetProduct
78 \end{enumerate}
79
80 You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.
81
82 \membersection{wxHtmlParser::InitParser}\label{wxhtmlparserinitparser}
83
84 \func{virtual void}{InitParser}{\param{const wxString\& }{source}}
85
86 Setups the parser for parsing the {\it source} string. (Should be overriden
87 in derived class)
88
89 \membersection{wxHtmlParser::DoneParser}\label{wxhtmlparserdoneparser}
90
91 \func{virtual void}{DoneParser}{\void}
92
93 This must be called after DoParsing().
94
95 \membersection{wxHtmlParser::DoParsing}\label{wxhtmlparserdoparsing}
96
97 \func{void}{DoParsing}{\param{int }{begin\_pos}, \param{int }{end\_pos}}
98
99 \func{void}{DoParsing}{\void}
100
101 Parses the m\_Source from begin\_pos to end\_pos-1.
102 (in noparams version it parses whole m\_Source)
103
104 \membersection{wxHtmlParser::GetProduct}\label{wxhtmlparsergetproduct}
105
106 \func{virtual wxObject*}{GetProduct}{\void}
107
108 Returns product of parsing. Returned value is result of parsing
109 of the document. The type of this result depends on internal
110 representation in derived parser (but it must be derived from wxObject!).
111
112 See wxHtmlWinParser for details.
113
114 \membersection{wxHtmlParser::AddTagHandler}\label{wxhtmlparseraddtaghandler}
115
116 \func{virtual void}{AddTagHandler}{\param{wxHtmlTagHandler }{*handler}}
117
118 Adds handler to the internal list (\& hash table) of handlers. This
119 method should not be called directly by user but rather by derived class'
120 constructor.
121
122 This adds the handler to this {\bf instance} of wxHtmlParser, not to
123 all objects of this class! (Static front-end to AddTagHandler is provided
124 by wxHtmlWinParser).
125
126 All handlers are deleted on object deletion.
127
128 \membersection{wxHtmlParser::GetSource}\label{wxhtmlparsergetsource}
129
130 \func{wxString*}{GetSource}{\void}
131
132 Returns pointer to the source being parsed.
133
134 \membersection{wxHtmlParser::GetTempData}\label{wxhtmlparsergettempdata}
135
136 \func{virtual wxList*}{GetTempData}{\void}
137
138 This method returns list of wxObjects that represents
139 all data allocated by the parser. These can't be freed
140 by the destructor because they must be valid as long as
141 GetProduct's return value is valid - the caller must
142 explicitly call
143
144 \begin{verbatim}
145 delete (MyParser -> GetTempData());
146 \end{verbatim}
147
148 to free the memory (this method always sets the list to delete its contents).
149
150 \wxheading{Example}
151
152 Why is this neccessary? Imagine wxHtmlWinParser: when handling
153 a FONT tag it creates some fonts. These fonts are then used by wxHtmlWindow
154 to display the text. But the wxHtmWinParser object is needed only when parsing
155 the document - it may be deleted then. But fonts CAN'T be deleted - they
156 must exist as long as the window is displaying text.
157
158 GetTempData() solves the problem.
159
160 \membersection{wxHtmlParser::AddText}\label{wxhtmlparseraddword}
161
162 \func{virtual void}{AddWord}{\param{const char* }{txt}}
163
164 Must be overwriten in derived class.
165
166 This method is called by \helpref{DoParsing}{wxhtmlparserdoparsing}
167 each time a part of text is parsed. {\it txt} is NOT only one word, it is
168 substring of input. It is not formatted or preprocessed (so white spaces are
169 unmodified).
170
171 \membersection{wxHtmlParser::AddTag}\label{wxhtmlparseraddtag}
172
173 \func{void}{AddTag}{\param{const wxHtmlTag\& }{tag}}
174
175 This may (and may not) be overwriten in derived class.
176
177 This method is called each time new tag is about to be added.
178 {\it tag} contains information about the tag. (See \helpref{wxHtmlTag}{wxhtmltag}
179 for details.)
180
181 Default (wxHtmlParser) behaviour is this:
182 First it finds a handler capable of handling this tag and then it calls
183 handler's HandleTag method.
184