42d306a033
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4396 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
148 lines
4.3 KiB
TeX
148 lines
4.3 KiB
TeX
\section{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}
|
|
|