1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: wxHTML Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">wxHTML Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_html_quickstart">wxHTML Quick Start</a><ul><li class="level2"><a href="#overview_html_quickstart_disphtml">Displaying HTML</a></li>
<li class="level2"><a href="#overview_html_quickstart_settingup">Setting up wxHtmlWindow</a></li>
<li class="level2"><a href="#overview_html_quickstart_custom">Customizing wxHtmlWindow</a></li>
</ul>
</li>
<li class="level1"><a href="#overview_html_printing">HTML Printing</a></li>
<li class="level1"><a href="#overview_html_helpformats">Help Files Format</a><ul><li class="level2"><a href="#overview_html_helpformats_hhp">Header file (.hhp)</a></li>
<li class="level2"><a href="#overview_html_helpformats_hhc">Contents file (.hhc)</a></li>
<li class="level2"><a href="#overview_html_helpformats_hhk">Index Files (.hhk)</a></li>
</ul>
</li>
<li class="level1"><a href="#overview_html_filters">Input Filters</a></li>
<li class="level1"><a href="#overview_html_cells">Cells and Containers</a><ul><li class="level2"><a href="#overview_html_cells_cells">Cells</a></li>
<li class="level2"><a href="#overview_html_cells_containers">Containers</a></li>
<li class="level2"><a href="#overview_html_cells_conttaghandler">Using Containers in Tag Handler</a></li>
</ul>
</li>
<li class="level1"><a href="#overview_html_handlers">Tag Handlers</a><ul><li class="level2"><a href="#overview_html_handlers_howworks">How it works</a></li>
<li class="level2"><a href="#overview_html_handlers_custom">Providing own tag handlers</a></li>
<li class="level2"><a href="#overview_html_handlers_tag">Tag handlers</a></li>
<li class="level2"><a href="#overview_html_handlers_modules">Tags Modules</a></li>
</ul>
</li>
<li class="level1"><a href="#overview_html_supptags">Supported HTML Tags</a><ul><li class="level2"><a href="#overview_html_supptags_commonvalues">Common Parameter Values</a></li>
<li class="level2"><a href="#overview_html_supptags_list">List of Supported Tags</a></li>
<li class="level2"><a href="#overview_html_suppstyles_list">Supported Styles</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>The wxHTML library provides classes for parsing and displaying HTML.</p>
<p>It is not intended to be a high-end HTML browser. If you are looking for something like that try <a href="http://www.mozilla.org/">http://www.mozilla.org/</a>.</p>
<p>wxHTML can be used as a generic rich text viewer - for example to display a nice About Box (like those of GNOME apps) or to display the result of database searching. There is a <a class="el" href="classwx_file_system.html" title="This class provides an interface for opening files on different file systems.">wxFileSystem</a> class which allows you to use your own virtual file systems.</p>
<p><a class="el" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a> supports tag handlers. This means that you can easily extend wxHtml library with new, unsupported tags. Not only that, you can even use your own application-specific tags!</p>
<p>See <code>src/html/m_*</code>.cpp files for details.</p>
<p>There is a generic <a class="el" href="classwx_html_parser.html" title="Classes derived from this handle the generic parsing of HTML documents: it scans the document and div...">wxHtmlParser</a> class, independent of <a class="el" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a>.</p>
<h1><a class="anchor" id="overview_html_quickstart"></a>
wxHTML Quick Start</h1>
<h2><a class="anchor" id="overview_html_quickstart_disphtml"></a>
Displaying HTML</h2>
<p>First of all, you must include <code>wx/wxhtml.h</code>.</p>
<p>Class <a class="el" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a> (derived from <a class="el" href="group__group__class__miscwnd.html#ga695bec5996cd4d5512d1a01cfdcf96a5" title="Scrolled window derived from wxPanel.">wxScrolledWindow</a>) is used to display HTML documents.</p>
<p>It has two important methods: <a class="el" href="classwx_html_window.html#ab7086e665bb533a34dc11ab29465db09" title="Unlike SetPage() this function first loads the HTML page from location and then displays it...">wxHtmlWindow::LoadPage</a> and <a class="el" href="classwx_html_window.html#ac6d0335b1bb749b498598fc5a3b32703" title="Sets the source of a page and displays it, for example:">wxHtmlWindow::SetPage</a>. LoadPage loads and displays HTML file while SetPage displays directly the passed <b>string</b>. See the example:</p>
<div class="fragment"><div class="line">mywin->LoadPage(<span class="stringliteral">"test.htm"</span>);</div>
<div class="line">mywin->SetPage(<span class="stringliteral">"htmlbody"</span></div>
<div class="line"> <span class="stringliteral">"h1Error/h1"</span></div>
<div class="line"> <span class="stringliteral">"Some error occurred :-H)"</span></div>
<div class="line"> <span class="stringliteral">"/body/hmtl"</span>);</div>
</div><!-- fragment --><h2><a class="anchor" id="overview_html_quickstart_settingup"></a>
Setting up wxHtmlWindow</h2>
<p>Because <a class="el" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a> is derived from <a class="el" href="group__group__class__miscwnd.html#ga695bec5996cd4d5512d1a01cfdcf96a5" title="Scrolled window derived from wxPanel.">wxScrolledWindow</a> and not from <a class="el" href="classwx_frame.html" title="A frame is a window whose size and position can (usually) be changed by the user.">wxFrame</a>, it doesn't have visible frame. But the user usually wants to see the title of HTML page displayed somewhere and the frame's titlebar is the ideal place for it.</p>
<p><a class="el" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a> provides 2 methods in order to handle this: <a class="el" href="classwx_html_window.html#ab524aecb99227497a569981a2f11f67f" title="Sets the frame in which page title will be displayed.">wxHtmlWindow::SetRelatedFrame</a> and <a class="el" href="classwx_html_window.html#a81b658e84cbaf395eddd2d9c40b00c70" title="After calling SetRelatedFrame(), this sets statusbar slot where messages will be displayed.">wxHtmlWindow::SetRelatedStatusBar</a>. See the example:</p>
<div class="fragment"><div class="line">html = <span class="keyword">new</span> <a class="code" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a>(<span class="keyword">this</span>);</div>
<div class="line">html->SetRelatedFrame(<span class="keyword">this</span>, <span class="stringliteral">"HTML : %%s"</span>);</div>
<div class="line">html->SetRelatedStatusBar(0);</div>
</div><!-- fragment --><p>The first command associates the HTML object with its parent frame (this points to <a class="el" href="classwx_frame.html" title="A frame is a window whose size and position can (usually) be changed by the user.">wxFrame</a> object there) and sets the format of the title. Page title "Hello, world!" will be displayed as "HTML : Hello, world!" in this example.</p>
<p>The second command sets which frame's status bar should be used to display browser's messages (such as "Loading..." or "Done" or hypertext links).</p>
<h2><a class="anchor" id="overview_html_quickstart_custom"></a>
Customizing wxHtmlWindow</h2>
<p>You can customize <a class="el" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a> by setting font size, font face and borders (space between border of window and displayed HTML). Related functions:</p>
<ul>
<li><a class="el" href="classwx_html_window.html#a31b77979403242da3ccd40bea9b29b87" title="This function sets font sizes and faces.">wxHtmlWindow::SetFonts</a> </li>
<li><a class="el" href="classwx_html_window.html#a3e2350cbf8bc74ba8451ab3f953046dc" title="This function sets the space between border of window and HTML contents.">wxHtmlWindow::SetBorders</a> </li>
<li><a class="el" href="classwx_html_window.html#a22f8b0b78251259c01ce5e8f17294fd4" title="This reads custom settings from wxConfig.">wxHtmlWindow::ReadCustomization</a> </li>
<li><a class="el" href="classwx_html_window.html#a46bb9859128a69e2d943a248c7bd41bd" title="Saves custom settings into wxConfig.">wxHtmlWindow::WriteCustomization</a></li>
</ul>
<p>The last two functions are used to store user customization info wxConfig stuff (for example in the registry under Windows, or in a dotfile under Unix).</p>
<h1><a class="anchor" id="overview_html_printing"></a>
HTML Printing</h1>
<p>The wxHTML library provides printing facilities with several levels of complexity. The easiest way to print an HTML document is to use the <a class="el" href="classwx_html_easy_printing.html" title="This class provides very simple interface to printing architecture.">wxHtmlEasyPrinting</a> class.</p>
<p>It lets you print HTML documents with only one command and you don't have to worry about deriving from the <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> class at all. It is only a simple wrapper around the <a class="el" href="classwx_html_printout.html" title="This class serves as printout class for HTML documents.">wxHtmlPrintout</a>, normal wxWidgets printout class.</p>
<p>And finally there is the low level class <a class="el" href="classwx_html_d_c_renderer.html" title="This class can render HTML document into a specified area of a DC.">wxHtmlDCRenderer</a> which you can use to render HTML into a rectangular area on any DC. It supports rendering into multiple rectangles with the same width. The most common use of this is placing one rectangle on each page or printing into two columns.</p>
<h1><a class="anchor" id="overview_html_helpformats"></a>
Help Files Format</h1>
<p>wxHTML library can be used to show an help manual to the user; in fact, it supports natively (through <a class="el" href="classwx_html_help_controller.html" title="This help controller provides an easy way of displaying HTML help in your application (see HTML Sampl...">wxHtmlHelpController</a>) a reduced version of MS HTML Workshop format.</p>
<p>A <b>book</b> consists of three files: the header file, the contents file and the index file.</p>
<p>You can make a regular zip archive of these files, plus the HTML and any image files, for wxHTML (or helpview) to read; and the <code>".zip"</code> file can optionally be renamed to <code>".htb"</code>.</p>
<h2><a class="anchor" id="overview_html_helpformats_hhp"></a>
Header file (.hhp)</h2>
<p>The header file must contain these lines (and may contain additional lines which are ignored):</p>
<div class="fragment"><div class="line">Contents file=filename.hhc</div>
<div class="line">Index file=filename.hhk</div>
<div class="line">Title=title of your book</div>
<div class="line">Default topic=<span class="keywordflow">default</span> page to be displayed.htm</div>
</div><!-- fragment --><p>All filenames (including the Default topic) are relative to the location of the <code>".hhp"</code> file.</p>
<dl class="section note"><dt>Note</dt><dd>For localization, in addition the <code>".hhp"</code> file may contain the line <div class="fragment"><div class="line">Charset=rfc_charset</div>
</div><!-- fragment --> which specifies what charset (e.g. "iso8859_1") was used in contents and index files. Please note that this line is incompatible with MS HTML Help Workshop and it would either silently remove it or complain with some error. See also <a class="el" href="overview_nonenglish.html">Writing Non-English Applications</a>.</dd></dl>
<h2><a class="anchor" id="overview_html_helpformats_hhc"></a>
Contents file (.hhc)</h2>
<p>Contents file has HTML syntax and it can be parsed by regular HTML parser. It contains exactly one list (<code><ul></code>....<code></ul></code> statement):</p>
<div class="fragment"><div class="line"><ul></div>
<div class="line"> <li><<span class="keywordtype">object</span> type=<span class="stringliteral">"text/sitemap"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"Name"</span> value=<span class="stringliteral">"@topic name@"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"ID"</span> value=@numeric_id@></div>
<div class="line"> <param name=<span class="stringliteral">"Local"</span> value=<span class="stringliteral">"@filename.htm@"</span>></div>
<div class="line"> </<span class="keywordtype">object</span>></div>
<div class="line"> <li><<span class="keywordtype">object</span> type=<span class="stringliteral">"text/sitemap"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"Name"</span> value=<span class="stringliteral">"@topic name@"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"ID"</span> value=@numeric_id@></div>
<div class="line"> <param name=<span class="stringliteral">"Local"</span> value=<span class="stringliteral">"@filename.htm@"</span>></div>
<div class="line"> </<span class="keywordtype">object</span>></div>
<div class="line"> ...</div>
<div class="line"></ul></div>
</div><!-- fragment --><p>You can modify value attributes of param tags. The <em>topic name</em> is name of chapter/topic as is displayed in contents, <em>filename.htm</em> is the HTML page name (relative to the <code>".hhp"</code> file) and <em>numeric_id</em> is optional, it is used only when you use <a class="el" href="classwx_html_help_controller.html#a13918b23f9de9c34b161272af8c5bee7" title="This is an overloaded member function, provided for convenience. It differs from the above function o...">wxHtmlHelpController::Display(int)</a>.</p>
<p>Items in the list may be nested - one <code><li></code> statement may contain a <code><ul></code> sub-statement:</p>
<div class="fragment"><div class="line"><ul></div>
<div class="line"> <li><<span class="keywordtype">object</span> type=<span class="stringliteral">"text/sitemap"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"Name"</span> value=<span class="stringliteral">"Top node"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"Local"</span> value=<span class="stringliteral">"top.htm"</span>></div>
<div class="line"> </<span class="keywordtype">object</span>></div>
<div class="line"> <ul></div>
<div class="line"> <li><<span class="keywordtype">object</span> type=<span class="stringliteral">"text/sitemap"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"Name"</span> value=<span class="stringliteral">"subnode in topnode"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"Local"</span> value=<span class="stringliteral">"subnode1.htm"</span>></div>
<div class="line"> </<span class="keywordtype">object</span>></div>
<div class="line"> ...</div>
<div class="line"> </ul></div>
<div class="line"> <li><<span class="keywordtype">object</span> type=<span class="stringliteral">"text/sitemap"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"Name"</span> value=<span class="stringliteral">"Another Top"</span>></div>
<div class="line"> <param name=<span class="stringliteral">"Local"</span> value=<span class="stringliteral">"top2.htm"</span>></div>
<div class="line"> </<span class="keywordtype">object</span>></div>
<div class="line"> ...</div>
<div class="line"></ul></div>
</div><!-- fragment --><h2><a class="anchor" id="overview_html_helpformats_hhk"></a>
Index Files (.hhk)</h2>
<p>Index files have same format as contents files except that ID params are ignored and sublists are <b>not</b> allowed.</p>
<h1><a class="anchor" id="overview_html_filters"></a>
Input Filters</h1>
<p>The wxHTML library provides a mechanism for reading and displaying files of many different file formats.</p>
<p><a class="el" href="classwx_html_window.html#ab7086e665bb533a34dc11ab29465db09" title="Unlike SetPage() this function first loads the HTML page from location and then displays it...">wxHtmlWindow::LoadPage</a> can load not only HTML files but any known file. To make a file type known to <a class="el" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a> you must create a <a class="el" href="classwx_html_filter.html" title="This class is the parent class of input filters for wxHtmlWindow.">wxHtmlFilter</a> filter and register it using <a class="el" href="classwx_html_window.html#a7d4293c4d2f03fd8d6252c62573b0529" title="Adds input filter to the static list of available filters.">wxHtmlWindow::AddFilter</a>.</p>
<h1><a class="anchor" id="overview_html_cells"></a>
Cells and Containers</h1>
<p>This article describes mechanism used by <a class="el" href="classwx_html_win_parser.html" title="This class is derived from wxHtmlParser and its main goal is to parse HTML input so that it can be di...">wxHtmlWinParser</a> and <a class="el" href="classwx_html_window.html" title="wxHtmlWindow is probably the only class you will directly use unless you want to do something special...">wxHtmlWindow</a> to parse and display HTML documents.</p>
<h2><a class="anchor" id="overview_html_cells_cells"></a>
Cells</h2>
<p>You can divide any text (or HTML) into small fragments. Let's call these fragments <b>cells</b>. Cell is for example one word, horizontal line, image or any other part of document. Each cell has width and height (except special "magic" cells with zero dimensions - e.g. colour changers or font changers). See <a class="el" href="classwx_html_cell.html" title="Internal data structure.">wxHtmlCell</a>.</p>
<h2><a class="anchor" id="overview_html_cells_containers"></a>
Containers</h2>
<p>Container is kind of cell that may contain sub-cells. Its size depends on number and sizes of its sub-cells (and also depends on width of window). See <a class="el" href="classwx_html_container_cell.html" title="The wxHtmlContainerCell class is an implementation of a cell that may contain more cells in it...">wxHtmlContainerCell</a>, <a class="el" href="classwx_html_cell.html#ada68b93b129fafc7b251580408b67fd6" title="Layouts the cell.">wxHtmlCell::Layout</a>. This image shows the cells and containers:</p>
<div class="image">
<img src="overview_html_contbox.png" alt="overview_html_contbox.png"/>
</div>
<h2><a class="anchor" id="overview_html_cells_conttaghandler"></a>
Using Containers in Tag Handler</h2>
<p><a class="el" href="classwx_html_win_parser.html" title="This class is derived from wxHtmlParser and its main goal is to parse HTML input so that it can be di...">wxHtmlWinParser</a> provides a user-friendly way of managing containers. It is based on the idea of opening and closing containers.</p>
<p>Use <a class="el" href="classwx_html_win_parser.html#a893a9b0a622a76275a8fdd8227bfa7de" title="Opens new container and returns pointer to it (see Cells and Containers).">wxHtmlWinParser::OpenContainer</a> to open new a container <em>within</em> an already opened container. This new container is a <em>sub-container</em> of the old one. (If you want to create a new container with the same depth level you can call <code>CloseContainer()</code>; OpenContainer();.)</p>
<p>Use <a class="el" href="classwx_html_win_parser.html#aad9104fa431ab3573fd55cf8ddef4f60" title="Closes the container, sets actual container to the parent one and returns pointer to it (see Cells an...">wxHtmlWinParser::CloseContainer</a> to close the container. This doesn't create a new container with same depth level but it returns "control" to the parent container. See explanation:</p>
<div class="image">
<img src="overview_html_cont.png" alt="overview_html_cont.png"/>
</div>
<p>There clearly must be same number of calls to OpenContainer as to CloseContainer.</p>
<p>This code creates a new paragraph (container at same depth level) with "Hello, world!":</p>
<div class="fragment"><div class="line">m_WParser->CloseContainer();</div>
<div class="line">c = m_WParser->OpenContainer();</div>
<div class="line"></div>
<div class="line">m_WParser->AddText(<span class="stringliteral">"Hello, "</span>);</div>
<div class="line">m_WParser->AddText(<span class="stringliteral">"world!"</span>);</div>
<div class="line"></div>
<div class="line">m_WParser->CloseContainer();</div>
<div class="line">m_WParser->OpenContainer();</div>
</div><!-- fragment --><p>and here is image of the situation:</p>
<div class="image">
<img src="overview_html_hello.png" alt="overview_html_hello.png"/>
</div>
<p>You can see that there was an opened container before the code was executed. We closed it, created our own container, then closed our container and opened new container.</p>
<p>The result was that we had <em>same</em> depth level after executing. This is general rule that should be followed by tag handlers: leave depth level of containers unmodified (in other words, number of OpenContainer and CloseContainer calls should be same within <a class="el" href="classwx_html_tag_handler.html#a9b619fe66c49e8756f8ff5db04c5e69e" title="This is the core method of each handler.">wxHtmlTagHandler::HandleTag</a>'s body).</p>
<p>Notice that it would be usually better to use <a class="el" href="classwx_html_container_cell.html#a84c159f60c4bd8f82622647428720667" title="Inserts a new cell into the container.">wxHtmlContainerCell::InsertCell</a> instead of adding text to the parser directly.</p>
<h1><a class="anchor" id="overview_html_handlers"></a>
Tag Handlers</h1>
<p>The wxHTML library provides architecture of pluggable <em>tag</em> handlers. Tag handler is class that understands particular HTML tag (or tags) and is able to interpret it.</p>
<p><a class="el" href="classwx_html_win_parser.html" title="This class is derived from wxHtmlParser and its main goal is to parse HTML input so that it can be di...">wxHtmlWinParser</a> has a static table of <b>modules</b>. Each module contains one or more tag handlers. Each time a new <a class="el" href="classwx_html_win_parser.html" title="This class is derived from wxHtmlParser and its main goal is to parse HTML input so that it can be di...">wxHtmlWinParser</a> object is constructed all modules are scanned and handlers are added to <a class="el" href="classwx_html_parser.html" title="Classes derived from this handle the generic parsing of HTML documents: it scans the document and div...">wxHtmlParser</a>'s list of available handlers (note: <a class="el" href="classwx_html_parser.html" title="Classes derived from this handle the generic parsing of HTML documents: it scans the document and div...">wxHtmlParser</a>'s list is non-static).</p>
<h2><a class="anchor" id="overview_html_handlers_howworks"></a>
How it works</h2>
<p>Common tag handler's <a class="el" href="classwx_html_tag_handler.html#a9b619fe66c49e8756f8ff5db04c5e69e" title="This is the core method of each handler.">wxHtmlTagHandler::HandleTag</a> method works in four steps:</p>
<ul>
<li>Save state of parent parser into local variables </li>
<li>Change parser state according to tag's params </li>
<li>Parse text between the tag and paired ending tag (if present) </li>
<li>Restore original parser state</li>
</ul>
<p>See <a class="el" href="classwx_html_win_parser.html" title="This class is derived from wxHtmlParser and its main goal is to parse HTML input so that it can be di...">wxHtmlWinParser</a> for methods for modifying parser's state. In general you can do things like opening/closing containers, changing colors, fonts etc.</p>
<h2><a class="anchor" id="overview_html_handlers_custom"></a>
Providing own tag handlers</h2>
<p>You should create a new .cpp file and place the following lines into it:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <mod_templ.h></span></div>
<div class="line"><span class="preprocessor">#include <forcelink.h></span></div>
<div class="line">FORCE_LINK_ME(yourmodulefilenamewithoutcpp)</div>
</div><!-- fragment --><p>Then you must define handlers and one module.</p>
<h2><a class="anchor" id="overview_html_handlers_tag"></a>
Tag handlers</h2>
<p>The handler is derived from <a class="el" href="classwx_html_win_tag_handler.html" title="This is basically wxHtmlTagHandler except that it is extended with protected member m_WParser pointin...">wxHtmlWinTagHandler</a> (or directly from <a class="el" href="classwx_html_tag_handler.html">wxHtmlTagHandler</a>).</p>
<p>You can use set of macros to define the handler (see src/html/m_*.cpp files for details). Handler definition must start with <b>TAG_HANDLER_BEGIN</b> macro and end with <b>TAG_HANDLER_END</b> macro.</p>
<p>I strongly recommend to have a look at <em>include/wxhtml/mod_templ.h</em> file. Otherwise you won't understand the structure of macros.</p>
<p>See macros reference: </p>
<ul>
<li><b>TAG_HANDLER_BEGIN</b>(<em>name</em>, <em>tags</em>): Starts handler definition. <em>name</em> is handler identifier (in fact part of class name), <em>tags</em> is string containing list of tags supported by this handler (in uppercase). This macro derives new class from <a class="el" href="classwx_html_win_tag_handler.html" title="This is basically wxHtmlTagHandler except that it is extended with protected member m_WParser pointin...">wxHtmlWinTagHandler</a> and implements it is <a class="el" href="classwx_html_tag_handler.html#a4659531bcbb3cbcafea31d31a227f747" title="Returns list of supported tags.">wxHtmlTagHandler::GetSupportedTags</a> method. Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")</li>
</ul>
<ul>
<li><b>TAG_HANDLER_VARS:</b> This macro starts block of variables definitions. (Variables are identical to class attributes.) Example:</li>
</ul>
<div class="fragment"><div class="line">TAG_HANDLER_BEGIN(VARS_ONLY, <span class="stringliteral">"CRAZYTAG"</span>)</div>
<div class="line"> TAG_HANDLER_VARS</div>
<div class="line"> <span class="keywordtype">int</span> my_int_var;</div>
<div class="line"> <a class="code" href="classwx_string.html" title="String class for passing textual data to or receiving it from wxWidgets.">wxString</a> something_else;</div>
<div class="line">TAG_HANDLER_END(VARS_ONLY)</div>
</div><!-- fragment --><p>This macro is used only in rare cases.</p>
<ul>
<li><b>TAG_HANDLER_CONSTR</b>(<em>name</em>): This macro supplies object constructor. <em>name</em> is same name as the one from TAG_HANDLER_BEGIN macro. Body of constructor follow after this macro (you must use { and } ). Example:</li>
</ul>
<div class="fragment"><div class="line">TAG_HANDLER_BEGIN(VARS2, <span class="stringliteral">"CRAZYTAG"</span>)</div>
<div class="line"> TAG_HANDLER_VARS</div>
<div class="line"> <span class="keywordtype">int</span> my_int_var;</div>
<div class="line"> TAG_HANDLER_CONSTR(vars2)</div>
<div class="line"> { <span class="comment">// !!!!!!</span></div>
<div class="line"> my_int_var = 666;</div>
<div class="line"> } <span class="comment">// !!!!!!</span></div>
<div class="line">TAG_HANDLER_END(VARS2)</div>
</div><!-- fragment --><p>Never used in wxHTML :-)</p>
<ul>
<li><b>TAG_HANDLER_PROC</b>(<em>varib</em>): This is very important macro. It defines <a class="el" href="classwx_html_tag_handler.html#a9b619fe66c49e8756f8ff5db04c5e69e" title="This is the core method of each handler.">wxHtmlTagHandler::HandleTag</a> method. <em>varib</em> is name of parameter passed to the method, usually <em>tag</em>. Body of method follows after this macro. Note than you must use { and } ! Example:</li>
</ul>
<div class="fragment"><div class="line">TAG_HANDLER_BEGIN(TITLE, <span class="stringliteral">"TITLE"</span>)</div>
<div class="line"> TAG_HANDLER_PROC(tag)</div>
<div class="line"> {</div>
<div class="line"> printf(<span class="stringliteral">"TITLE found...\n"</span>);</div>
<div class="line"> }</div>
<div class="line">TAG_HANDLER_END(TITLE)</div>
</div><!-- fragment --><ul>
<li><b>TAG_HANDLER_END</b>(<em>name</em>): Ends definition of tag handler <em>name</em>.</li>
</ul>
<h2><a class="anchor" id="overview_html_handlers_modules"></a>
Tags Modules</h2>
<p>You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and TAGS_MODULE_END to inherit new module from <a class="el" href="classwx_html_tags_module.html" title="This class provides easy way of filling wxHtmlWinParser's table of tag handlers.">wxHtmlTagsModule</a> and to create instance of it.</p>
<p>See macros reference:</p>
<ul>
<li><b>TAGS_MODULE_BEGIN</b>(<em>modname</em>): Begins module definition. <em>modname</em> is part of class name and must be unique. </li>
<li><b>TAGS_MODULE_ADD</b>(<em>name</em>): Adds the handler to this module. <em>name</em> is the identifier from TAG_HANDLER_BEGIN. </li>
<li><b>TAGS_MODULE_END</b>(<em>modname</em>): Ends the definition of module. Example:</li>
</ul>
<div class="fragment"><div class="line">TAGS_MODULE_BEGIN(Examples)</div>
<div class="line"> TAGS_MODULE_ADD(VARS_ONLY)</div>
<div class="line"> TAGS_MODULE_ADD(VARS2)</div>
<div class="line"> TAGS_MODULE_ADD(TITLE)</div>
<div class="line">TAGS_MODULE_END(Examples)</div>
</div><!-- fragment --><h1><a class="anchor" id="overview_html_supptags"></a>
Supported HTML Tags</h1>
<p>wxHTML is not full implementation of HTML standard. Instead, it supports most common tags so that it is possible to display <em>simple</em> HTML documents with it. (For example it works fine with pages created in Netscape Composer or generated by tex2rtf).</p>
<p>Following tables list all tags known to wxHTML, together with supported parameters.</p>
<p>A tag has general form of <code>tagname</code> param_1 param_2 ... param_n where param_i is either <code>paramname="paramvalue"</code> or <code>paramname=paramvalue</code> - these two are equivalent. Unless stated otherwise, wxHTML is case-insensitive.</p>
<h2><a class="anchor" id="overview_html_supptags_commonvalues"></a>
Common Parameter Values</h2>
<p>We will use these substitutions in tags descriptions:</p>
<div class="fragment"><div class="line">[alignment] CENTER</div>
<div class="line"> LEFT</div>
<div class="line"> RIGHT</div>
<div class="line"> JUSTIFY</div>
<div class="line"></div>
<div class="line">[v_alignment] TOP</div>
<div class="line"> BOTTOM</div>
<div class="line"> CENTER</div>
<div class="line"></div>
<div class="line">[color] HTML 4.0-compliant colour specification</div>
<div class="line"></div>
<div class="line">[fontsize] -2</div>
<div class="line"> -1</div>
<div class="line"> +0</div>
<div class="line"> +1</div>
<div class="line"> +2</div>
<div class="line"> +3</div>
<div class="line"> +4</div>
<div class="line"> 1</div>
<div class="line"> 2</div>
<div class="line"> 3</div>
<div class="line"> 4</div>
<div class="line"> 5</div>
<div class="line"> 6</div>
<div class="line"> 7</div>
<div class="line"></div>
<div class="line">[pixels] integer value that represents dimension in pixels</div>
<div class="line"></div>
<div class="line">[percent] i%</div>
<div class="line"> where i is integer</div>
<div class="line"></div>
<div class="line">[url] an URL</div>
<div class="line"></div>
<div class="line">[string] text <span class="keywordtype">string</span></div>
<div class="line"></div>
<div class="line">[coords] c(1),c(2),c(3),...,c(n)</div>
<div class="line"> where c(i) is integer</div>
</div><!-- fragment --><h2><a class="anchor" id="overview_html_supptags_list"></a>
List of Supported Tags</h2>
<div class="fragment"><div class="line">A NAME=[string]</div>
<div class="line"> HREF=[url]</div>
<div class="line"> TARGET=[target window spec]</div>
<div class="line">ADDRESS</div>
<div class="line">AREA SHAPE=POLY</div>
<div class="line"> SHAPE=CIRCLE</div>
<div class="line"> SHAPE=RECT</div>
<div class="line"> COORDS=[coords]</div>
<div class="line"> HREF=[url]</div>
<div class="line">B</div>
<div class="line">BIG</div>
<div class="line">BLOCKQUOTE</div>
<div class="line">BODY TEXT=[color]</div>
<div class="line"> LINK=[color]</div>
<div class="line"> BGCOLOR=[color]</div>
<div class="line">BR ALIGN=[alignment]</div>
<div class="line">CENTER</div>
<div class="line">CITE</div>
<div class="line">CODE</div>
<div class="line">DD</div>
<div class="line">DIV ALIGN=[alignment]</div>
<div class="line">DL</div>
<div class="line">DT</div>
<div class="line">EM</div>
<div class="line">FONT COLOR=[color]</div>
<div class="line"> SIZE=[fontsize]</div>
<div class="line"> FACE=[comma-separated list of facenames]</div>
<div class="line">HR ALIGN=[alignment]</div>
<div class="line"> SIZE=[pixels]</div>
<div class="line"> WIDTH=[percent|pixels]</div>
<div class="line"> NOSHADE</div>
<div class="line">H1</div>
<div class="line">H2</div>
<div class="line">H3</div>
<div class="line">H4</div>
<div class="line">H5</div>
<div class="line">H6</div>
<div class="line">I</div>
<div class="line">IMG SRC=[url]</div>
<div class="line"> WIDTH=[percent|pixels]</div>
<div class="line"> HEIGHT=[pixels]</div>
<div class="line"> ALIGN=TEXTTOP</div>
<div class="line"> ALIGN=CENTER</div>
<div class="line"> ALIGN=ABSCENTER</div>
<div class="line"> ALIGN=BOTTOM</div>
<div class="line"> USEMAP=[url]</div>
<div class="line">KBD</div>
<div class="line">LI</div>
<div class="line">MAP NAME=[string]</div>
<div class="line">META HTTP-EQUIV=<span class="stringliteral">"Content-Type"</span></div>
<div class="line"> CONTENT=[string]</div>
<div class="line">OL</div>
<div class="line">P ALIGN=[alignment]</div>
<div class="line">PRE</div>
<div class="line">SAMP</div>
<div class="line">SMALL</div>
<div class="line">SPAN</div>
<div class="line">STRIKE</div>
<div class="line">STRONG</div>
<div class="line">SUB</div>
<div class="line">SUP</div>
<div class="line">TABLE ALIGN=[alignment]</div>
<div class="line"> WIDTH=[percent|pixels]</div>
<div class="line"> BORDER=[pixels]</div>
<div class="line"> VALIGN=[v_alignment]</div>
<div class="line"> BGCOLOR=[color]</div>
<div class="line"> CELLSPACING=[pixels]</div>
<div class="line"> CELLPADDING=[pixels]</div>
<div class="line">TD ALIGN=[alignment]</div>
<div class="line"> VALIGN=[v_alignment]</div>
<div class="line"> BGCOLOR=[color]</div>
<div class="line"> WIDTH=[percent|pixels]</div>
<div class="line"> COLSPAN=[pixels]</div>
<div class="line"> ROWSPAN=[pixels]</div>
<div class="line"> NOWRAP</div>
<div class="line">TH ALIGN=[alignment]</div>
<div class="line"> VALIGN=[v_alignment]</div>
<div class="line"> BGCOLOR=[color]</div>
<div class="line"> WIDTH=[percent|pixels]</div>
<div class="line"> COLSPAN=[pixels]</div>
<div class="line"> ROWSPAN=[pixels]</div>
<div class="line">TITLE</div>
<div class="line">TR ALIGN=[alignment]</div>
<div class="line"> VALIGN=[v_alignment]</div>
<div class="line"> BGCOLOR=[color]</div>
<div class="line">TT</div>
<div class="line">U</div>
<div class="line">UL</div>
</div><!-- fragment --><h2><a class="anchor" id="overview_html_suppstyles_list"></a>
Supported Styles</h2>
<p>wxHTML doesn't really have CSS support but it does support a few simple styles: you can use <code>"text-align"</code>, <code>"width"</code>, <code>"vertical-align"</code> and <code>"background"</code> with all elements and for <code>SPAN</code> elements a few other styles are additionally recognized:</p>
<ul>
<li><code>color</code> </li>
<li><code>font-family</code> </li>
<li><code>font-size</code> (only in point units)</li>
<li><code>font-style</code> (only "oblique", "italic" and "normal" values are supported)</li>
<li><code>font-weight</code> (only "bold" and "normal" values are supported)</li>
<li><code>text-decoration</code> (only "underline" value is supported) </li>
</ul>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
