docs/doxygen/overviews/html.h

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