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 licence
   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 SPAN
 547 STRIKE
 548 STRONG
 549 SUB
 550 SUP
 551 TABLE           ALIGN=[alignment]
 552                 WIDTH=[percent|pixels]
 553                 BORDER=[pixels]
 554                 VALIGN=[v_alignment]
 555                 BGCOLOR=[color]
 556                 CELLSPACING=[pixels]
 557                 CELLPADDING=[pixels]
 558 TD              ALIGN=[alignment]
 559                 VALIGN=[v_alignment]
 560                 BGCOLOR=[color]
 561                 WIDTH=[percent|pixels]
 562                 COLSPAN=[pixels]
 563                 ROWSPAN=[pixels]
 564                 NOWRAP
 565 TH              ALIGN=[alignment]
 566                 VALIGN=[v_alignment]
 567                 BGCOLOR=[color]
 568                 WIDTH=[percent|pixels]
 569                 COLSPAN=[pixels]
 570                 ROWSPAN=[pixels]
 571 TITLE
 572 TR              ALIGN=[alignment]
 573                 VALIGN=[v_alignment]
 574                 BGCOLOR=[color]
 575 TT
 576 U
 577 UL
 578 @endcode
 579
 580 @subsection overview_html_suppstyles_list List of supported styles
 581
 582 wxHTML doesn't really have CSS support but it does support a few simple styles:
 583 you can use @c "text-align", @c "width", @c "vertical-align" and @c
 584 "background" with all elements and for @c SPAN elements a few other styles are
 585 additionally recognized:
 586     - @c color
 587     - @c font-family
 588     - @c font-size (only in point units)
 589     - @c font-style (only "oblique", "italic" and "normal" values are supported)
 590     - @c font-weight (only "bold" and "normal" values are supported)
 591     - @c text-decoration (only "underline" value is supported)
 592
 593 */
 594