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