docs/latex/wx/htmlhand.tex

   1 \section{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/mod\_*.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
 117 \wxheading{Tags Modules}
 118
 119 You can use set of 3 macros TAGS\_MODULE\_BEGIN, TAGS\_MODULE\_ADD and
 120 TAGS\_MODULE\_END to inherit new module from
 121 \helpref{wxHtmlTagsModule}{wxhtmltagsmodule} and to create instance of it.
 122 See macros reference:
 123
 124 {\bf TAGS\_MODULE\_BEGIN}({\it modname})
 125
 126 Begins module definition. {\it modname} is part of class name and must
 127 be unique.
 128
 129 {\bf TAGS\_MODULE\_ADD}({\it name})
 130
 131 Adds the handler to this module. {\it name} is the identifier from
 132 TAG\_HANDLER\_BEGIN.
 133
 134 {\bf TAGS\_MODULE\_END}({\it modname})
 135
 136 Ends the definition of module.
 137
 138 {\bf Example:}
 139
 140 \begin{verbatim}
 141 TAGS_MODULE_BEGIN(Examples)
 142     TAGS_MODULE_ADD(VARS_ONLY)
 143     TAGS_MODULE_ADD(VARS2)
 144     TAGS_MODULE_ADD(TITLE)
 145 TAGS_MODULE_END(Examples)
 146 \end{verbatim}
 147