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