documented Harm's changes to wxHTML help

[wxWidgets.git] / docs / latex / wx / htmlhand.tex

\membersection{Tag Handlers}\label{handlers}

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

\helpref{wxHtmlWinParser}{wxhtmlwinparser} has static table of {\bf 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).

\wxheading{How it works}

Common tag handler's \helpref{HandleTag}{wxhtmltaghandlerhandletag} method
works in four steps:

\begin{enumerate}\itemsep=0pt
\item Save state of parent parser into local variables
\item Change parser state according to tag's params
\item Parse text between the tag and paired ending tag (if present)
\item Restore original parser state
\end{enumerate}

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

\wxheading{Providing own tag handlers}

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

\begin{verbatim}
#include <mod_templ.h>
#include <forcelink.h>
FORCE_LINK_ME(yourmodulefilenamewithoutcpp)
\end{verbatim}

Then you must define handlers and one module.

\wxheading{Tag handlers}

The handler is derived from \helpref{wxHtmlWinTagHandler}{wxhtmlwintaghandler}
(or directly from \helpref{wxHtmlTagHandler}{wxhtmltaghandler})

You can use set of macros to define the handler (see src/mod\_*.cpp files
for details). Handler definition must start with {\bf TAG\_HANDLER\_BEGIN} macro
and end with {\bf TAG\_HANDLER\_END} macro. I strongly recommend to have a look
at {\it include/wxhtml/mod\_templ.h} file. Otherwise you won't understand
the structure of macros. See macros reference:

{\bf TAG\_HANDLER\_BEGIN}({\it name}, {\it tags})

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

Example: TAG\_HANDLER\_BEGIN(FONTS, "B,I,U,T")

{\bf TAG\_HANDLER\_VARS}

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

\begin{verbatim}
TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
    TAG_HANDLER_VARS
        int my_int_var;
	wxString something_else;
TAG_HANDLER_END(VARS_ONLY)
\end{verbatim}

This macro is used only in rare cases.

{\bf TAG\_HANDLER\_CONSTR}({\it name})

This macro supplies object constructor. {\it name} is same name as the one
from TAG\_HANDLER\_BEGIN macro. Body of constructor follow after
this macro (you must use { and } ). Example:

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

Never used in wxHTML :-)

{\bf TAG\_HANDLER\_PROC}({\it varib})

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

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

{\bf TAG\_HANDLER\_END}({\it name})

Ends definition of tag handler {\it name}. 


\wxheading{Tags Modules}

You can use set of 3 macros TAGS\_MODULE\_BEGIN, TAGS\_MODULE\_ADD and 
TAGS\_MODULE\_END to inherit new module from
\helpref{wxHtmlTagsModule}{wxhtmltagsmodule} and to create instance of it.
See macros reference:

{\bf TAGS\_MODULE\_BEGIN}({\it modname})

Begins module definition. {\it modname} is part of class name and must
be unique.

{\bf TAGS\_MODULE\_ADD}({\it name})

Adds the handler to this module. {\it name} is the identifier from
TAG\_HANDLER\_BEGIN.

{\bf TAGS\_MODULE\_END}({\it modname})

Ends the definition of module.

{\bf Example:}

\begin{verbatim}
TAGS_MODULE_BEGIN(Examples)
    TAGS_MODULE_ADD(VARS_ONLY)
    TAGS_MODULE_ADD(VARS2)
    TAGS_MODULE_ADD(TITLE)
TAGS_MODULE_END(Examples)
\end{verbatim}