docs/doxygen/overviews/html.h

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