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 @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 &lt;ul&gt;....@c &lt;/ul&gt; 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 &lt;li&gt; statement may contain a
 176 @c &lt;ul&gt; 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 */