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