1\subsection{Tag Handlers}\label{handlers}
2
3The wxHTML library provides architecture of pluggable {\it tag handlers}.
4Tag handler is class that understands particular HTML tag (or tags) and is
5able to interpret it.
6
7\helpref{wxHtmlWinParser}{wxhtmlwinparser} has static table of {\bf modules}.
8Each module contains one or more tag handlers. Each time a new wxHtmlWinParser
9object is constructed all modules are scanned and handlers are added
10to wxHtmlParser's list of available handlers (note: wxHtmlParser's list
11is non-static).
12
13\wxheading{How it works}
14
15Common tag handler's \helpref{HandleTag}{wxhtmltaghandlerhandletag} method
16works in four steps:
17
18\begin{enumerate}\itemsep=0pt
19\item Save state of parent parser into local variables
20\item Change parser state according to tag's params
21\item Parse text between the tag and paired ending tag (if present)
22\item Restore original parser state
23\end{enumerate}
24
25See \helpref{wxHtmlWinParser}{wxhtmlwinparser} for methods for modifying
26parser's state. In general you can do things like opening/closing containers,
27changing colors, fonts etc.
28
29\wxheading{Providing own tag handlers}
30
31You should create new .cpp file and place following lines into it: 
32
33\begin{verbatim}
34#include <mod_templ.h>
35#include <forcelink.h>
36FORCE_LINK_ME(yourmodulefilenamewithoutcpp)
37\end{verbatim}
38
39Then you must define handlers and one module.
40
41\wxheading{Tag handlers}
42
43The handler is derived from \helpref{wxHtmlWinTagHandler}{wxhtmlwintaghandler}
44(or directly from \helpref{wxHtmlTagHandler}{wxhtmltaghandler})
45
46You can use set of macros to define the handler (see src/html/m\_*.cpp files
47for details). Handler definition must start with {\bf TAG\_HANDLER\_BEGIN} macro
48and end with {\bf TAG\_HANDLER\_END} macro. I strongly recommend to have a look
49at {\it include/wxhtml/mod\_templ.h} file. Otherwise you won't understand
50the structure of macros. See macros reference:
51
52{\bf TAG\_HANDLER\_BEGIN}({\it name}, {\it tags})
53
54Starts handler definition. {\it name} is handler identifier (in fact
55part of class name), {\it tags} is string containing list of tags
56supported by this handler (in uppercase). This macro derives new class from
57wxHtmlWinTagHandler and implements it is 
58\helpref{GetSupportedTags}{wxhtmltaghandlergetsupportedtags} method.
59
60Example: TAG\_HANDLER\_BEGIN(FONTS, "B,I,U,T")
61
62{\bf TAG\_HANDLER\_VARS}
63
64This macro starts block of variables definitions. (Variables are identical
65to class attributes.) Example:
66
67\begin{verbatim}
68TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
69    TAG_HANDLER_VARS
70        int my_int_var;
71	wxString something_else;
72TAG_HANDLER_END(VARS_ONLY)
73\end{verbatim}
74
75This macro is used only in rare cases.
76
77{\bf TAG\_HANDLER\_CONSTR}({\it name})
78
79This macro supplies object constructor. {\it name} is same name as the one
80from TAG\_HANDLER\_BEGIN macro. Body of constructor follow after
81this macro (you must use { and } ). Example:
82
83\begin{verbatim}
84TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG")
85    TAG_HANDLER_VARS
86        int my_int_var;
87    TAG_HANDLER_CONSTR(vars2)
88        { // !!!!!!
89	    my_int_var = 666;
90	} // !!!!!!
91TAG_HANDLER_END(VARS2)
92\end{verbatim}
93
94Never used in wxHTML :-)
95
96{\bf TAG\_HANDLER\_PROC}({\it varib})
97
98This is very important macro. It defines \helpref{HandleTag}{wxhtmltaghandlerhandletag}
99method. {\it varib} is name of parameter passed to the method, usually
100{\it tag}. Body of method follows after this macro.
101Note than you must use { and } ! Example:
102
103\begin{verbatim}
104TAG_HANDLER_BEGIN(TITLE, "TITLE")
105    TAG_HANDLER_PROC(tag)
106        {
107	    printf("TITLE found...\n");
108	}
109TAG_HANDLER_END(TITLE)
110\end{verbatim}
111
112{\bf TAG\_HANDLER\_END}({\it name})
113
114Ends definition of tag handler {\it name}. 
115
116\wxheading{Tags Modules}
117
118You can use set of 3 macros TAGS\_MODULE\_BEGIN, TAGS\_MODULE\_ADD and 
119TAGS\_MODULE\_END to inherit new module from
120\helpref{wxHtmlTagsModule}{wxhtmltagsmodule} and to create instance of it.
121See macros reference:
122
123{\bf TAGS\_MODULE\_BEGIN}({\it modname})
124
125Begins module definition. {\it modname} is part of class name and must
126be unique.
127
128{\bf TAGS\_MODULE\_ADD}({\it name})
129
130Adds the handler to this module. {\it name} is the identifier from
131TAG\_HANDLER\_BEGIN.
132
133{\bf TAGS\_MODULE\_END}({\it modname})
134
135Ends the definition of module.
136
137{\bf Example:}
138
139\begin{verbatim}
140TAGS_MODULE_BEGIN(Examples)
141    TAGS_MODULE_ADD(VARS_ONLY)
142    TAGS_MODULE_ADD(VARS2)
143    TAGS_MODULE_ADD(TITLE)
144TAGS_MODULE_END(Examples)
145\end{verbatim}
146
147