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