## wxHTML overview

This topic was written by Vaclav Slavik, the author of the wxHTML library.

The wxHTML library provides classes for parsing and displaying HTML.

It is not intended to be a high-end HTML browser. If you are looking for something like that try http://www.mozilla.org.

wxHTML can be used as a generic rich text viewer - for example to display a nice About Box (like those of GNOME apps) or to display the result of database searching. There is a wxFileSystem class which allows you to use your own virtual file systems.

wxHtmlWindow supports tag handlers. This means that you can easily extend wxHtml library with new, unsupported tags. Not only that, you can even use your own application-specific tags! See `src/html/m_*.cpp` files for details.

There is a generic wxHtmlParser class, independent of wxHtmlWindow.

wxHTML quick start
HTML Printing
Help Files Format
Input Filters
Cells and Containers
Tag Handlers
Tags supported by wxHTML

### wxHTML quick start

Displaying HTML

First of all, you must include <wx/wxhtml.h>.

Class wxHtmlWindow (derived from wxScrolledWindow) is used to display HTML documents. It has two important methods: LoadPage and SetPage. LoadPage loads and displays HTML file while SetPage displays directly the passed string. See the example:

        mywin -> LoadPage("test.htm");
        mywin -> SetPage("<html><body>"
                         "<h1>Error</h1>"
    		     "Some error occurred :-H)"
    		     "</body></hmtl>");

I think the difference is quite clear.

Displaying Help

See wxHtmlHelpController.

Setting up wxHtmlWindow

Because wxHtmlWindow is derived from wxScrolledWindow and not from wxFrame, it doesn't have visible frame. But the user usually wants to see the title of HTML page displayed somewhere and the frame's titlebar is the ideal place for it.

wxHtmlWindow provides 2 methods in order to handle this: SetRelatedFrame and SetRelatedStatusBar. See the example:

        html = new wxHtmlWindow(this);
        html -> SetRelatedFrame(this, "HTML : %%s");
        html -> SetRelatedStatusBar(0);

The first command associates the HTML object with its parent frame (this points to wxFrame object there) and sets the format of the title. Page title "Hello, world!" will be displayed as "HTML : Hello, world!" in this example.

The second command sets which frame's status bar should be used to display browser's messages (such as "Loading..." or "Done" or hypertext links).

Customizing wxHtmlWindow

You can customize wxHtmlWindow by setting font size, font face and borders (space between border of window and displayed HTML). Related functions:

- SetFonts
- SetBorders
- ReadCustomization
- WriteCustomization

The last two functions are used to store user customization info wxConfig stuff (for example in the registry under Windows, or in a dotfile under Unix).

### HTML Printing

The wxHTML library provides printing facilities with several levels of complexity.

The easiest way to print an HTML document is to use wxHtmlEasyPrinting class. It lets you print HTML documents with only one command and you don't have to worry about deriving from the wxPrintout class at all. It is only a simple wrapper around the wxHtmlPrintout, normal wxWidgets printout class.

And finally there is the low level class wxHtmlDCRenderer which you can use to render HTML into a rectangular area on any DC. It supports rendering into multiple rectangles with the same width. (The most common use of this is placing one rectangle on each page or printing into two columns.)

### Help Files Format

wxHTML library uses a reduced version of MS HTML Workshop format. Tex2RTF can produce these files when generating HTML, if you set htmlWorkshopFiles to true in your tex2rtf.ini file.

(See wxHtmlHelpController for help controller description.)

A book consists of three files: header file, contents file and index file. You can make a regular zip archive of these files, plus the HTML and any image files, for wxHTML (or helpview) to read; and the .zip file can optionally be renamed to .htb.

Header file (.hhp)

Header file must contain these lines (and may contain additional lines which are ignored) :

    Contents file=<filename.hhc>
    Index file=<filename.hhk>
    Title=<title of your book>
    Default topic=<default page to be displayed.htm>

All filenames (including the Default topic) are relative to the location of .hhp file.

Localization note: In addition, .hhp file may contain line

    Charset=<rfc_charset>

which specifies what charset (e.g. "iso8859_1") was used in contents and index files. Please note that this line is incompatible with MS HTML Help Workshop and it would either silently remove it or complain with some error. See also Writing non-English applications.

Contents file (.hhc)

Contents file has HTML syntax and it can be parsed by regular HTML parser. It contains exactly one list (`<ul>`....`</ul>` statement):

    <ul>

      <li> <object type="text/sitemap">
               <param name="Name" value="@topic name@">
               <param name="ID" value=@numeric_id@>
               <param name="Local" value="@filename.htm@">
           </object>
      <li> <object type="text/sitemap">
               <param name="Name" value="@topic name@">
               <param name="ID" value=@numeric_id@>
               <param name="Local" value="@filename.htm@">
           </object>
      ...

    </ul>

You can modify value attributes of param tags. topic name is name of chapter/topic as is displayed in contents, filename.htm is HTML page name (relative to .hhp file) and numeric_id is optional - it is used only when you use wxHtmlHelpController::Display(int)

Items in the list may be nested - one `<li>` statement may contain a `<ul>` sub-statement:

    <ul>

      <li> <object type="text/sitemap">
               <param name="Name" value="Top node">
               <param name="Local" value="top.htm">
           </object>
           <ul>
             <li> <object type="text/sitemap">
                  <param name="Name" value="subnode in topnode">
                  <param name="Local" value="subnode1.htm">
                  </object>
          ...
           </ul>

      <li> <object type="text/sitemap">
               <param name="Name" value="Another Top">
               <param name="Local" value="top2.htm">
           </object>
      ...

    </ul>

Index file (.hhk)

Index files have same format as contents file except that ID params are ignored and sublists are not allowed.

### Input Filters

The wxHTML library provides a mechanism for reading and displaying files of many different file formats.

wxHtmlWindow::LoadPage can load not only HTML files but any known file. To make a file type known to wxHtmlWindow you must create a wxHtmlFilter filter and register it using wxHtmlWindow::AddFilter.

### Cells and Containers

This article describes mechanism used by wxHtmlWinParser and wxHtmlWindow to parse and display HTML documents.

Cells

You can divide any text (or HTML) into small fragments. Let's call these fragments cells. Cell is for example one word, horizontal line, image or any other part of document. Each cell has width and height (except special "magic" cells with zero dimensions - e.g. colour changers or font changers).

See wxHtmlCell.

Containers

Container is kind of cell that may contain sub-cells. Its size depends on number and sizes of its sub-cells (and also depends on width of window).

See wxHtmlContainerCell, wxHtmlCell::Layout.

Using Containers in Tag Handler

wxHtmlWinParser provides a user-friendly way of managing containers. It is based on the idea of opening and closing containers.

Use OpenContainer to open new a container within an already opened container. This new container is a sub-container of the old one. (If you want to create a new container with the same depth level you can call `CloseContainer(); OpenContainer();`.)

Use CloseContainer to close the container. This doesn't create a new container with same depth level but it returns "control" to the parent container.

It is clear there must be same number of calls to OpenContainer as to CloseContainer...

Example

This code creates a new paragraph (container at same depth level) with "Hello, world!":

    m_WParser -> CloseContainer();
    c = m_WParser -> OpenContainer();

    m_WParser -> AddWord("Hello, ");
    m_WParser -> AddWord("world!");

    m_WParser -> CloseContainer();
    m_WParser -> OpenContainer();

You can see that there was opened container before running the code. We closed it, created our own container, then closed our container and opened new container. The result was that we had same depth level after executing. This is general rule that should be followed by tag handlers: leave depth level of containers unmodified (in other words, number of OpenContainer and CloseContainer calls should be same within HandleTag's body).

### Tag Handlers

The wxHTML library provides architecture of pluggable tag handlers. Tag handler is class that understands particular HTML tag (or tags) and is able to interpret it.

wxHtmlWinParser has static table of modules. Each module contains one or more tag handlers. Each time a new wxHtmlWinParser object is constructed all modules are scanned and handlers are added to wxHtmlParser's list of available handlers (note: wxHtmlParser's list is non-static).

How it works

Common tag handler's HandleTag method works in four steps:

1. Save state of parent parser into local variables
2. Change parser state according to tag's params
3. Parse text between the tag and paired ending tag (if present)
4. Restore original parser state

See wxHtmlWinParser for methods for modifying parser's state. In general you can do things like opening/closing containers, changing colors, fonts etc.

Providing own tag handlers

You should create new .cpp file and place following lines into it:

    #include <mod_templ.h>
    #include <forcelink.h>
    FORCE_LINK_ME(yourmodulefilenamewithoutcpp)

Then you must define handlers and one module.

Tag handlers

The handler is derived from wxHtmlWinTagHandler (or directly from wxHtmlTagHandler)

You can use set of macros to define the handler (see src/html/m_*.cpp files for details). Handler definition must start with TAG_HANDLER_BEGIN macro and end with TAG_HANDLER_END macro. I strongly recommend to have a look at include/wxhtml/mod_templ.h file. Otherwise you won't understand the structure of macros. See macros reference:

TAG_HANDLER_BEGIN(name, tags)

Starts handler definition. name is handler identifier (in fact part of class name), tags is string containing list of tags supported by this handler (in uppercase). This macro derives new class from wxHtmlWinTagHandler and implements it is GetSupportedTags method.

Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")

TAG_HANDLER_VARS

This macro starts block of variables definitions. (Variables are identical to class attributes.) Example:

    TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
        TAG_HANDLER_VARS
            int my_int_var;
    	wxString something_else;
    TAG_HANDLER_END(VARS_ONLY)

This macro is used only in rare cases.

TAG_HANDLER_CONSTR(name)

This macro supplies object constructor. name is same name as the one from TAG_HANDLER_BEGIN macro. Body of constructor follow after this macro (you must use and ). Example:

    TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG")
        TAG_HANDLER_VARS
            int my_int_var;
        TAG_HANDLER_CONSTR(vars2)
            { // !!!!!!
    	    my_int_var = 666;
    	} // !!!!!!
    TAG_HANDLER_END(VARS2)

Never used in wxHTML :-)

TAG_HANDLER_PROC(varib)

This is very important macro. It defines HandleTag method. varib is name of parameter passed to the method, usually tag. Body of method follows after this macro. Note than you must use and ! Example:

    TAG_HANDLER_BEGIN(TITLE, "TITLE")
        TAG_HANDLER_PROC(tag)
            {
    	    printf("TITLE found...\n");
    	}
    TAG_HANDLER_END(TITLE)

TAG_HANDLER_END(name)

Ends definition of tag handler name.

Tags Modules

You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and TAGS_MODULE_END to inherit new module from wxHtmlTagsModule and to create instance of it. See macros reference:

TAGS_MODULE_BEGIN(modname)

Begins module definition. modname is part of class name and must be unique.

TAGS_MODULE_ADD(name)

Adds the handler to this module. name is the identifier from TAG_HANDLER_BEGIN.

TAGS_MODULE_END(modname)

Ends the definition of module.

Example:

    TAGS_MODULE_BEGIN(Examples)
        TAGS_MODULE_ADD(VARS_ONLY)
        TAGS_MODULE_ADD(VARS2)
        TAGS_MODULE_ADD(TITLE)
    TAGS_MODULE_END(Examples)

### Tags supported by wxHTML

wxHTML is not full implementation of HTML standard. Instead, it supports most common tags so that it is possible to display simple HTML documents with it. (For example it works fine with pages created in Netscape Composer or generated by tex2rtf).

Following tables list all tags known to wxHTML, together with supported parameters. A tag has general form of `<tagname param_1 param_2 ... param_n>` where param_i is either `paramname="paramvalue"` or `paramname=paramvalue` - these two are equivalent. Unless stated otherwise, wxHTML is case-insensitive.

Table of common parameter values

We will use these substitutions in tags descriptions:

    [alignment]     CENTER
                    LEFT
                    RIGHT
                    JUSTIFY

    [v_alignment]   TOP
                    BOTTOM
                    CENTER

    [color]         HTML 4.0-compliant colour specification

    [fontsize]      -2
                    -1
                    +0
                    +1
                    +2
                    +3
                    +4
                     1
                     2
                     3
                     4
                     5
                     6
                     7

    [pixels]        integer value that represents dimension in pixels

    [percent]       i%
                    where i is integer

    [url]           an URL

    [string]        text string

    [coords]        c(1),c(2),c(3),...,c(n)
                    where c(i) is integer

List of supported tags

    A               NAME=[string]
                    HREF=[url]
                    TARGET=[target window spec]
    ADDRESS
    AREA            SHAPE=POLY
                    SHAPE=CIRCLE
                    SHAPE=RECT
                    COORDS=[coords]
                    HREF=[url]
    B
    BIG
    BLOCKQUOTE
    BODY            TEXT=[color]
                    LINK=[color]
                    BGCOLOR=[color]
    BR              ALIGN=[alignment]
    CENTER
    CITE
    CODE
    DD
    DIV             ALIGN=[alignment]
    DL
    DT
    EM
    FONT            COLOR=[color]
                    SIZE=[fontsize]
                    FACE=[comma-separated list of facenames]
    HR              ALIGN=[alignment]
                    SIZE=[pixels]
                    WIDTH=[percent|pixels]
                    NOSHADE
    H1
    H2
    H3
    H4
    H5
    H6
    I
    IMG             SRC=[url]
                    WIDTH=[pixels]
                    HEIGHT=[pixels]
                    ALIGN=TEXTTOP
                    ALIGN=CENTER
                    ALIGN=ABSCENTER
                    ALIGN=BOTTOM
                    USEMAP=[url]
    KBD
    LI
    MAP             NAME=[string]
    META            HTTP-EQUIV="Content-Type"
                    CONTENT=[string]
    OL
    P               ALIGN=[alignment]
    PRE
    SAMP
    SMALL
    STRIKE
    STRONG
    SUB
    SUP
    TABLE           ALIGN=[alignment]
                    WIDTH=[percent|pixels]
                    BORDER=[pixels]
                    VALIGN=[v_alignment]
                    BGCOLOR=[color]
                    CELLSPACING=[pixels]
                    CELLPADDING=[pixels]
    TD              ALIGN=[alignment]
                    VALIGN=[v_alignment]
                    BGCOLOR=[color]
                    WIDTH=[percent|pixels]
                    COLSPAN=[pixels]
                    ROWSPAN=[pixels]
                    NOWRAP
    TH              ALIGN=[alignment]
                    VALIGN=[v_alignment]
                    BGCOLOR=[color]
                    WIDTH=[percent|pixels]
                    COLSPAN=[pixels]
                    ROWSPAN=[pixels]
    TITLE
    TR              ALIGN=[alignment]
                    VALIGN=[v_alignment]
                    BGCOLOR=[color]
    TT
    U
    UL