]> git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/html.h
Added parenthesis around macro arguments
[wxWidgets.git] / docs / doxygen / overviews / html.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: html.h
3 // Purpose: topic overview
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10
11 @page overview_html wxHTML Overview
12
13 The wxHTML library provides classes for parsing and displaying HTML.
14 It is not intended to be a high-end HTML browser. If you are looking for
15 something like that try <http://www.mozilla.org/>.
16
17 wxHTML can be used as a generic rich text viewer - for example to display
18 a nice About Box (like those of GNOME apps) or to display the result of
19 database searching. There is a wxFileSystem class which allows you to use
20 your own virtual file systems.
21
22 wxHtmlWindow supports tag handlers. This means that you can easily
23 extend wxHtml library with new, unsupported tags. Not only that,
24 you can even use your own application-specific tags!
25
26 See @c src/html/m_*.cpp files for details.
27
28 There is a generic wxHtmlParser class, independent of wxHtmlWindow.
29
30 @li @ref overview_html_quickstart
31 @li @ref overview_html_printing
32 @li @ref overview_html_helpformats
33 @li @ref overview_html_filters
34 @li @ref overview_html_cells
35 @li @ref overview_html_handlers
36 @li @ref overview_html_supptags
37
38
39 <hr>
40
41
42 @section overview_html_quickstart wxHTML quick start
43
44 @subsection overview_html_quickstart_disphtml Displaying HTML
45
46 First of all, you must include @c wx/wxhtml.h.
47
48 Class wxHtmlWindow (derived from ::wxScrolledWindow) is used to display HTML documents.
49
50 It has two important methods: wxHtmlWindow::LoadPage and wxHtmlWindow::SetPage.
51 LoadPage loads and displays HTML file while SetPage displays directly the
52 passed @b string. See the example:
53
54 @code
55 mywin -> LoadPage("test.htm");
56 mywin -> SetPage("htmlbody"
57 "h1Error/h1"
58 "Some error occurred :-H)"
59 "/body/hmtl");
60 @endcode
61
62 @subsection overview_html_quickstart_settingup Setting up wxHtmlWindow
63
64 Because wxHtmlWindow is derived from ::wxScrolledWindow and not from
65 wxFrame, it doesn't have visible frame. But the user usually wants to see
66 the title of HTML page displayed somewhere and the frame's titlebar is
67 the ideal place for it.
68
69 wxHtmlWindow provides 2 methods in order to handle this:
70 wxHtmlWindow::SetRelatedFrame and wxHtmlWindow::SetRelatedStatusBar.
71 See the example:
72
73 @code
74 html = new wxHtmlWindow(this);
75 html -> SetRelatedFrame(this, "HTML : %%s");
76 html -> SetRelatedStatusBar(0);
77 @endcode
78
79 The first command associates the HTML object with its parent frame
80 (this points to wxFrame object there) and sets the format of the title.
81 Page title "Hello, world!" will be displayed as "HTML : Hello, world!"
82 in this example.
83
84 The second command sets which frame's status bar should be used to display
85 browser's messages (such as "Loading..." or "Done" or hypertext links).
86
87 @subsection overview_html_quickstart_custom Customizing wxHtmlWindow
88
89 You can customize wxHtmlWindow by setting font size, font face and
90 borders (space between border of window and displayed HTML). Related functions:
91
92 @li wxHtmlWindow::SetFonts
93 @li wxHtmlWindow::SetBorders
94 @li wxHtmlWindow::ReadCustomization
95 @li wxHtmlWindow::WriteCustomization
96
97 The last two functions are used to store user customization info wxConfig stuff
98 (for example in the registry under Windows, or in a dotfile under Unix).
99
100
101
102 @section overview_html_printing HTML Printing
103
104 The wxHTML library provides printing facilities with several levels of complexity.
105 The easiest way to print an HTML document is to use the wxHtmlEasyPrinting class.
106
107 It lets you print HTML documents with only one command and you don't have to worry
108 about deriving from the wxPrintout class at all. It is only a simple wrapper around the
109 wxHtmlPrintout, normal wxWidgets printout class.
110
111 And finally there is the low level class wxHtmlDCRenderer which you can use to
112 render HTML into a rectangular area on any DC.
113
114 It supports rendering into multiple rectangles with the same
115 width. (The most common use of this is placing one rectangle on each page or
116 printing into two columns.)
117
118
119 @section overview_html_helpformats Help Files Format
120
121 wxHTML library can be used to show an help manual to the user; in fact, it supports
122 natively (through wxHtmlHelpController) a reduced version of MS HTML Workshop format.
123
124 A @b book consists of three files: the header file, the contents file
125 and the index file.
126
127 You can make a regular zip archive of these files, plus the HTML and any
128 image files, for wxHTML (or helpview) to read; and the @c ".zip" file can
129 optionally be renamed to @c ".htb".
130
131 @subsection overview_html_helpformats_hhp Header file (.hhp)
132
133 The header file must contain these lines (and may contain additional lines
134 which are ignored):
135
136 @code
137 Contents file=filename.hhc
138 Index file=filename.hhk
139 Title=title of your book
140 Default topic=default page to be displayed.htm
141 @endcode
142
143 All filenames (including the Default topic) are relative to the
144 location of the @c ".hhp" file.
145
146 @note For localization, in addition the @c ".hhp" file may contain the line
147 @code
148 Charset=rfc_charset
149 @endcode
150 which specifies what charset (e.g. "iso8859_1") was used in contents
151 and index files. Please note that this line is incompatible with
152 MS HTML Help Workshop and it would either silently remove it or complain
153 with some error. See also @ref overview_nonenglish.
154
155 @subsection overview_html_helpformats_hhc Contents file (.hhc)
156
157 Contents file has HTML syntax and it can be parsed by regular HTML parser.
158 It contains exactly one list (@c &lt;ul&gt;....@c &lt;/ul&gt; statement):
159
160 @code
161 <ul>
162
163 <li><object type="text/sitemap">
164 <param name="Name" value="@topic name@">
165 <param name="ID" value=@numeric_id@>
166 <param name="Local" value="@filename.htm@">
167 </object>
168 <li><object type="text/sitemap">
169 <param name="Name" value="@topic name@">
170 <param name="ID" value=@numeric_id@>
171 <param name="Local" value="@filename.htm@">
172 </object>
173 ...
174 </ul>
175 @endcode
176
177 You can modify value attributes of param tags.
178 The <em>topic name</em> is name of chapter/topic as is displayed in
179 contents, <em>filename.htm</em> is the HTML page name (relative to the @c ".hhp" file)
180 and <em>numeric_id</em> is optional - it is used only when you use wxHtmlHelpController::Display(int).
181
182 Items in the list may be nested - one @c &lt;li&gt; statement may contain a @c &lt;ul&gt; sub-statement:
183
184 @code
185 <ul>
186
187 <li><object type="text/sitemap">
188 <param name="Name" value="Top node">
189 <param name="Local" value="top.htm">
190 </object>
191 <ul>
192 <li><object type="text/sitemap">
193 <param name="Name" value="subnode in topnode">
194 <param name="Local" value="subnode1.htm">
195 </object>
196 ...
197 </ul>
198
199 <li><object type="text/sitemap">
200 <param name="Name" value="Another Top">
201 <param name="Local" value="top2.htm">
202 </object>
203 ...
204
205 </ul>
206 @endcode
207
208 @subsection overview_html_helpformats_hhk Index file (.hhk)
209
210 Index files have same format as contents files except that ID params are ignored
211 and sublists are @b not allowed.
212
213
214 @section overview_html_filters Input Filters
215
216 The wxHTML library provides a mechanism for reading and displaying
217 files of many different file formats.
218
219 wxHtmlWindow::LoadPage can load not only HTML files but any known file.
220 To make a file type known to wxHtmlWindow you must create a wxHtmlFilter filter and
221 register it using wxHtmlWindow::AddFilter.
222
223
224 @section overview_html_cells Cells and Containers
225
226 This article describes mechanism used by wxHtmlWinParser and
227 wxHtmlWindow to parse and display HTML documents.
228
229 @subsection overview_html_cells_cells Cells
230
231 You can divide any text (or HTML) into small fragments. Let's call these
232 fragments @b cells. Cell is for example one word, horizontal line, image
233 or any other part of document. Each cell has width and height (except special
234 "magic" cells with zero dimensions - e.g. colour changers or font changers).
235 See wxHtmlCell.
236
237 @subsection overview_html_cells_containers Containers
238
239 Container is kind of cell that may contain sub-cells. Its size depends
240 on number and sizes of its sub-cells (and also depends on width of window).
241 See wxHtmlContainerCell, wxHtmlCell::Layout. This image shows the cells and
242 containers:
243
244 @image html overview_html_contbox.png
245
246 @subsection overview_html_cells_conttaghandler Using Containers in Tag Handler
247
248 wxHtmlWinParser provides a user-friendly way of managing containers.
249 It is based on the idea of opening and closing containers.
250
251 Use wxHtmlWinParser::OpenContainer to open new a container @e within an already
252 opened container.
253 This new container is a @e sub-container of the old one. (If you want to create a
254 new container with the same depth level you can call @c CloseContainer(); OpenContainer();.)
255
256 Use wxHtmlWinParser::CloseContainer to close the container.
257 This doesn't create a new container with same depth level but it returns "control"
258 to the parent container. See explanation:
259
260 @image html overview_html_cont.png
261
262 There clearly must be same number of calls to OpenContainer as to
263 CloseContainer.
264
265 @subsubsection overview_html_cells_conttaghandler_example Example
266
267 This code creates a new paragraph (container at same depth level)
268 with "Hello, world!":
269
270 @code
271 m_WParser -> CloseContainer();
272 c = m_WParser -> OpenContainer();
273
274 m_WParser -> AddText("Hello, ");
275 m_WParser -> AddText("world!");
276
277 m_WParser -> CloseContainer();
278 m_WParser -> OpenContainer();
279 @endcode
280
281 and here is image of the situation:
282
283 @image html overview_html_hello.png
284
285 You can see that there was an opened container before the code was executed.
286 We closed it, created our own container, then closed our container and opened
287 new container.
288
289 The result was that we had @e same depth level after executing.
290 This is general rule that should be followed by tag handlers:
291 leave depth level of containers unmodified (in other words, number of
292 OpenContainer and CloseContainer calls should be same within
293 wxHtmlTagHandler::HandleTag's body).
294
295 Notice that it would be usually better to use wxHtmlContainerCell::InsertCell instead
296 of adding text to the parser directly.
297
298
299 @section overview_html_handlers Tag Handlers
300
301 The wxHTML library provides architecture of pluggable @e tag handlers.
302 Tag handler is class that understands particular HTML tag (or tags) and is
303 able to interpret it.
304
305 wxHtmlWinParser has a static table of @b modules.
306 Each module contains one or more tag handlers. Each time a new wxHtmlWinParser
307 object is constructed all modules are scanned and handlers are added
308 to wxHtmlParser's list of available handlers (note: wxHtmlParser's list
309 is non-static).
310
311 @subsection overview_html_handlers_howworks How it works
312
313 Common tag handler's wxHtmlTagHandler::HandleTag method works in four steps:
314
315 @li Save state of parent parser into local variables
316 @li Change parser state according to tag's params
317 @li Parse text between the tag and paired ending tag (if present)
318 @li Restore original parser state
319
320 See wxHtmlWinParser for methods for modifying parser's state.
321 In general you can do things like opening/closing containers, changing colors, fonts etc.
322
323 @subsection overview_html_handlers_custom Providing own tag handlers
324
325 You should create a new .cpp file and place the following lines into it:
326
327 @code
328 #include <mod_templ.h>
329 #include <forcelink.h>
330 FORCE_LINK_ME(yourmodulefilenamewithoutcpp)
331 @endcode
332
333 Then you must define handlers and one module.
334
335 @subsection overview_html_handlers_tag Tag handlers
336
337 The handler is derived from wxHtmlWinTagHandler (or directly from wxHtmlTagHandler).
338
339 You can use set of macros to define the handler (see src/html/m_*.cpp files
340 for details). Handler definition must start with @b TAG_HANDLER_BEGIN macro
341 and end with @b TAG_HANDLER_END macro.
342
343 I strongly recommend to have a look at @e include/wxhtml/mod_templ.h file.
344 Otherwise you won't understand the structure of macros.
345
346 See macros reference:
347 @li @b TAG_HANDLER_BEGIN(@e name, @e tags):
348 Starts handler definition. @e name is handler identifier (in fact
349 part of class name), @e tags is string containing list of tags
350 supported by this handler (in uppercase). This macro derives new class from
351 wxHtmlWinTagHandler and implements it is wxHtmlTagHandler::GetSupportedTags method.
352 Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")
353
354 @li @b TAG_HANDLER_VARS:
355 This macro starts block of variables definitions. (Variables are identical
356 to class attributes.) Example:
357
358 @code
359 TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
360 TAG_HANDLER_VARS
361 int my_int_var;
362 wxString something_else;
363 TAG_HANDLER_END(VARS_ONLY)
364 @endcode
365
366 This macro is used only in rare cases.
367
368 @li @b TAG_HANDLER_CONSTR(@e name):
369 This macro supplies object constructor. @e name is same name as the one
370 from TAG_HANDLER_BEGIN macro. Body of constructor follow after
371 this macro (you must use { and } ). Example:
372
373 @code
374 TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG")
375 TAG_HANDLER_VARS
376 int my_int_var;
377 TAG_HANDLER_CONSTR(vars2)
378 { // !!!!!!
379 my_int_var = 666;
380 } // !!!!!!
381 TAG_HANDLER_END(VARS2)
382 @endcode
383
384 Never used in wxHTML :-)
385
386 @li @b TAG_HANDLER_PROC(@e varib):
387 This is very important macro. It defines wxHtmlTagHandler::HandleTag
388 method. @e varib is name of parameter passed to the method, usually
389 @e tag. Body of method follows after this macro.
390 Note than you must use { and } !
391 Example:
392
393 @code
394 TAG_HANDLER_BEGIN(TITLE, "TITLE")
395 TAG_HANDLER_PROC(tag)
396 {
397 printf("TITLE found...\n");
398 }
399 TAG_HANDLER_END(TITLE)
400 @endcode
401
402 @li @b TAG_HANDLER_END(@e name):
403 Ends definition of tag handler @e name.
404
405 @subsection overview_html_handlers_modules Tags Modules
406
407 You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and
408 TAGS_MODULE_END to inherit new module from
409 wxHtmlTagsModule and to create instance of it.
410
411 See macros reference:
412
413 @li @b TAGS_MODULE_BEGIN(@e modname):
414 Begins module definition. @e modname is part of class name and must be unique.
415 @li @b TAGS_MODULE_ADD(@e name):
416 Adds the handler to this module. @e name is the identifier from TAG_HANDLER_BEGIN.
417 @li @b TAGS_MODULE_END(@e modname):
418 Ends the definition of module.
419 Example:
420
421 @code
422 TAGS_MODULE_BEGIN(Examples)
423 TAGS_MODULE_ADD(VARS_ONLY)
424 TAGS_MODULE_ADD(VARS2)
425 TAGS_MODULE_ADD(TITLE)
426 TAGS_MODULE_END(Examples)
427 @endcode
428
429
430 @section overview_html_supptags Tags supported by wxHTML
431
432 wxHTML is not full implementation of HTML standard. Instead, it supports most
433 common tags so that it is possible to display @e simple HTML documents with it.
434 (For example it works fine with pages created in Netscape Composer or generated by tex2rtf).
435
436 Following tables list all tags known to wxHTML, together with supported parameters.
437
438 A tag has general form of @c tagname param_1 param_2 ... param_n where param_i is
439 either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent.
440 Unless stated otherwise, wxHTML is case-insensitive.
441
442 @subsection overview_html_supptags_commonvalues Table of common parameter values
443
444 We will use these substitutions in tags descriptions:
445
446 @code
447 [alignment] CENTER
448 LEFT
449 RIGHT
450 JUSTIFY
451
452 [v_alignment] TOP
453 BOTTOM
454 CENTER
455
456 [color] HTML 4.0-compliant colour specification
457
458 [fontsize] -2
459 -1
460 +0
461 +1
462 +2
463 +3
464 +4
465 1
466 2
467 3
468 4
469 5
470 6
471 7
472
473 [pixels] integer value that represents dimension in pixels
474
475 [percent] i%
476 where i is integer
477
478 [url] an URL
479
480 [string] text string
481
482 [coords] c(1),c(2),c(3),...,c(n)
483 where c(i) is integer
484 @endcode
485
486
487 @subsection overview_html_supptags_list List of supported tags
488
489 @code
490 A NAME=[string]
491 HREF=[url]
492 TARGET=[target window spec]
493 ADDRESS
494 AREA SHAPE=POLY
495 SHAPE=CIRCLE
496 SHAPE=RECT
497 COORDS=[coords]
498 HREF=[url]
499 B
500 BIG
501 BLOCKQUOTE
502 BODY TEXT=[color]
503 LINK=[color]
504 BGCOLOR=[color]
505 BR ALIGN=[alignment]
506 CENTER
507 CITE
508 CODE
509 DD
510 DIV ALIGN=[alignment]
511 DL
512 DT
513 EM
514 FONT COLOR=[color]
515 SIZE=[fontsize]
516 FACE=[comma-separated list of facenames]
517 HR ALIGN=[alignment]
518 SIZE=[pixels]
519 WIDTH=[percent|pixels]
520 NOSHADE
521 H1
522 H2
523 H3
524 H4
525 H5
526 H6
527 I
528 IMG SRC=[url]
529 WIDTH=[percent|pixels]
530 HEIGHT=[pixels]
531 ALIGN=TEXTTOP
532 ALIGN=CENTER
533 ALIGN=ABSCENTER
534 ALIGN=BOTTOM
535 USEMAP=[url]
536 KBD
537 LI
538 MAP NAME=[string]
539 META HTTP-EQUIV="Content-Type"
540 CONTENT=[string]
541 OL
542 P ALIGN=[alignment]
543 PRE
544 SAMP
545 SMALL
546 STRIKE
547 STRONG
548 SUB
549 SUP
550 TABLE ALIGN=[alignment]
551 WIDTH=[percent|pixels]
552 BORDER=[pixels]
553 VALIGN=[v_alignment]
554 BGCOLOR=[color]
555 CELLSPACING=[pixels]
556 CELLPADDING=[pixels]
557 TD ALIGN=[alignment]
558 VALIGN=[v_alignment]
559 BGCOLOR=[color]
560 WIDTH=[percent|pixels]
561 COLSPAN=[pixels]
562 ROWSPAN=[pixels]
563 NOWRAP
564 TH ALIGN=[alignment]
565 VALIGN=[v_alignment]
566 BGCOLOR=[color]
567 WIDTH=[percent|pixels]
568 COLSPAN=[pixels]
569 ROWSPAN=[pixels]
570 TITLE
571 TR ALIGN=[alignment]
572 VALIGN=[v_alignment]
573 BGCOLOR=[color]
574 TT
575 U
576 UL
577 @endcode
578
579 */
580